refactor(intake): add ClickHouse repository boundary

[BrianNewsom]

Summary

• introduce a domain-facing session repository interface and ClickHouse implementation
• add a named, parameterized query executor with result mapping, error translation, and query timing
• restrict runtime table identifiers to a closed enum and prevent new raw-client imports outside the migration allowlist
• migrate session dependency wiring without changing its SQL or API behavior

Stacked on #924.

Validation

• Intake Ruff lint and format checks
• focused ty check for changed source and tests
• complete Intake unit suite: 213 passed
• ClickHouse 26.3 session integration test: 1 passed

Summary by CodeRabbit

• Improvements
  • Refreshed evaluation session and rollup reads for more consistent data mapping and metrics (cost, latency, tokens, evaluator scores).
  • Improved ClickHouse query execution with named query handling, safer parameter binding, and clearer error reporting.
  • Updated dependency wiring to use the ClickHouse-backed session/rollup implementations when available.
• Bug Fixes
  • Fixed/strengthened metric sorting behavior, including bounded large sort safeguards and correct hydration ordering.
  • Improved protections against unsafe session inputs and improved handling when no results exist.
• Tests
  • Expanded integration and repository tests for sorting, filtering, empty results, and query/error behavior.
  • Added coverage for ClickHouse executor and import-boundary constraints.

[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: 5f1940e7-3048-43fb-aabe-e69c54e2f646

📥 Commits

Reviewing files that changed from the base of the PR and between c8829b7 and 9b90990.

📒 Files selected for processing (5)

• services/intake/src/nmp/intake/api/v2/experiments/endpoints.py
• services/intake/src/nmp/intake/api/v2/experiments/schemas.py
• services/intake/src/nmp/intake/repository/clickhouse/evaluation_rollup.py
• services/intake/src/nmp/intake/repository/evaluation_rollup.py
• services/intake/tests/test_experiment_rollup_repository.py

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

• services/intake/src/nmp/intake/repository/evaluation_rollup.py
• services/intake/src/nmp/intake/api/v2/experiments/schemas.py
• services/intake/tests/test_experiment_rollup_repository.py
• services/intake/src/nmp/intake/api/v2/experiments/endpoints.py
• services/intake/src/nmp/intake/repository/clickhouse/evaluation_rollup.py

---

📝 Walkthrough

Walkthrough

ClickHouse access now runs through a typed executor and registered table names. Evaluation session and rollup contracts are separated from implementations, dependencies use executor-backed repositories, and tests cover query mapping, parameter binding, sorting, filtering, and import boundaries.

Changes

ClickHouse repository migration

Layer / File(s)	Summary
Typed ClickHouse execution boundary services/intake/src/nmp/intake/repository/clickhouse/executor.py, services/intake/src/nmp/intake/repository/clickhouse/tables.py	Named queries, mapped results, scalar fetching, error translation, timing logs, and validated table qualification are centralized.
Repository contracts and implementations services/intake/src/nmp/intake/repository/evaluation_*.py, services/intake/src/nmp/intake/repository/session.py, services/intake/src/nmp/intake/repository/clickhouse/*	Evaluation read models and repository interfaces are separated from ClickHouse implementations, which now use ClickHouseExecutor.
Executor-based dependency wiring services/intake/src/nmp/intake/api/v2/experiments/*, services/intake/src/nmp/intake/spans/api/dependencies.py, services/intake/src/nmp/intake/spans/service.py	Experiment and span dependencies construct ClickHouse-specific repositories through the shared executor and import domain contracts from the repository layer.
Executor and repository behavior validation services/intake/tests/test_clickhouse_*.py, services/intake/tests/test_*repository.py, services/intake/tests/integration/spans/*	Tests validate executor behavior, parameterized queries, metric sorting, session filtering, rollups, session mapping, and raw-client import restrictions.

Sequence Diagram(s)

sequenceDiagram
  participant API
  participant DependencyProvider
  participant ClickHouseRepository
  participant ClickHouseExecutor
  participant ClickHouse
  API->>DependencyProvider: request repository dependency
  DependencyProvider->>ClickHouseExecutor: create executor from client
  DependencyProvider->>ClickHouseRepository: construct repository with executor
  API->>ClickHouseRepository: request sessions or rollups
  ClickHouseRepository->>ClickHouseExecutor: execute named query
  ClickHouseExecutor->>ClickHouse: run parameterized SQL
  ClickHouse-->>ClickHouseExecutor: return rows
  ClickHouseExecutor-->>ClickHouseRepository: return mapped dictionaries
  ClickHouseRepository-->>API: return domain read model

Loading

Possibly related PRs

• NVIDIA-NeMo/nemo-platform#612: Refactors overlapping experiment API dependency and schema contracts.
• NVIDIA-NeMo/nemo-platform#744: Adds related executor-backed session repository wiring.
• NVIDIA-NeMo/nemo-platform#780: Modifies the related evaluation-session sorting flow.

Suggested reviewers: shanaiabuggy

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 9.43% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title matches the main change: introducing a ClickHouse repository boundary and related refactor work.
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 docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch clickhouse-dao-foundation/brnewsom

---

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

[github-actions]

Suite	Lines Covered	Line Rate	Branch Rate
Unit Tests	27392/35142	78.0%	62.3%
Integration Tests	16051/33854	47.4%	19.9%