feat(ts-sdk): family-adapter batch architecture + math standards-alignment family

[adnanrhussain]

Summary

Refactors the batch-evaluation tool from a hardcoded single "evaluator group" into an evaluator-family adapter architecture, and lands math standards-alignment as the first non-text family. This is the base PR of a stack — output projections (JSON/HTML/CSV) and the CLI flow (family/member selection, --yes/non-interactive, platform-key resolution) follow in stacked PRs.

Why

The batch tool assumed every evaluator was homogeneous: evaluate(text, grade) → {score, reasoning}, CSV requiring text+grade, one fixed group, a QTC-specific report. Math standards alignment breaks all of those (3-arg evaluate(question, statementCode, jurisdiction), structured per-learning-component output, a platform/KG key). Rather than special-case it, this introduces a family seam so the next family (feedback) slots in without core changes.

What changed

• src/batch/families/ (new): EvaluatorFamily interface (members, columns, required keys, createRunner, maxInputRows) + registry. family.ts also owns column normalization (normalizeRow, validateRequiredColumns) with alias + default support.
• BatchEvaluator is now family-driven: it owns orchestration (concurrency, cancellation, per-task error isolation, timing) and delegates how to invoke an evaluator to the family runner. evaluate() accepts a family id or a family object.
• QTC family: the six text-complexity evaluators, behavior unchanged (all prior tests pass).
• Standards family: math-standards-alignment. Maps to a {alignedCount, totalCount, learningComponents[]} payload; jurisdiction defaults to Multi-State; platform key hard-required. Column aliases (ccss_standard→statementCode, text→question).
• parseCSV is now schema-agnostic (reads all columns); family owns validation/aliases/defaults. One malformed row → an error result, not a whole-run abort.
• KG caching: confirmed the client already promise-caches by statementCode:jurisdiction+UUID; the standards runner reuses one client across rows, so N items over M unique standards do M fetches. Locked with a positive cache-hit test.

Input-shape change

BatchInput moves from { text, grade, rowIndex, originalRow } to { rowIndex, columns, originalRow },
and parseCSV returns the new shape. Both are public via the ./batch subpath export, so a consumer
reading row.text gets undefined (plus TS2339) and a hand-built row hits the shape check below. No
in-repo consumer outside src/batch/ is affected; the demo server is pinned to the published ^0.8.0.

A malformed row is now rejected with a message naming the expected shape and the migration, rather than
the bare TypeError: Cannot convert undefined or null to object that Object.keys(undefined) produced.

Not in this PR (stacked follow-ups)

• Output projections: JSON (joinable per-item verdicts + per-LC detail), CSV (flat), standards HTML verdict-browser.
• CLI: family→member selection, --model shortcodes, --platform-api-key, --yes/non-interactive. (Standards family is not yet reachable from the CLI — programmatic API only.)

Testing

• 342 unit tests pass; typecheck + lint clean (0 errors).
• QTC behavior preserved (existing suites unchanged in intent; internal-poking tests rewritten to assert public behavior / use a stub family).

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[Copilot]

Pull request overview

Refactors the TypeScript batch-evaluation SDK from a single hardcoded evaluator-group model into a family/adapter architecture, enabling heterogeneous evaluator contracts and adding a new math standards-alignment family.

Changes:

• Introduces EvaluatorFamily/FamilyRunner abstractions with a registry and shared column normalization (aliases/defaults + required-column validation).
• Updates BatchEvaluator orchestration to be family-driven (rows × selected members), adds payload support for structured outputs, and makes CSV parsing schema-agnostic.
• Adds the math-standards-alignment family (KG-backed + Anthropic by default) and expands/rewrites unit/integration tests accordingly.

Reviewed changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
sdks/typescript/src/batch/evaluator.ts	Refactors batch execution to use families/runners; updates evaluate() signature and row normalization flow.
sdks/typescript/src/batch/families/family.ts	Adds the family interfaces plus column validation/normalization and member resolution helpers.
sdks/typescript/src/batch/families/registry.ts	Adds a registry for available evaluator families.
sdks/typescript/src/batch/families/qtc.ts	Implements the existing text-complexity family using the new runner abstraction.
sdks/typescript/src/batch/families/standards.ts	Adds the math standards-alignment family and runner integration.
sdks/typescript/src/batch/csv.ts	Makes CSV parsing schema-agnostic and returns column bags instead of fixed text/grade.
sdks/typescript/src/batch/types.ts	Updates batch types for family rows/tasks and adds payload + new config fields.
sdks/typescript/src/batch/index.ts	Re-exports new family APIs and types from the batch entrypoint.
sdks/typescript/src/batch/cli.ts	Adjusts CLI invocation to the new evaluate(..., { onProgress }) calling convention.
sdks/typescript/tests/unit/batch/csv-parsing.test.ts	Updates tests for schema-agnostic CSV parsing behavior.
sdks/typescript/tests/unit/batch/column-normalization.test.ts	Adds new tests for alias/default/required-column normalization and member resolution.
sdks/typescript/tests/unit/batch/limits.test.ts	Rewrites orchestration tests to use stub families instead of internal state poking.
sdks/typescript/tests/unit/batch/llm-provider.test.ts	Updates BYO-provider tests to assert behavior via public results.
sdks/typescript/tests/integration/batch.integration.test.ts	Updates integration usage to the new options object signature and new input shape.
sdks/typescript/tests/unit/knowledge-graph/client.test.ts	Adds a positive test to ensure successful KG lookups are cached.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.