feat(entities): add grouped count queries

[callingmedic911]

Summary

• add bounded, filtered entity counts grouped by a scalar field
• expose optional grouped metadata from entity lists and EntityClient.count_by()
• validate group fields, normalize cross-dialect keys, and update OpenAPI contracts

Test plan

• 97 passed, 1 skipped across focused repository, API, and client suites
• Ruff check and format-check on all changed handwritten Python
• focused entity-service type checks
• final whole-branch code review with no blocking findings

Context

This is an independent platform capability proposed while reviewing #757. It intentionally contains no Insights or Studio consumer changes.

Summary by CodeRabbit

• New Features
  • Added an optional count_by parameter to the entities listing endpoint to return counts grouped by a direct string data field.
  • Listing responses now include group_counts (group key → integer count) when count_by is provided.
  • Added client support to request and return grouped counts, including validation for unsupported grouping fields and clear errors.
• Tests
  • Added coverage for grouped counting behavior, error handling, and group-cardinality limits.

[github-actions]

Suite	Lines Covered	Line Rate	Branch Rate
Unit Tests	27157/34869	77.9%	62.1%
Integration Tests	15968/33581	47.5%	20.0%

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 30944df7-ba3e-44b1-aea7-115e2e26cedb

📥 Commits

Reviewing files that changed from the base of the PR and between 91f68e7 and 43f997a.

⛔ Files ignored due to path filters (1)

• sdk/python/nemo-platform/.nmpcontext/openapi.yaml is excluded by !sdk/**

📒 Files selected for processing (3)

• openapi/ga/individual/platform.openapi.yaml
• openapi/ga/openapi.yaml
• openapi/openapi.yaml

🚧 Files skipped from review as they are similar to previous changes (3)

• openapi/ga/openapi.yaml
• openapi/openapi.yaml
• openapi/ga/individual/platform.openapi.yaml

---

📝 Walkthrough

Walkthrough

Changes

Entity listing now accepts count_by for direct string data fields and returns grouped counts. Repository, endpoint, OpenAPI, plugin client, integration tests, and repository tests support aggregation, filtering, validation, and cardinality limits.

Entity grouped counts

Layer / File(s)	Summary
API contracts openapi/..., services/core/entities/src/.../endpoints.py	OpenAPI and Python response contracts add count_by and group_counts.
Repository grouped counting services/core/entities/src/.../repository/entity.py, services/core/entities/src/.../repository/sqlalchemy/entity.py, services/core/entities/tests/repository/*	The repository groups string-valued direct JSON fields, applies filters, validates fields, and enforces a group limit.
Listing endpoint integration services/core/entities/src/.../endpoints.py, services/core/entities/tests/integration/*	The endpoint applies effective workspace filtering, returns grouped counts, and maps invalid grouping requests to HTTP 400.
Client count_by surface packages/nemo_platform_plugin/src/.../entities.py, packages/nemo_platform_plugin/tests/test_entity_client.py	The plugin client validates fields, serializes filters, requests grouped counts, and handles missing response metadata.

Sequence Diagram(s)

sequenceDiagram
  participant EntityClient
  participant list_entities
  participant SQLAlchemyEntityRepository
  EntityClient->>list_entities: Request entities with count_by and filter
  list_entities->>SQLAlchemyEntityRepository: List filtered entities
  list_entities->>SQLAlchemyEntityRepository: Count entities by direct string field
  SQLAlchemyEntityRepository-->>list_entities: Entities and group counts
  list_entities-->>EntityClient: EntitiesPage with group_counts

Loading

Suggested labels: feat

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: adding grouped count queries for entities.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch entity-count-by/aditypandey

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In
`@services/core/entities/src/nmp/core/entities/app/repository/sqlalchemy/entity.py`:
- Around line 219-220: Replace the cast-and-trim logic in the grouped-value path
of the entity repository with the dialect-aware JSON scalar extractor so escaped
quotes and backslashes decode correctly. In
services/core/entities/src/nmp/core/entities/app/repository/sqlalchemy/entity.py:219-220,
update the expression assigned to group_column while preserving
raw_group_column. Add a regression case in
services/core/entities/tests/repository/test_entity_group_counts.py:18-26
covering quoted and backslash-containing insight_id values and asserting their
decoded grouped counts.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: cd7731cc-6957-4811-adf5-a8179070c190

📥 Commits

Reviewing files that changed from the base of the PR and between 82bcdae and c185259.

📒 Files selected for processing (10)

• openapi/ga/individual/platform.openapi.yaml
• openapi/ga/openapi.yaml
• openapi/openapi.yaml
• packages/nemo_platform_plugin/src/nemo_platform_plugin/entities.py
• packages/nemo_platform_plugin/tests/test_entity_client.py
• services/core/entities/src/nmp/core/entities/api/v2/entities/endpoints.py
• services/core/entities/src/nmp/core/entities/app/repository/entity.py
• services/core/entities/src/nmp/core/entities/app/repository/sqlalchemy/entity.py
• services/core/entities/tests/integration/test_generic_entities.py
• services/core/entities/tests/repository/test_entity_group_counts.py

[walston]

You've got a couple failing CI checks, and Coderabbit called out an apparently valid(?) issue.

[maxdubrinsky]

Looks good to me once tests are passing.

Features like this have been pondered in the past, and we might want to look at expanding this out into a more comprehensive set of grouping functions. Don't think we need to go full aggregation pipelines, but I could see other operations being useful on the plugin/studio side.