@gaunt-sloth/batch 2.0.0-alpha.19

package/dist/evalTypes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"evalTypes.js","sourceRoot":"","sources":["../src/evalTypes.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;mGAImG;AACnG,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+export { buildMatrix } from '#src/matrix.js';
+export { bindCellContent } from '#src/interpolate.js';
+export { parseOverFile } from '#src/parseOver.js';
+export { runBatchMatrix, buildBatchSummary } from '#src/BatchRunner.js';
+export { writeBatchOutput } from '#src/output.js';
+export type { BatchRunnerOptions, BatchSummary, CellResult, CellRunOutcome, MatrixCell, MatrixRow, RunCellFn, } from '#src/types.js';
+export { DEFAULT_CONCURRENCY } from '#src/types.js';
+export { parseEvalSuite } from '#src/evalSuite.js';
+export { runDeterministicChecks } from '#src/deterministicChecks.js';
+export { judgeEvalCase, buildJudgeMessages, EvalVerdictSchema, EVAL_JUDGE_DEFAULT_TIMEOUT_MS, } from '#src/judge.js';
+export type { EvalJudgeVerdict } from '#src/judge.js';
+export { runEvalSuite } from '#src/evalRunner.js';
+export { writeEvalOutput } from '#src/evalOutput.js';
+export type { DeterministicCheckResult, EvalCase, EvalCaseResult, EvalSuite, EvalSuiteSummary, EvalTarget, JudgeFn, JudgeOutcome, JudgeVerdict, } from '#src/evalTypes.js';
+export type { RunEvalSuiteOptions } from '#src/evalRunner.js';
+export { DEFAULT_EVAL_PASS_THRESHOLD } from '#src/evalTypes.js';
+export { runWorkflow } from '#src/workflow/runWorkflow.js';
+export type { WorkflowAgentOptions, WorkflowContext, RunWorkflowOptions, } from '#src/workflow/runWorkflow.js';

package/dist/index.js

@@ -0,0 +1,17 @@
+export { buildMatrix } from '#src/matrix.js';
+export { bindCellContent } from '#src/interpolate.js';
+export { parseOverFile } from '#src/parseOver.js';
+export { runBatchMatrix, buildBatchSummary } from '#src/BatchRunner.js';
+export { writeBatchOutput } from '#src/output.js';
+export { DEFAULT_CONCURRENCY } from '#src/types.js';
+// BATCH-2 — `gth eval`'s suite parsing, deterministic checks, judge, runner, and output writer.
+export { parseEvalSuite } from '#src/evalSuite.js';
+export { runDeterministicChecks } from '#src/deterministicChecks.js';
+export { judgeEvalCase, buildJudgeMessages, EvalVerdictSchema, EVAL_JUDGE_DEFAULT_TIMEOUT_MS, } from '#src/judge.js';
+export { runEvalSuite } from '#src/evalRunner.js';
+export { writeEvalOutput } from '#src/evalOutput.js';
+export { DEFAULT_EVAL_PASS_THRESHOLD } from '#src/evalTypes.js';
+// BATCH-3 — the `gth workflow` host: runs a local JS orchestration script that drives one or more
+// LLM calls through a small WorkflowContext.
+export { runWorkflow } from '#src/workflow/runWorkflow.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxE,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAUlD,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAEpD,gGAAgG;AAChG,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AACrE,OAAO,EACL,aAAa,EACb,kBAAkB,EAClB,iBAAiB,EACjB,6BAA6B,GAC9B,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAarD,OAAO,EAAE,2BAA2B,EAAE,MAAM,mBAAmB,CAAC;AAEhE,kGAAkG;AAClG,6CAA6C;AAC7C,OAAO,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC"}

package/dist/interpolate.d.ts

@@ -0,0 +1,16 @@
+import type { MatrixRow } from '#src/types.js';
+/**
+ * Bind one input row into a script's content.
+ *
+ * - Every `{{field}}` placeholder whose `field` is a key of `row` is replaced with that value.
+ * - A placeholder naming a field the row doesn't have is left untouched (fail-soft: a typo in the
+ *   script doesn't blow up the run, it just doesn't get substituted — visible in the recorded
+ *   per-cell content if you go looking).
+ * - When the script contains **no** placeholder that matched any row field at all, the row is
+ *   appended as a fenced context block instead of silently dropped. This covers the "script has no
+ *   placeholders" case BATCH-1's own scope note calls out explicitly: a script that never mentions
+ *   `{{...}}` still needs the row's data available to the model, just not spliced into prose.
+ *
+ * `row` undefined (no `--over`) is a no-op passthrough.
+ */
+export declare function bindCellContent(baseContent: string, row: MatrixRow | undefined): string;

package/dist/interpolate.js

@@ -0,0 +1,48 @@
+/**
+ * BATCH-1 cell-binding syntax: `{{field}}` placeholders.
+ *
+ * Matches a bare field name (letters/digits/`_`/`.`/`-`), optionally surrounded by whitespace
+ * inside the braces (`{{ field }}` also works). Chosen over a heavier templating engine (mustache,
+ * handlebars-with-helpers, …) because BATCH-1's job is a literal find/replace of csv/jsonl column
+ * values into prose — no conditionals or loops belong in a prompt-executable script, and `{{x}}` is
+ * the syntax #405's own case format already uses for template-ish values, so it needs no new
+ * mental model for that user.
+ */
+const PLACEHOLDER_RE = /\{\{\s*([\w.-]+)\s*\}\}/g;
+/**
+ * Bind one input row into a script's content.
+ *
+ * - Every `{{field}}` placeholder whose `field` is a key of `row` is replaced with that value.
+ * - A placeholder naming a field the row doesn't have is left untouched (fail-soft: a typo in the
+ *   script doesn't blow up the run, it just doesn't get substituted — visible in the recorded
+ *   per-cell content if you go looking).
+ * - When the script contains **no** placeholder that matched any row field at all, the row is
+ *   appended as a fenced context block instead of silently dropped. This covers the "script has no
+ *   placeholders" case BATCH-1's own scope note calls out explicitly: a script that never mentions
+ *   `{{...}}` still needs the row's data available to the model, just not spliced into prose.
+ *
+ * `row` undefined (no `--over`) is a no-op passthrough.
+ */
+export function bindCellContent(baseContent, row) {
+    if (!row) {
+        return baseContent;
+    }
+    let matchedAny = false;
+    const bound = baseContent.replace(PLACEHOLDER_RE, (full, field) => {
+        if (Object.prototype.hasOwnProperty.call(row, field)) {
+            matchedAny = true;
+            return row[field];
+        }
+        return full;
+    });
+    if (matchedAny) {
+        return bound;
+    }
+    return `${bound}\n\n${formatRowAsContextBlock(row)}`;
+}
+/** Render a row as a small fenced block of `key: value` lines, for the no-placeholder fallback. */
+function formatRowAsContextBlock(row) {
+    const lines = Object.entries(row).map(([key, value]) => `${key}: ${value}`);
+    return ['Batch input row for this cell:', '<batch-row>', ...lines, '</batch-row>'].join('\n');
+}
+//# sourceMappingURL=interpolate.js.map

package/dist/interpolate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interpolate.js","sourceRoot":"","sources":["../src/interpolate.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AACH,MAAM,cAAc,GAAG,0BAA0B,CAAC;AAElD;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,eAAe,CAAC,WAAmB,EAAE,GAA0B;IAC7E,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,OAAO,WAAW,CAAC;IACrB,CAAC;IAED,IAAI,UAAU,GAAG,KAAK,CAAC;IACvB,MAAM,KAAK,GAAG,WAAW,CAAC,OAAO,CAAC,cAAc,EAAE,CAAC,IAAI,EAAE,KAAa,EAAE,EAAE;QACxE,IAAI,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,CAAC;YACrD,UAAU,GAAG,IAAI,CAAC;YAClB,OAAO,GAAG,CAAC,KAAK,CAAC,CAAC;QACpB,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC,CAAC,CAAC;IAEH,IAAI,UAAU,EAAE,CAAC;QACf,OAAO,KAAK,CAAC;IACf,CAAC;IAED,OAAO,GAAG,KAAK,OAAO,uBAAuB,CAAC,GAAG,CAAC,EAAE,CAAC;AACvD,CAAC;AAED,mGAAmG;AACnG,SAAS,uBAAuB,CAAC,GAAc;IAC7C,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,KAAK,KAAK,EAAE,CAAC,CAAC;IAC5E,OAAO,CAAC,gCAAgC,EAAE,aAAa,EAAE,GAAG,KAAK,EAAE,cAAc,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAChG,CAAC"}

package/dist/judge.d.ts

@@ -0,0 +1,62 @@
+/**
+ * @module judge
+ *
+ * BATCH-2 — LLM-as-judge grading for `gth eval`. Adapts the *mechanism* of EXT-10's shell-safety
+ * judge (`packages/core/src/core/shell/judge.ts`): `model.withStructuredOutput(zodSchema)` for a
+ * single non-agentic structured call, raced against a timeout. The failure policy differs on
+ * purpose — EXT-10 fails CLOSED (escalates to a human approval prompt); eval has no human in the
+ * loop, so a judge that can't produce a verdict simply FAILS the case ({@link JudgeOutcome.ok}
+ * `false`), it does not "escalate" anywhere.
+ *
+ * Verdict scale matches `review`'s existing convention (`packages/review/src/middleware/
+ * reviewRateMiddleware.ts`'s `RateSchema`: `rate` 0-10 + a reason/comment string) for UX
+ * consistency — a user who knows `review`'s threshold semantics already knows eval's. `RateSchema`
+ * itself is not imported/reused: it is coupled to review's middleware/tool-call/artifact-store
+ * plumbing, which doesn't fit a plain structured-output call here.
+ *
+ * Model source: `config.llm` by default, i.e. the SAME model config as the SUT — matching
+ * `judgeShellCommand`'s own default. A separate `--judge <profile>` model is BATCH-2's own
+ * "Not in scope" list (identity-matrix/pluggable-target work); grading with the SUT's own model
+ * config is a known, real simplification for this first slice.
+ */
+import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
+import * as z from 'zod';
+import type { JudgeOutcome } from '#src/evalTypes.js';
+/** Structured verdict the judge model must return — 0-10 `rate` + a `reason`, matching `review`'s
+ * `RateSchema` shape (`rate`/`comment`) closely enough that the scale/semantics are the same;
+ * named `reason` here to read naturally as "why this rate" rather than a generic review comment. */
+export declare const EvalVerdictSchema: z.ZodObject<{
+    rate: z.ZodNumber;
+    reason: z.ZodString;
+}, z.core.$strip>;
+export type EvalJudgeVerdict = z.infer<typeof EvalVerdictSchema>;
+/** Default wall-clock budget (ms) for the judge LLM call — same default as `judgeShellCommand`'s
+ * `JUDGE_DEFAULT_TIMEOUT_MS`, kept as eval's own constant since the two judges live in different
+ * packages (`@gaunt-sloth/core` vs `@gaunt-sloth/batch`) and are conceptually independent gates. */
+export declare const EVAL_JUDGE_DEFAULT_TIMEOUT_MS = 30000;
+/**
+ * Build the judge's messages: a fixed system preamble and a user message embedding the rubric and
+ * the SUT's answer. Exposed (and returning plain strings) so tests can assert structure without a
+ * live model.
+ */
+export declare function buildJudgeMessages(answer: string, rubric: string): {
+    system: string;
+    user: string;
+};
+/**
+ * Grade one case's SUT answer against its rubric via LLM-as-judge.
+ *
+ * - Builds the judge prompt ({@link buildJudgeMessages}).
+ * - Calls `model.withStructuredOutput(EvalVerdictSchema)`.
+ * - Races the call against `timeoutMs` (default {@link EVAL_JUDGE_DEFAULT_TIMEOUT_MS}).
+ * - **Fails the case, not closed-to-a-human:** any throw / timeout / unparseable output / unusable
+ *   model returns `{ ok: false, error }` — never a verdict, and never an auto-pass.
+ *
+ * @param answer The SUT's answer text to grade.
+ * @param rubric The case's judge rubric (already validated non-blank by `parseEvalSuite`).
+ * @param model The judge model — the caller passes `config.llm` (see module doc); `undefined`
+ *   fails the case immediately, same as an unusable model.
+ */
+export declare function judgeEvalCase(answer: string, rubric: string, model: BaseChatModel | undefined, options?: {
+    timeoutMs?: number;
+}): Promise<JudgeOutcome>;

package/dist/judge.js

@@ -0,0 +1,119 @@
+/**
+ * @module judge
+ *
+ * BATCH-2 — LLM-as-judge grading for `gth eval`. Adapts the *mechanism* of EXT-10's shell-safety
+ * judge (`packages/core/src/core/shell/judge.ts`): `model.withStructuredOutput(zodSchema)` for a
+ * single non-agentic structured call, raced against a timeout. The failure policy differs on
+ * purpose — EXT-10 fails CLOSED (escalates to a human approval prompt); eval has no human in the
+ * loop, so a judge that can't produce a verdict simply FAILS the case ({@link JudgeOutcome.ok}
+ * `false`), it does not "escalate" anywhere.
+ *
+ * Verdict scale matches `review`'s existing convention (`packages/review/src/middleware/
+ * reviewRateMiddleware.ts`'s `RateSchema`: `rate` 0-10 + a reason/comment string) for UX
+ * consistency — a user who knows `review`'s threshold semantics already knows eval's. `RateSchema`
+ * itself is not imported/reused: it is coupled to review's middleware/tool-call/artifact-store
+ * plumbing, which doesn't fit a plain structured-output call here.
+ *
+ * Model source: `config.llm` by default, i.e. the SAME model config as the SUT — matching
+ * `judgeShellCommand`'s own default. A separate `--judge <profile>` model is BATCH-2's own
+ * "Not in scope" list (identity-matrix/pluggable-target work); grading with the SUT's own model
+ * config is a known, real simplification for this first slice.
+ */
+import { HumanMessage, SystemMessage } from '@langchain/core/messages';
+import * as z from 'zod';
+/** Structured verdict the judge model must return — 0-10 `rate` + a `reason`, matching `review`'s
+ * `RateSchema` shape (`rate`/`comment`) closely enough that the scale/semantics are the same;
+ * named `reason` here to read naturally as "why this rate" rather than a generic review comment. */
+export const EvalVerdictSchema = z.object({
+    rate: z
+        .number()
+        .min(0)
+        .max(10)
+        .describe('How well the answer satisfies the rubric, from 0 to 10.'),
+    reason: z.string().describe('One or two sentences explaining the rate.'),
+});
+/** Default wall-clock budget (ms) for the judge LLM call — same default as `judgeShellCommand`'s
+ * `JUDGE_DEFAULT_TIMEOUT_MS`, kept as eval's own constant since the two judges live in different
+ * packages (`@gaunt-sloth/core` vs `@gaunt-sloth/batch`) and are conceptually independent gates. */
+export const EVAL_JUDGE_DEFAULT_TIMEOUT_MS = 30_000;
+const EVAL_JUDGE_SYSTEM_PROMPT = [
+    "You are gaunt-sloth's eval judge.",
+    'You are given a rubric and an AI assistant answer, and must rate how well the answer satisfies',
+    'that rubric.',
+    '',
+    'Rate on a scale from 0 to 10, where 0 is a complete failure to satisfy the rubric and 10 is a',
+    'perfect match. Base the rating only on whether the answer satisfies the rubric — not on style,',
+    'tone, or preferences the rubric does not mention.',
+    'Use the reason field to briefly justify the rate, referencing what the rubric asked for and',
+    'what the answer actually did.',
+].join('\n');
+/**
+ * Build the judge's messages: a fixed system preamble and a user message embedding the rubric and
+ * the SUT's answer. Exposed (and returning plain strings) so tests can assert structure without a
+ * live model.
+ */
+export function buildJudgeMessages(answer, rubric) {
+    const userLines = [
+        'Rubric:',
+        rubric,
+        '',
+        'Answer to evaluate:',
+        '<answer>',
+        answer || '(empty answer)',
+        '</answer>',
+    ];
+    return { system: EVAL_JUDGE_SYSTEM_PROMPT, user: userLines.join('\n') };
+}
+/**
+ * Grade one case's SUT answer against its rubric via LLM-as-judge.
+ *
+ * - Builds the judge prompt ({@link buildJudgeMessages}).
+ * - Calls `model.withStructuredOutput(EvalVerdictSchema)`.
+ * - Races the call against `timeoutMs` (default {@link EVAL_JUDGE_DEFAULT_TIMEOUT_MS}).
+ * - **Fails the case, not closed-to-a-human:** any throw / timeout / unparseable output / unusable
+ *   model returns `{ ok: false, error }` — never a verdict, and never an auto-pass.
+ *
+ * @param answer The SUT's answer text to grade.
+ * @param rubric The case's judge rubric (already validated non-blank by `parseEvalSuite`).
+ * @param model The judge model — the caller passes `config.llm` (see module doc); `undefined`
+ *   fails the case immediately, same as an unusable model.
+ */
+export async function judgeEvalCase(answer, rubric, model, options) {
+    const timeoutMs = options?.timeoutMs ?? EVAL_JUDGE_DEFAULT_TIMEOUT_MS;
+    if (!model || typeof model.withStructuredOutput !== 'function') {
+        return { attempted: true, ok: false, error: 'No usable judge model configured.' };
+    }
+    const { system, user } = buildJudgeMessages(answer, rubric);
+    let timer;
+    try {
+        const structured = model.withStructuredOutput(EvalVerdictSchema);
+        const judgePromise = structured.invoke([new SystemMessage(system), new HumanMessage(user)]);
+        const TIMEOUT = Symbol('eval-judge-timeout');
+        const timeoutPromise = new Promise((resolve) => {
+            timer = setTimeout(() => resolve(TIMEOUT), timeoutMs);
+        });
+        const raced = await Promise.race([judgePromise, timeoutPromise]);
+        if (raced === TIMEOUT) {
+            return { attempted: true, ok: false, error: `Judge timed out after ${timeoutMs}ms.` };
+        }
+        // withStructuredOutput already coerces to the schema, but re-validate defensively: a fake or
+        // misbehaving model could return a non-conforming object.
+        const parsed = EvalVerdictSchema.safeParse(raced);
+        if (!parsed.success) {
+            return { attempted: true, ok: false, error: 'Judge returned unparseable output.' };
+        }
+        return { attempted: true, ok: true, verdict: parsed.data };
+    }
+    catch (error) {
+        return {
+            attempted: true,
+            ok: false,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+//# sourceMappingURL=judge.js.map

package/dist/judge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"judge.js","sourceRoot":"","sources":["../src/judge.ts"],"names":[],"mappings":"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"}

package/dist/matrix.d.ts

@@ -0,0 +1,11 @@
+import type { MatrixCell, MatrixRow } from '#src/types.js';
+/**
+ * Build the batch matrix: the cross product of the model axis (`--models`, absent = a single
+ * `undefined`-model cell using the resolved config's model) and the input axis (`--over`, absent =
+ * a single `undefined`-row cell using the script's own content, exactly like `exec`).
+ *
+ * `models`/`rows` pass `undefined` (not an empty array) to mean "axis absent" — an empty array is
+ * treated as a caller bug and also collapses to "absent" defensively, since a 0-cell matrix would
+ * silently do nothing.
+ */
+export declare function buildMatrix(baseContent: string, models: string[] | undefined, rows: MatrixRow[] | undefined): MatrixCell[];

package/dist/matrix.js

@@ -0,0 +1,31 @@
+import { bindCellContent } from '#src/interpolate.js';
+/**
+ * Build the batch matrix: the cross product of the model axis (`--models`, absent = a single
+ * `undefined`-model cell using the resolved config's model) and the input axis (`--over`, absent =
+ * a single `undefined`-row cell using the script's own content, exactly like `exec`).
+ *
+ * `models`/`rows` pass `undefined` (not an empty array) to mean "axis absent" — an empty array is
+ * treated as a caller bug and also collapses to "absent" defensively, since a 0-cell matrix would
+ * silently do nothing.
+ */
+export function buildMatrix(baseContent, models, rows) {
+    const modelAxis = models && models.length > 0 ? models : [undefined];
+    const rowAxis = rows && rows.length > 0 ? rows : [undefined];
+    const cells = [];
+    for (let mi = 0; mi < modelAxis.length; mi++) {
+        for (let ri = 0; ri < rowAxis.length; ri++) {
+            const model = modelAxis[mi];
+            const row = rowAxis[ri];
+            cells.push({
+                id: `cell-${mi}-${ri}`,
+                modelIndex: mi,
+                model,
+                inputIndex: ri,
+                inputRow: row,
+                content: bindCellContent(baseContent, row),
+            });
+        }
+    }
+    return cells;
+}
+//# sourceMappingURL=matrix.js.map

package/dist/matrix.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"matrix.js","sourceRoot":"","sources":["../src/matrix.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAGtD;;;;;;;;GAQG;AACH,MAAM,UAAU,WAAW,CACzB,WAAmB,EACnB,MAA4B,EAC5B,IAA6B;IAE7B,MAAM,SAAS,GAAG,MAAM,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IACrE,MAAM,OAAO,GAAG,IAAI,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IAE7D,MAAM,KAAK,GAAiB,EAAE,CAAC;IAC/B,KAAK,IAAI,EAAE,GAAG,CAAC,EAAE,EAAE,GAAG,SAAS,CAAC,MAAM,EAAE,EAAE,EAAE,EAAE,CAAC;QAC7C,KAAK,IAAI,EAAE,GAAG,CAAC,EAAE,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,EAAE,EAAE,EAAE,CAAC;YAC3C,MAAM,KAAK,GAAG,SAAS,CAAC,EAAE,CAAC,CAAC;YAC5B,MAAM,GAAG,GAAG,OAAO,CAAC,EAAE,CAAC,CAAC;YACxB,KAAK,CAAC,IAAI,CAAC;gBACT,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,EAAE;gBACtB,UAAU,EAAE,EAAE;gBACd,KAAK;gBACL,UAAU,EAAE,EAAE;gBACd,QAAQ,EAAE,GAAG;gBACb,OAAO,EAAE,eAAe,CAAC,WAAW,EAAE,GAAG,CAAC;aAC3C,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/output.d.ts

@@ -0,0 +1,13 @@
+import type { BatchSummary, CellResult } from '#src/types.js';
+/**
+ * Write one structured JSON record per cell (`<id>.json`) plus one aggregate `results.json`
+ * (pass/fail counts + a per-cell one-liner — a lightweight flake report) into `outputDir`.
+ * Creates `outputDir` (and any missing parents) if it doesn't exist.
+ *
+ * Pure I/O, deliberately separate from {@link runBatchMatrix}: the runner never touches the
+ * filesystem, so unit tests can exercise matrix/concurrency/retry logic without a tmp dir, and this
+ * function can be tested in isolation with a fixed set of results.
+ *
+ * @returns The aggregate {@link BatchSummary} that was written to `results.json`.
+ */
+export declare function writeBatchOutput(outputDir: string, results: CellResult[]): BatchSummary;

package/dist/output.js

@@ -0,0 +1,24 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { buildBatchSummary } from '#src/BatchRunner.js';
+/**
+ * Write one structured JSON record per cell (`<id>.json`) plus one aggregate `results.json`
+ * (pass/fail counts + a per-cell one-liner — a lightweight flake report) into `outputDir`.
+ * Creates `outputDir` (and any missing parents) if it doesn't exist.
+ *
+ * Pure I/O, deliberately separate from {@link runBatchMatrix}: the runner never touches the
+ * filesystem, so unit tests can exercise matrix/concurrency/retry logic without a tmp dir, and this
+ * function can be tested in isolation with a fixed set of results.
+ *
+ * @returns The aggregate {@link BatchSummary} that was written to `results.json`.
+ */
+export function writeBatchOutput(outputDir, results) {
+    mkdirSync(outputDir, { recursive: true });
+    for (const result of results) {
+        writeFileSync(join(outputDir, `${result.id}.json`), `${JSON.stringify(result, null, 2)}\n`);
+    }
+    const summary = buildBatchSummary(results);
+    writeFileSync(join(outputDir, 'results.json'), `${JSON.stringify(summary, null, 2)}\n`);
+    return summary;
+}
+//# sourceMappingURL=output.js.map

package/dist/output.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.js","sourceRoot":"","sources":["../src/output.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAGxD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,gBAAgB,CAAC,SAAiB,EAAE,OAAqB;IACvE,SAAS,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAE1C,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,aAAa,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,MAAM,CAAC,EAAE,OAAO,CAAC,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;IAC9F,CAAC;IAED,MAAM,OAAO,GAAG,iBAAiB,CAAC,OAAO,CAAC,CAAC;IAC3C,aAAa,CAAC,IAAI,CAAC,SAAS,EAAE,cAAc,CAAC,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;IAExF,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/parseOver.d.ts

@@ -0,0 +1,14 @@
+import type { MatrixRow } from '#src/types.js';
+/**
+ * Parse `--over <path>` content into matrix rows. Format is chosen by file extension:
+ * `.jsonl`/`.ndjson` → one JSON object per line; anything else (including `.csv`) → CSV.
+ *
+ * This is content binding only (BATCH-1 scope): every row becomes an object of string fields that
+ * {@link bindCellContent} interpolates into the script. A glob-of-binary-files path binding is out
+ * of scope for this task.
+ *
+ * Throws a descriptive `Error` on malformed input — the harness-level failure the CLI surface doc
+ * calls out as the one thing that should make `gth batch` exit non-zero (a bad row/cell answer
+ * never should).
+ */
+export declare function parseOverFile(filePath: string, content: string): MatrixRow[];

package/dist/parseOver.js

@@ -0,0 +1,116 @@
+/**
+ * Parse `--over <path>` content into matrix rows. Format is chosen by file extension:
+ * `.jsonl`/`.ndjson` → one JSON object per line; anything else (including `.csv`) → CSV.
+ *
+ * This is content binding only (BATCH-1 scope): every row becomes an object of string fields that
+ * {@link bindCellContent} interpolates into the script. A glob-of-binary-files path binding is out
+ * of scope for this task.
+ *
+ * Throws a descriptive `Error` on malformed input — the harness-level failure the CLI surface doc
+ * calls out as the one thing that should make `gth batch` exit non-zero (a bad row/cell answer
+ * never should).
+ */
+export function parseOverFile(filePath, content) {
+    const isJsonl = /\.(jsonl|ndjson)$/i.test(filePath);
+    return isJsonl ? parseJsonl(filePath, content) : parseCsv(filePath, content);
+}
+function parseJsonl(filePath, content) {
+    const rows = [];
+    const lines = content.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i].trim();
+        if (line.length === 0)
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch (error) {
+            throw new Error(`--over ${filePath}: invalid JSON on line ${i + 1}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            throw new Error(`--over ${filePath}: line ${i + 1} must be a JSON object, got ${JSON.stringify(parsed)}`);
+        }
+        rows.push(stringifyRowValues(parsed));
+    }
+    if (rows.length === 0) {
+        throw new Error(`--over ${filePath}: no rows found (empty JSONL file)`);
+    }
+    return rows;
+}
+function stringifyRowValues(record) {
+    const row = {};
+    for (const [key, value] of Object.entries(record)) {
+        row[key] = typeof value === 'string' ? value : JSON.stringify(value);
+    }
+    return row;
+}
+/** Minimal RFC4180 CSV parser (quoted fields, escaped `""`, CRLF/LF), header row = field names. */
+function parseCsvLines(text) {
+    const rows = [];
+    let field = '';
+    let row = [];
+    let inQuotes = false;
+    for (let i = 0; i < text.length; i++) {
+        const c = text[i];
+        if (inQuotes) {
+            if (c === '"') {
+                if (text[i + 1] === '"') {
+                    field += '"';
+                    i++;
+                }
+                else {
+                    inQuotes = false;
+                }
+            }
+            else {
+                field += c;
+            }
+        }
+        else if (c === '"') {
+            inQuotes = true;
+        }
+        else if (c === ',') {
+            row.push(field);
+            field = '';
+        }
+        else if (c === '\n') {
+            row.push(field);
+            rows.push(row);
+            row = [];
+            field = '';
+        }
+        else if (c !== '\r') {
+            field += c;
+        }
+    }
+    if (field.length > 0 || row.length > 0) {
+        row.push(field);
+        rows.push(row);
+    }
+    return rows;
+}
+function parseCsv(filePath, content) {
+    const raw = parseCsvLines(content);
+    if (raw.length === 0) {
+        throw new Error(`--over ${filePath}: empty CSV file (no header row)`);
+    }
+    const header = raw[0].map((h) => h.trim());
+    if (header.length === 0 || header.every((h) => h.length === 0)) {
+        throw new Error(`--over ${filePath}: CSV header row is empty`);
+    }
+    const rows = raw
+        .slice(1)
+        .filter((r) => r.some((c) => c.trim() !== ''))
+        .map((r) => {
+        if (r.length !== header.length) {
+            throw new Error(`--over ${filePath}: row has ${r.length} field(s), expected ${header.length} to match the header`);
+        }
+        return Object.fromEntries(header.map((h, i) => [h, (r[i] ?? '').trim()]));
+    });
+    if (rows.length === 0) {
+        throw new Error(`--over ${filePath}: no data rows found (only a header row)`);
+    }
+    return rows;
+}
+//# sourceMappingURL=parseOver.js.map

package/dist/parseOver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parseOver.js","sourceRoot":"","sources":["../src/parseOver.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,97 @@
+/**
+ * @packageDocumentation
+ * BATCH-1 — the shapes shared across matrix construction, the concurrency/retry runner, and the
+ * structured output writer. Deliberately independent of any LLM/runner types (`GthConfig`,
+ * `runSingleShot`, …): this package only knows about *cells* and *outcomes*. The production
+ * adapter that turns a cell into an actual `runSingleShot` call lives in
+ * `packages/app/src/commands/batchCommand.ts`, which is what keeps {@link RunCellFn} injectable —
+ * unit tests here fake it, the CLI wires the real one.
+ */
+/** One row/record parsed from `--over <path.csv|path.jsonl>`. Values are always strings for csv. */
+export type MatrixRow = Record<string, string>;
+/**
+ * One cell of the batch matrix — the cross product of the model axis (`--models`) and the input
+ * axis (`--over`). Either axis may be absent (single cell using the resolved config's model and/or
+ * the script's own content, mirroring `exec` with no matrix at all).
+ */
+export interface MatrixCell {
+    /**
+     * Filename-safe, deterministic identifier: `cell-<modelIndex>-<rowIndex>` (0-based; both
+     * default to 0 when their axis is absent). Never derived from the model name or row content so
+     * it stays stable and filesystem-safe regardless of what a model/provider string or row data
+     * contains.
+     */
+    id: string;
+    /** 0-based index into the (possibly single-element) model axis. */
+    modelIndex: number;
+    /** The model name for this cell, when `--models` was supplied. Absent = the configured model. */
+    model?: string;
+    /** 0-based index into the (possibly single-element) input axis. */
+    inputIndex: number;
+    /** The source row for this cell, when `--over` was supplied. Absent = no input axis. */
+    inputRow?: MatrixRow;
+    /** The fully-bound prompt content for this cell (base script content with the row interpolated). */
+    content: string;
+}
+/** What one attempt at running a cell through the shared single-shot runtime produced. */
+export interface CellRunOutcome {
+    /** `true` when the cell's run completed without error; mirrors `runSingleShot`'s contract. */
+    ok: boolean;
+    /**
+     * The model's final answer text, when the injected run-cell function can cleanly obtain it.
+     * The production adapter (wired around `runSingleShot`) populates this from
+     * `runSingleShot`'s `SingleShotResult.answer` (BATCH-2); still optional because fakes used in
+     * tests, or a future non-`runSingleShot`-backed `RunCellFn`, may leave it unset.
+     */
+    answer?: string;
+    /** Total prompt/input tokens for the run, when available (see {@link answer}'s caveat). */
+    tokensInput?: number;
+    /** Total completion/output tokens for the run, when available (see {@link answer}'s caveat). */
+    tokensOutput?: number;
+    /** Names of tools invoked during the run, when available (see {@link answer}'s caveat). */
+    tools?: string[];
+    /** A human-readable failure reason, set when `ok` is `false`. */
+    error?: string;
+}
+/**
+ * Injectable "run one prompt" function — the seam that lets {@link runBatchMatrix} be fully unit
+ * tested without any real LLM call. The production wiring (`batchCommand.ts`) adapts
+ * `runSingleShot` to this shape; tests inject a fake that resolves/rejects/throws as needed.
+ */
+export type RunCellFn = (cell: MatrixCell) => Promise<CellRunOutcome>;
+/** One cell's full structured record, as written to `<id>.json` and summarized in `results.json`. */
+export interface CellResult extends CellRunOutcome {
+    id: string;
+    model?: string;
+    inputIndex: number;
+    /** The source row for this cell, echoed for traceability (absent when no `--over` was given). */
+    inputRow?: MatrixRow;
+    /** Wall-clock time across all attempts (including retries) for this cell, in milliseconds. */
+    durationMs: number;
+    /** How many retries were consumed (0 = succeeded, or failed, on the first attempt). */
+    retries: number;
+}
+/** Options for {@link runBatchMatrix}. */
+export interface BatchRunnerOptions {
+    /** Max in-flight cells. Must be >= 1; non-finite/invalid values fall back to the default. */
+    concurrency?: number;
+    /** Number of retries on a failed cell (0 = no retry, the default). */
+    retry?: number;
+    /** The injectable per-cell run function (see {@link RunCellFn}). */
+    runCell: RunCellFn;
+}
+/** A lightweight, `--repeat`-free version of the "flake report" §3 of the requirements asks for. */
+export interface BatchSummary {
+    total: number;
+    passed: number;
+    failed: number;
+    cells: Array<{
+        id: string;
+        model?: string;
+        inputIndex: number;
+        ok: boolean;
+        retries: number;
+    }>;
+}
+/** The default concurrency cap when `-j/--concurrency` is not supplied. */
+export declare const DEFAULT_CONCURRENCY = 4;