@moltzap/evals that runs against every runtime the
suite supports and grades with a versioned code grader.
The work is four files. Three of them fail to compile if you skip them; the
fourth fails silently, so do it in the order below.
Prerequisites
- A local checkout with dependencies installed.
- A scenario id nobody has used. Existing ids are
EVAL-005throughEVAL-034, with gaps;packages/evals/src/descriptions.tsis the list. - A decision about what a passing response looks like, precise enough to
write as a check. If the property needs a model to judge it, that is fine —
it becomes a
requiresJudgmentcheck and the case reportsundecideduntil a semantic tier resolves it.
Steps
1. Describe the case
Inpackages/evals/src/descriptions.ts:
expectedBehavior is prose a person reads. It is not executed. The checks in
step 2 are what actually run, so anything you claim here that no check
establishes will read as undecided in the report.
2. Write the grader
Inpackages/evals/src/graders.ts, import the description and add a grader.
Use oneResponseGrader for a single-turn episode or twoResponseGrader for a
two-turn one — they set expectedResponses for you.
GraderId must match `${string}.grader/v${number}` or it will not
typecheck. See the grading vocabulary reference
for every check constructor.
3. Define the evaluation
Inpackages/evals/src/evaluations.ts, add a defineEvalNNN function next to
its neighbours:
id is the simulator definition id and is versioned separately from the
grader id. Bump it when the episode changes, because a ledger recorded under
the old episode is no longer evidence for the new one.
Episode builders live in packages/evals/src/episodes.ts:
4. Register it
Still inpackages/evals/src/evaluations.ts, two edits:
Add the member to the EvaluationSuite interface:
defineEvaluationSuite:
5. Update the suite test
packages/evals/src/evaluations.test.ts asserts the exact key list:
Verification
evaluations.test.ts:
Troubleshooting
GradingRefused instead of a report. The evidence is not gradeable, not
the agent misbehaving. The detail field says which: the program did not
succeed, the target never became ready, or the selected-response count does
not match expectedResponses. A two-turn episode graded with
oneResponseGrader produces exactly this.
Every check reports undecided. Expected when the grader is a detector
plus requiresJudgment: a detector that finds nothing settles nothing. Add a
deciding check — exactFinalText or atMostWords — if the property is
mechanical.
The type error names GraderId. The grader id must be
`${string}.grader/v${number}`. "moltzap.eval-040.grader" has no
version and will not typecheck.
Nothing runs and nothing fails. Check step 4. A registered description
with no suite entry is invisible.
Related
- Grading vocabulary reference — every check constructor
- Code-first evaluations — suites, runtimes, and measurements
- Grading typed ledgers — what the ledger guarantees before grading