Skip to content

[refactor] Drop duplicate EvaluationRun type, align step-reference shape#5466

Draft
ardaerzin wants to merge 1 commit into
ts-chore/unify-span-typesfrom
ts-chore/dedupe-api-types
Draft

[refactor] Drop duplicate EvaluationRun type, align step-reference shape#5466
ardaerzin wants to merge 1 commit into
ts-chore/unify-span-typesfrom
ts-chore/dedupe-api-types

Conversation

@ardaerzin

Copy link
Copy Markdown
Contributor

Context

usePreviewEvaluations declared its own EvaluationRun interface while @agenta/entities/evaluationRun already had the canonical zod-derived one for the same entity. The local copy declared name, description, status, meta and flags as always-present, but the schema (which validates the actual payload) says the backend can send null for all of them. That gap is why #5464 had to hand-add updated_at to the local copy to keep it current, while the entities type already had it.

Changes

The local interface is deleted. Its two importers and the hook take EvaluationRun from @agenta/entities/evaluationRun. CandidateRun.status in CompareRunsMenu was widened to string | null to match.

Swapping surfaced drift inside @agenta/entities itself. The step-reference shape is declared in three places with three different types:

core/schema.ts   {id: string, slug?: string | null, version?: number | null}   <- validated
etl RunStep      {id: string, slug?: string,        version?: string}          <- version is a STRING
etl ColumnGroup  {id?: string, slug?: string}                                  <- id optional

The core schema is the boundary-validated truth, so it now exports EvaluationRunStepReference and both ETL declarations reference it instead of redeclaring it.

Scoped out, and why

The other two candidates in the original list did not survive verification. Neither is a swap I would make without changing behavior or inventing structure.

PreviewTestset is not the entities Testset. They describe different endpoints. PreviewTestset carries slug plus an embedded data.testcases; the entities Testset is lean metadata (id, name, description?, project_id?). Pointing one at the other would silently drop fields the UI reads.

PreviewTestCase does match Fern's TestcaseOutput (Fern's is a superset, all-optional). But web/oss cannot import the Fern client directly, and the entities testcase domain has no canonical testcase entity type to route it through. Adding one is reasonable follow-up work, not a drive-by.

OrganizationProvider has no entities domain at all. The EE response's settings is a free-form dict, while Fern's SsoProviderSettingsDto models the create-input (required client_id/issuer_url). Creating a whole entities domain for one settings interface is disproportionate to the drift risk.

Tests / notes

What to QA

Nothing user-visible. If you want a smoke check: the evaluation runs table and the compare-runs menu still list runs with their status and created date, and the eval run details table still renders columns (the step-reference type feeds column grouping).

…e shape

usePreviewEvaluations declared its own EvaluationRun while
@agenta/entities/evaluationRun already had the canonical zod-derived one.
The local copy over-declared requiredness (name/description/status/meta/flags
as non-null) where the schema says the backend can send null, so #5464 had to
hand-add updated_at to keep it current. Deleted it; the two importers and the
hook now take the type from the package.

Swapping surfaced drift inside @agenta/entities itself: the step-reference
shape was redeclared three times with different types. The core zod schema has
{id, slug?: string|null, version?: number|null}, while the ETL RunStep said
slug?: string and version?: STRING, and ColumnGroup.refs said id?: string.
Both now reference the exported EvaluationRunStepReference from the validated
schema. CandidateRun.status widened to match.

Scoped out, with reasons:
- PreviewTestset is NOT the entities Testset (different endpoint shape: it
  carries slug plus embedded data.testcases; entities Testset is lean
  metadata). PreviewTestCase does match Fern TestcaseOutput, but entities has
  no canonical testcase entity type to route it through yet.
- OrganizationProvider has no entities domain at all, and the response settings
  is a free-form dict while Fern's SsoProviderSettingsDto models create-input.
  Creating a domain for one interface is disproportionate.
@vercel

vercel Bot commented Jul 23, 2026

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
agenta-documentation Ready Ready Preview, Comment Jul 23, 2026 3:56pm

Request Review

@coderabbitai

coderabbitai Bot commented Jul 23, 2026

Copy link
Copy Markdown

Review Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 21166382-7f5f-459d-a4fa-1a553e773d1c

📥 Commits

Reviewing files that changed from the base of the PR and between 9301719 and bca0c66.

📒 Files selected for processing (7)
  • web/oss/src/components/EvalRunDetails/atoms/table/run.ts
  • web/oss/src/components/EvalRunDetails/components/CompareRunsMenu.tsx
  • web/oss/src/components/EvaluationRunsTablePOC/types.ts
  • web/oss/src/lib/hooks/usePreviewEvaluations/index.ts
  • web/oss/src/lib/hooks/usePreviewEvaluations/types.ts
  • web/packages/agenta-entities/src/evaluationRun/core/schema.ts
  • web/packages/agenta-entities/src/evaluationRun/etl/resolveMappings.ts

📝 Walkthrough

Summary by CodeRabbit

  • Improvements
    • Standardized evaluation run data handling across the application.
    • Improved compatibility when evaluation run statuses or step references are unavailable.
    • Ensured run comparisons, tables, and details use consistent evaluation run information.
    • Added support for richer step reference metadata, including identifiers, slugs, and versions.

Walkthrough

Changes

The PR centralizes EvaluationRun and step-reference types in agenta-entities, updates OSS evaluation run consumers to use them, and permits nullable candidate run statuses.

Evaluation run type consolidation

Layer / File(s) Summary
Canonical entity contracts
web/packages/agenta-entities/src/evaluationRun/core/schema.ts, web/packages/agenta-entities/src/evaluationRun/etl/resolveMappings.ts
Exports EvaluationRunStepReference from the schema and uses it for run step references and column group references.
OSS evaluation run migration
web/oss/src/lib/hooks/usePreviewEvaluations/types.ts, web/oss/src/lib/hooks/usePreviewEvaluations/index.ts, web/oss/src/components/EvalRunDetails/atoms/table/run.ts, web/oss/src/components/EvaluationRunsTablePOC/types.ts, web/oss/src/components/EvalRunDetails/components/CompareRunsMenu.tsx
Replaces the local EvaluationRun interface with the entity type across OSS modules and widens candidate run status to include null.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Title check ✅ Passed The title clearly reflects the main refactor: removing the duplicate EvaluationRun type and aligning step-reference shapes.
Description check ✅ Passed The description is detailed and directly matches the refactor, type alignment, and excluded follow-up candidates in the diff.
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 docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch ts-chore/dedupe-api-types

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

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

@ardaerzin

Copy link
Copy Markdown
Contributor Author

@coderabbitai review

@coderabbitai

coderabbitai Bot commented Jul 23, 2026

Copy link
Copy Markdown
✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant