@axlsdk/eval 0.13.0 → 0.13.2

package/README.md

@@ -10,63 +10,120 @@ Evaluation framework for [Axl](https://github.com/axl-sdk/axl) agentic workflows
 npm install @axlsdk/eval
 ```
 
-## API
+TypeScript eval files require [tsx](https://github.com/privatenumber/tsx) as a dev dependency (`npm install -D tsx`).
 
-### `dataset(config)`
+## Quick Start
 
-Define evaluation datasets:
+An eval file defines what to test (dataset), how to run it (execution function), and how to score it (scorers):
+
+```typescript
+// evals/qa.eval.ts
+import { defineEval, dataset, scorer, llmScorer } from '@axlsdk/eval';
+import type { AxlRuntime } from '@axlsdk/axl';
+import { z } from 'zod';
+import { qaAgent } from '../src/agents/qa.js';
+
+export default defineEval({
+  workflow: 'qa-eval',  // label for results (used in output table and comparisons)
+  dataset: dataset({
+    name: 'qa-basics',
+    schema: z.object({ question: z.string() }),
+    items: [
+      { input: { question: 'What is TypeScript?' } },
+      { input: { question: 'Explain closures.' } },
+    ],
+  }),
+  scorers: [
+    // Deterministic — runs in-process, no LLM call
+    scorer({
+      name: 'not-empty',
+      description: 'Output is non-empty',
+      score: (output) => (String(output).length > 10 ? 1 : 0),
+    }),
+    // LLM-as-judge — calls an LLM to evaluate quality
+    llmScorer({
+      name: 'relevance',
+      description: 'Is the answer relevant to the question?',
+      model: 'openai:gpt-4o',
+      system: 'Rate whether the answer is relevant to the question asked.',
+      schema: z.object({ score: z.number(), reasoning: z.string() }),
+    }),
+  ],
+});
+
+// How to produce output for each dataset item
+export async function executeWorkflow(input: { question: string }, runtime: AxlRuntime) {
+  const ctx = runtime.createContext();
+  return { output: await ctx.ask(qaAgent, input.question) };
+}
+```
+
+Run it:
+
+```bash
+OPENAI_API_KEY=sk-... npx axl-eval ./evals/qa.eval.ts
+```
+
+```
+Eval: qa-eval x qa-basics (2 items)
+  Scorer     Mean      Min      Max      p50      p95
+  ─────────────────────────────────────────────────────
+  not-empty  1.00     1.00     1.00     1.00     1.00
+  relevance  0.90     0.80     1.00     0.90     1.00
+
+  Failures: 0/2 | Cost: $0.01 | Duration: 3.2s
+```
+
+If an LLM scorer fails (wrong API key, provider down, invalid response), you'll see:
+
+```
+  relevance    --       --       --       --       --
+
+  Scorer errors (2/2 items affected):
+    - Scorer "relevance" threw: OpenAI API key is required. Set OPENAI_API_KEY or pass apiKey in options.
+```
+
+## Datasets
 
 ```typescript
 import { dataset } from '@axlsdk/eval';
 import { z } from 'zod';
 
-// Inline items with schema and annotations
 const ds = dataset({
   name: 'math-basics',
   schema: z.object({ question: z.string() }),
-  annotations: z.object({ answer: z.number() }),
+  annotations: z.object({ answer: z.number() }),  // optional ground truth
   items: [
     { input: { question: '2+2' }, annotations: { answer: 4 } },
     { input: { question: '3*5' }, annotations: { answer: 15 } },
-    { input: { question: '10/2' }, annotations: { answer: 5 } },
   ],
 });
-
-// Load from file
-const ds = dataset({
-  name: 'math-advanced',
-  schema: z.object({ question: z.string() }),
-  file: './datasets/math.json',
-});
 ```
 
-### `scorer(config)`
+You can also load from a file: `dataset({ name: 'large', schema, file: './data.json' })`.
+
+## Scorers
 
-Define deterministic scoring functions. The `score` callback receives `(output, input, annotations?)`:
+Scorers rate each output on a 0-1 scale. You can mix deterministic and LLM scorers in the same eval.
+
+### Deterministic scorers
+
+Pure functions — fast, free, deterministic. The `score` callback receives `(output, input, annotations?)`:
 
 ```typescript
 import { scorer } from '@axlsdk/eval';
 
-const exactMatch = scorer({
-  name: 'exact-match',
-  description: 'Checks if the output answer exactly matches the expected answer',
-  score: (output, input, annotations) => output.answer === annotations?.answer ? 1 : 0,
-});
-
-const partialMatch = scorer({
-  name: 'partial',
-  description: 'Checks if the output contains the expected answer',
-  score: (output, input, annotations) => {
-    const outputStr = String(output).toLowerCase();
-    const expected = String(annotations?.answer).toLowerCase();
-    return outputStr.includes(expected) ? 1 : 0;
-  },
+const containsAnswer = scorer({
+  name: 'contains-answer',
+  description: 'Output contains the expected numeric answer',
+  score: (output, _input, annotations) =>
+    String(output).includes(String(annotations?.answer)) ? 1 : 0,
 });
 ```
 
-### `llmScorer(config)`
+### LLM scorers
 
-Use an LLM as a judge. The scorer automatically constructs a prompt from the input, output, and annotations, then validates the response against your Zod schema:
+Use an LLM as a judge. The scorer constructs a prompt from the input, output, and annotations, calls the LLM, and validates the response against your Zod schema:
 
 ```typescript
 import { llmScorer } from '@axlsdk/eval';
@@ -74,285 +131,216 @@ import { z } from 'zod';
 
 const qualityJudge = llmScorer({
   name: 'quality',
-  description: 'Rates output quality on a 0-1 scale',
-  model: 'openai-responses:gpt-5.4',
-  system: 'You are an expert evaluator. Rate the quality of AI outputs.',
+  description: 'Rates overall output quality',
+  model: 'openai:gpt-4o',           // provider:model URI
+  system: 'Rate the quality of the AI output.',
   schema: z.object({
     score: z.number().min(0).max(1),
     reasoning: z.string(),
   }),
-  temperature: 0.2,
+  temperature: 0.2,                  // default: 0.2 (low for consistency)
 });
 ```
 
-### `runEval(config, executeFn, runtime)`
+The `model` field uses a `provider:model` URI. The provider is resolved automatically at eval time — just set the right API key:
 
-Run an evaluation. LLM scorer providers are automatically resolved from the runtime's provider registry using each scorer's `model` URI (e.g., `google:gemini-3.1-flash`). Ensure the relevant API key environment variable is set (e.g., `OPENAI_API_KEY`, `GOOGLE_AI_API_KEY`) or register providers via `runtime.registerProvider()`:
+| Provider | URI prefix | Env var |
+|----------|-----------|---------|
+| OpenAI (Chat Completions) | `openai:` | `OPENAI_API_KEY` |
+| OpenAI (Responses API) | `openai-responses:` | `OPENAI_API_KEY` |
+| Anthropic | `anthropic:` | `ANTHROPIC_API_KEY` |
+| Google Gemini | `google:` | `GOOGLE_API_KEY` or `GEMINI_API_KEY` |
+| Custom | `your-name:` | Via `runtime.registerProvider('your-name', provider)` |
 
-```typescript
-import { runEval } from '@axlsdk/eval';
+Different LLM scorers can use different providers — each resolves independently:
 
-const results = await runEval(
-  {
-    workflow: 'my-workflow',  // label stored in results for comparison
-    dataset: ds,
-    scorers: [exactMatch, qualityJudge],
-    concurrency: 5,
-  },
-  async (input) => {
-    const output = await runtime.execute('my-workflow', input);
-    return { output };
-  },
-  runtime,
-);
-
-console.log(results.summary);
-// { count: 3, failures: 0, scorers: { 'exact-match': { mean: 0.85, min: 0, max: 1, p50: 1, p95: 1 }, ... } }
+```typescript
+const qualityJudge = llmScorer({ name: 'quality', model: 'openai:gpt-4o', ... });
+const safetyJudge = llmScorer({ name: 'safety', model: 'anthropic:claude-sonnet-4-5-20250514', ... });
 ```
 
-### `evalCompare(baseline, candidate)`
-
-Compare two evaluation runs:
+## Running Evals
 
-```typescript
-import { evalCompare } from '@axlsdk/eval';
+### CLI
 
-const comparison = evalCompare(baselineResults, candidateResults);
+The most common way to run evals:
 
-console.log(comparison.regressions);
-// [{ input: ..., scorer: 'exact-match', baselineScore: 1, candidateScore: 0, delta: -1 }]
-
-console.log(comparison.improvements);
-// [{ input: ..., scorer: 'quality', baselineScore: 0.5, candidateScore: 0.9, delta: 0.4 }]
+```bash
+npx axl-eval ./evals/qa.eval.ts                    # run a single file
+npx axl-eval ./evals/                               # run all *.eval.* files in a directory
+npx axl-eval ./evals/ --output ./results/v1.json    # save results to JSON
+npx axl-eval ./evals/ --config ./axl.config.ts      # use a specific runtime config
 ```
 
-### `defineEval(config)`
+The CLI resolves a runtime automatically: `--config <path>` > auto-detect `axl.config.*` > bare `new AxlRuntime()` (providers from env vars).
 
-Define an eval file for discovery by the CLI or Studio middleware:
+### Programmatic
+
+**`runtime.eval()`** — when you have a workflow registered on the runtime. The `workflow` field must match the registered name:
 
 ```typescript
-// evals/math.eval.ts
-import { defineEval, dataset, scorer } from '@axlsdk/eval';
+import { AxlRuntime, workflow, agent } from '@axlsdk/axl';
+import { dataset, scorer } from '@axlsdk/eval';
 import { z } from 'zod';
 
-const mathDataset = dataset({
-  name: 'math-basics',
-  schema: z.object({ question: z.string() }),
-  annotations: z.object({ answer: z.number() }),
-  items: [
-    { input: { question: '2+2' }, annotations: { answer: 4 } },
-    { input: { question: '3*5' }, annotations: { answer: 15 } },
-  ],
+const qaAgent = agent({ name: 'qa', model: 'openai:gpt-4o', system: 'Answer questions.' });
+const qaWorkflow = workflow({
+  name: 'qa-workflow',
+  input: z.object({ question: z.string() }),
+  handler: async (ctx) => ctx.ask(qaAgent, ctx.input.question),
 });
 
-const correctAnswer = scorer({
-  name: 'correct-answer',
-  description: 'Checks if the output contains the expected numeric answer',
-  score: (output, _input, annotations) =>
-    String(output).includes(String(annotations?.answer)) ? 1 : 0,
-});
+const runtime = new AxlRuntime();
+runtime.register(qaWorkflow);
 
-export default defineEval({
-  workflow: 'math-workflow',
-  dataset: mathDataset,
-  scorers: [correctAnswer],
+const results = await runtime.eval({
+  workflow: 'qa-workflow',  // must match the registered workflow name
+  dataset: ds,
+  scorers: [containsAnswer, qualityJudge],
 });
 ```
 
-When running via `runtime.eval()` or `runtime.runRegisteredEval()`, the runner calls `runtime.execute(workflow, input)` by default, which requires the workflow to be registered on the runtime.
+**`runEval()`** — when you want full control. The `workflow` field is just a label; the second argument is the function that produces output:
 
-When running via the CLI, the eval runner resolves the execution function in order: (1) the exported `executeWorkflow` function, (2) `runtime.execute(workflow, input)` if the workflow is registered on the runtime, or (3) a passthrough that returns the input as the output (with a warning).
+```typescript
+import { runEval } from '@axlsdk/eval';
 
-The function receives `(input, runtime)` — the second argument is the `AxlRuntime` instance, always provided by the CLI, Studio, and `runtime.runRegisteredEval()`. Use it to call agents without needing a registered workflow:
+const results = await runEval(
+  { workflow: 'my-eval', dataset: ds, scorers: [containsAnswer, qualityJudge] },
+  async (input, runtime) => {
+    const ctx = runtime.createContext();
+    return { output: await ctx.ask(qaAgent, input.question) };
+  },
+  runtime,
+);
+```
 
-```typescript
-// evals/qa-quality.eval.ts — calls an agent directly via the runtime
-import { defineEval, dataset, scorer } from '@axlsdk/eval';
-import type { AxlRuntime } from '@axlsdk/axl';
-import { z } from 'zod';
-import { qaAgent } from '../src/agents/qa.js'; // import your agent definition
+### Studio
 
-const qaDataset = dataset({
-  name: 'qa-pairs',
-  schema: z.object({ question: z.string() }),
-  items: [
-    { input: { question: 'What is TypeScript?' } },
-    { input: { question: 'How do promises work?' } },
-  ],
-});
+Eval files can be lazy-loaded by the Studio middleware for the Eval Runner panel:
 
-const notEmpty = scorer({
-  name: 'not-empty',
-  description: 'Output is non-empty',
-  score: (output) => (String(output).length > 0 ? 1 : 0),
-});
+```typescript
+import { createStudioMiddleware } from '@axlsdk/studio/middleware';
 
-export default defineEval({
-  workflow: 'qa-quality', // label for results (not a runtime lookup)
-  dataset: qaDataset,
-  scorers: [notEmpty],
+const studio = createStudioMiddleware({
+  runtime,
+  evals: 'evals/**/*.eval.ts',
 });
-
-export async function executeWorkflow(input: { question: string }, runtime: AxlRuntime) {
-  const ctx = runtime.createContext();
-  const output = await ctx.ask(qaAgent, input.question);
-  return { output }; // cost tracked automatically via runtime.trackCost()
-}
 ```
 
-When no runtime is needed (e.g., testing a pure function), omit the runtime parameter — these evals work from both the CLI and Studio:
+See the [@axlsdk/studio README](../axl-studio/README.md#lazy-eval-loading) for details.
 
-```typescript
-// evals/parser.eval.ts — tests a pure function, no runtime needed
-export async function executeWorkflow(input: { raw: string }) {
-  const result = parseDocument(input.raw);
-  return { output: result };
-}
-```
+## Understanding Results
 
-> **Note:** The CLI always provides a runtime to `executeWorkflow`. By default it auto-detects `axl.config.*` in the working directory or falls back to a bare `AxlRuntime` (providers resolved from environment variables). Use `--config` for explicit config files.
+Each eval run returns an `EvalResult` with per-item scores and aggregate statistics.
 
-### Cost Tracking
+**Scores** are `number | null` per scorer per item:
+- `0` to `1` — valid score from the scorer
+- `null` — the scorer failed (see `item.scorerErrors` for details)
 
-Cost is tracked automatically. You don't need to return `cost` from your `executeWorkflow` — the eval runner wraps each item with `runtime.trackCost()`, which captures cost from all `createContext()` and `execute()` calls.
+Summary statistics (mean, p50, p95, etc.) exclude `null` scores. If all scores for a scorer are `null`, the CLI shows `--` instead of misleading `0.00`.
 
 ```typescript
-export async function executeWorkflow(input: { question: string }, runtime: AxlRuntime) {
-  const ctx = runtime.createContext();
-  const output = await ctx.ask(myAgent, input.question);
-  return { output }; // cost captured automatically
+const results = await runtime.eval({ ... });
+
+// Aggregate stats
+console.log(results.summary.scorers['quality'].mean);  // 0.85
+console.log(results.summary.count);                     // 50 items
+console.log(results.summary.failures);                  // 2 workflow errors
+
+// Per-item inspection
+for (const item of results.items) {
+  if (item.error) continue;                              // workflow threw
+  if (item.scores['quality'] === null) {
+    console.log('Scorer failed:', item.scorerErrors);    // e.g., ["Scorer "quality" threw: ..."]
+  }
 }
-```
-
-To override the automatic cost (e.g., to exclude setup calls), return it explicitly:
 
-```typescript
-return { output, cost: ctx.totalCost };
+// Cost includes both workflow and LLM scorer calls
+console.log(results.totalCost);  // 0.42
 ```
 
-You can also read `ctx.totalCost` at any point to inspect accumulated cost.
+## Comparing Results
 
-### Common Patterns
+Compare two runs to detect regressions and improvements:
 
-**Budget per item** — cap cost to prevent runaway evals:
+```bash
+npx axl-eval compare ./results/v1.json ./results/v2.json
+npx axl-eval compare v1.json v2.json --fail-on-regression  # exit 1 if worse
+```
 
 ```typescript
-export async function executeWorkflow(input: { question: string }, runtime: AxlRuntime) {
-  const ctx = runtime.createContext({ budget: '$0.50' });
-  const output = await ctx.ask(myAgent, input.question);
-  return { output };
-}
+import { evalCompare } from '@axlsdk/eval';
+
+const comparison = evalCompare(v1Results, v2Results);
+console.log(comparison.regressions);   // items that got worse
+console.log(comparison.improvements);  // items that got better
 ```
 
-**Timeout per item** — cancel items that take too long:
+## Eval Files in Detail
 
-```typescript
-export async function executeWorkflow(input: { question: string }, runtime: AxlRuntime) {
-  const controller = new AbortController();
-  setTimeout(() => controller.abort(), 30_000);
-  const ctx = runtime.createContext({ signal: controller.signal });
-  const output = await ctx.ask(myAgent, input.question);
-  return { output };
-}
-```
+### Execution function
 
-**Auto-approve tools** — when testing agents that have tools with `requireApproval`:
+By default, the runner calls `runtime.execute(workflow, input)` for each item. Export `executeWorkflow` to override:
 
 ```typescript
+// evals/qa.eval.ts
+import { defineEval, dataset, scorer } from '@axlsdk/eval';
+import type { AxlRuntime } from '@axlsdk/axl';
+import { qaAgent } from '../src/agents/qa.js';
+
+export default defineEval({
+  workflow: 'qa-eval',
+  dataset: dataset({ ... }),
+  scorers: [scorer({ ... })],
+});
+
 export async function executeWorkflow(input: { question: string }, runtime: AxlRuntime) {
-  const ctx = runtime.createContext({
-    awaitHumanHandler: async () => ({ approved: true }),
-  });
-  const output = await ctx.ask(myAgent, input.question);
-  return { output };
+  const ctx = runtime.createContext();
+  return { output: await ctx.ask(qaAgent, input.question) };
 }
 ```
 
-**Multi-turn evaluation** — test follow-up responses with conversation history:
+When no runtime is needed (e.g., testing a pure function):
 
 ```typescript
-export async function executeWorkflow(
-  input: { setupPrompt: string; setupResponse: string; followUp: string },
-  runtime: AxlRuntime,
-) {
-  const ctx = runtime.createContext({
-    sessionHistory: [
-      { role: 'user', content: input.setupPrompt },
-      { role: 'assistant', content: input.setupResponse },
-    ],
-  });
-  const output = await ctx.ask(myAgent, input.followUp);
-  return { output };
+export async function executeWorkflow(input: { raw: string }) {
+  return { output: parseDocument(input.raw) };
 }
 ```
 
-## CLI
-
-Run evaluations from the command line:
-
-```bash
-# Run an eval file
-npx axl-eval ./evals/math.eval.ts
+### Cost tracking
 
-# Run all evals in a directory
-npx axl-eval ./evals/
+Cost is tracked automatically — the runner wraps each item with `runtime.trackCost()`. LLM scorer costs are also included in `totalCost` and count toward the `budget` limit.
 
-# Save results to a file
-npx axl-eval ./evals/math.eval.ts --output ./results/baseline.json
+To override (e.g., exclude setup calls), return cost explicitly:
 
-# Use a config file for runtime access
-npx axl-eval ./evals/ --config ./axl.config.ts
-
-# Use custom import conditions (monorepo source exports)
-npx axl-eval ./evals/ --config ./axl.config.ts --conditions development
-
-# Compare two results
-npx axl-eval compare ./results/baseline.json ./results/candidate.json
-
-# Fail CI if regressions detected
-npx axl-eval compare baseline.json candidate.json --fail-on-regression
+```typescript
+return { output, cost: ctx.totalCost };
 ```
 
-TypeScript config and eval files require [tsx](https://github.com/privatenumber/tsx) as a dev dependency (`npm install -D tsx`).
-
-### Runtime Resolution
-
-The CLI resolves an `AxlRuntime` to pass to `executeWorkflow`:
-
-1. **`--config <path>`** — use an explicit config file
-2. **Auto-detect** — search for `axl.config.mts` → `.ts` → `.mjs` → `.js` in cwd
-3. **Fallback** — create a bare `new AxlRuntime()` (providers resolve from environment variables)
-
-When a runtime is available, each `executeWorkflow` call is wrapped with `runtime.trackCost()` for automatic cost attribution.
+### Common patterns
 
-## Studio Integration
+**Budget** — cap cost per item with `runtime.createContext({ budget: '$0.50' })`.
 
-Eval files can also be lazy-loaded by the Studio middleware, enabling the Eval Runner panel without static imports that would create circular dependencies:
+**Timeout** — abort slow items:
 
 ```typescript
-import { createStudioMiddleware } from '@axlsdk/studio/middleware';
-
-const studio = createStudioMiddleware({
-  runtime,
-  evals: 'evals/**/*.eval.ts',
-});
+const controller = new AbortController();
+setTimeout(() => controller.abort(), 30_000);
+const ctx = runtime.createContext({ signal: controller.signal });
 ```
 
-See the [@axlsdk/studio README](../axl-studio/README.md#lazy-eval-loading) for details.
+**Auto-approve tools** — skip human approval in evals: `runtime.createContext({ awaitHumanHandler: async () => ({ approved: true }) })`.
 
-## Integration with AxlRuntime
+**Multi-turn** — provide conversation history:
 
 ```typescript
-import { AxlRuntime } from '@axlsdk/axl';
-
-const runtime = new AxlRuntime();
-runtime.register(myWorkflow);
-
-const results = await runtime.eval({
-  workflow: 'my-workflow',
-  dataset: ds,
-  scorers: [exactMatch],
-  concurrency: 3,
+const ctx = runtime.createContext({
+  sessionHistory: [
+    { role: 'user', content: input.setupPrompt },
+    { role: 'assistant', content: input.setupResponse },
+  ],
 });
 ```
 

package/dist/{chunk-7B5NFD5T.js → chunk-K73SNPVV.js}

@@ -158,8 +158,8 @@ async function runEval(config, executeWorkflow, runtime) {
           }
         }
         if (score < 0 || score > 1) {
-          if (!evalItem.errors) evalItem.errors = [];
-          evalItem.errors.push(
+          if (!evalItem.scorerErrors) evalItem.scorerErrors = [];
+          evalItem.scorerErrors.push(
             `Scorer "${scorer.name}" returned out-of-range score ${score} for input ${JSON.stringify(item.input)}`
           );
           evalItem.scores[scorer.name] = null;
@@ -173,8 +173,8 @@ async function runEval(config, executeWorkflow, runtime) {
             totalCost += lastCost;
           }
         }
-        if (!evalItem.errors) evalItem.errors = [];
-        evalItem.errors.push(
+        if (!evalItem.scorerErrors) evalItem.scorerErrors = [];
+        evalItem.scorerErrors.push(
           `Scorer "${scorer.name}" threw: ${err instanceof Error ? err.message : String(err)}`
         );
         evalItem.scores[scorer.name] = null;
@@ -215,4 +215,4 @@ export {
   evalCompare,
   runEval
 };
-//# sourceMappingURL=chunk-7B5NFD5T.js.map
+//# sourceMappingURL=chunk-K73SNPVV.js.map

package/dist/chunk-K73SNPVV.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/compare.ts","../src/runner.ts"],"sourcesContent":["import type { EvalResult, EvalComparison, EvalRegression, EvalImprovement } from './types.js';\n\nfunction round(n: number): number {\n  return Math.round(n * 100) / 100;\n}\n\nexport function evalCompare(baseline: EvalResult, candidate: EvalResult): EvalComparison {\n  if (baseline.dataset !== candidate.dataset) {\n    throw new Error(\n      `Cannot compare evals from different datasets: \"${baseline.dataset}\" vs \"${candidate.dataset}\"`,\n    );\n  }\n\n  const baselineScorerNames = Object.keys(baseline.summary.scorers).sort();\n  const candidateScorerNames = Object.keys(candidate.summary.scorers).sort();\n  if (JSON.stringify(baselineScorerNames) !== JSON.stringify(candidateScorerNames)) {\n    throw new Error(`Cannot compare evals with different scorers`);\n  }\n\n  const scorers: EvalComparison['scorers'] = {};\n  for (const name of baselineScorerNames) {\n    const bMean = baseline.summary.scorers[name].mean;\n    const cMean = candidate.summary.scorers[name].mean;\n    const delta = round(cMean - bMean);\n    const deltaPercent = bMean > 0 ? round((delta / bMean) * 100) : 0;\n    scorers[name] = { baselineMean: bMean, candidateMean: cMean, delta, deltaPercent };\n  }\n\n  const regressions: EvalRegression[] = [];\n  const improvements: EvalImprovement[] = [];\n\n  const minLength = Math.min(baseline.items.length, candidate.items.length);\n  for (let i = 0; i < minLength; i++) {\n    const bItem = baseline.items[i];\n    const cItem = candidate.items[i];\n    if (bItem.error || cItem.error) continue;\n    for (const name of baselineScorerNames) {\n      const bScore = bItem.scores[name];\n      const cScore = cItem.scores[name];\n      if (bScore == null || cScore == null) continue;\n      const delta = round(cScore - bScore);\n      if (delta < -0.1)\n        regressions.push({\n          input: bItem.input,\n          scorer: name,\n          baselineScore: bScore,\n          candidateScore: cScore,\n          delta,\n        });\n      else if (delta > 0.1)\n        improvements.push({\n          input: bItem.input,\n          scorer: name,\n          baselineScore: bScore,\n          candidateScore: cScore,\n          delta,\n        });\n    }\n  }\n\n  const parts: string[] = [];\n  for (const name of baselineScorerNames) {\n    const s = scorers[name];\n    if (Math.abs(s.delta) > 0.001) {\n      const direction = s.delta > 0 ? 'improves' : 'regresses';\n      const sign = s.delta > 0 ? '+' : '';\n      parts.push(\n        `'${name}' ${direction} by ${sign}${s.deltaPercent.toFixed(1)}% (${s.baselineMean.toFixed(2)} -> ${s.candidateMean.toFixed(2)})`,\n      );\n    }\n  }\n  const summaryStr = `candidate ${parts.length > 0 ? parts.join(', ') : 'no significant changes'} with ${regressions.length} regressions and ${improvements.length} improvements`;\n\n  return {\n    baseline: { id: baseline.id, metadata: baseline.metadata },\n    candidate: { id: candidate.id, metadata: candidate.metadata },\n    scorers,\n    regressions,\n    improvements,\n    summary: summaryStr,\n  };\n}\n","import type { AxlRuntime } from '@axlsdk/axl';\nimport type { EvalConfig, EvalResult, EvalItem, EvalSummary } from './types.js';\nimport type { ScorerContext } from './scorer.js';\nimport { randomUUID } from 'node:crypto';\n\nfunction computeStats(scores: number[]): {\n  mean: number;\n  min: number;\n  max: number;\n  p50: number;\n  p95: number;\n} {\n  if (scores.length === 0) return { mean: 0, min: 0, max: 0, p50: 0, p95: 0 };\n  const sorted = [...scores].sort((a, b) => a - b);\n  const mean = sorted.reduce((a, b) => a + b, 0) / sorted.length;\n  const min = sorted[0];\n  const max = sorted[sorted.length - 1];\n  const p50 = sorted[Math.floor(sorted.length * 0.5)];\n  const p95 = sorted[Math.floor(sorted.length * 0.95)];\n  return { mean: round(mean), min: round(min), max: round(max), p50: round(p50), p95: round(p95) };\n}\n\nfunction round(n: number): number {\n  return Math.round(n * 1000) / 1000;\n}\n\nfunction parseCost(cost: string): number {\n  const match = cost.match(/^\\$?([\\d.]+)$/);\n  if (!match) throw new Error(`Invalid cost format: \"${cost}\"`);\n  return parseFloat(match[1]);\n}\n\nexport async function runEval(\n  config: EvalConfig,\n  executeWorkflow: (\n    input: unknown,\n    runtime: AxlRuntime,\n  ) => Promise<{ output: unknown; cost?: number }>,\n  runtime: AxlRuntime,\n): Promise<EvalResult> {\n  const startTime = Date.now();\n  const id = randomUUID();\n  const items = await config.dataset.getItems();\n  const concurrency = config.concurrency ?? 5;\n  const budgetLimit = config.budget ? parseCost(config.budget) : undefined;\n\n  // Create a scorer context that LLM scorers use to resolve providers.\n  const scorerContext: ScorerContext = {\n    resolveProvider: (uri: string) => {\n      if (typeof runtime.resolveProvider !== 'function') {\n        throw new Error(\n          `LLM scorers require a runtime with resolveProvider(). ` +\n            `Ensure you are using a real AxlRuntime instance, not a mock.`,\n        );\n      }\n      return runtime.resolveProvider(uri);\n    },\n  };\n\n  const evalItems: EvalItem[] = [];\n  let totalCost = 0;\n  let budgetExceeded = false;\n\n  async function processItem(item: (typeof items)[0]): Promise<void> {\n    if (budgetExceeded) {\n      evalItems.push({\n        input: item.input,\n        annotations: item.annotations,\n        output: null,\n        error: 'Budget exceeded',\n        scores: {},\n      });\n      return;\n    }\n\n    const evalItem: EvalItem = {\n      input: item.input,\n      annotations: item.annotations,\n      output: null,\n      scores: {},\n    };\n    try {\n      const result = await executeWorkflow(item.input, runtime);\n      evalItem.output = result.output;\n      if (result.cost != null) {\n        totalCost += result.cost;\n      }\n    } catch (err) {\n      evalItem.error = err instanceof Error ? err.message : String(err);\n      evalItems.push(evalItem);\n      return;\n    }\n\n    if (budgetLimit != null && totalCost > budgetLimit) {\n      budgetExceeded = true;\n    }\n\n    for (const scorer of config.scorers) {\n      try {\n        const score = await scorer.score(\n          evalItem.output,\n          item.input,\n          item.annotations,\n          scorerContext,\n        );\n        // Accumulate LLM scorer cost if available\n        if (scorer.isLlm) {\n          const lastCost = (scorer as unknown as { _lastCost?: number })._lastCost;\n          if (lastCost != null) {\n            totalCost += lastCost;\n          }\n        }\n        if (score < 0 || score > 1) {\n          if (!evalItem.scorerErrors) evalItem.scorerErrors = [];\n          evalItem.scorerErrors.push(\n            `Scorer \"${scorer.name}\" returned out-of-range score ${score} for input ${JSON.stringify(item.input)}`,\n          );\n          evalItem.scores[scorer.name] = null;\n        } else {\n          evalItem.scores[scorer.name] = round(score);\n        }\n      } catch (err) {\n        // Accumulate cost even on failure — the LLM call may have succeeded\n        // before a downstream error (e.g., invalid JSON, schema validation)\n        if (scorer.isLlm) {\n          const lastCost = (scorer as unknown as { _lastCost?: number })._lastCost;\n          if (lastCost != null) {\n            totalCost += lastCost;\n          }\n        }\n        if (!evalItem.scorerErrors) evalItem.scorerErrors = [];\n        evalItem.scorerErrors.push(\n          `Scorer \"${scorer.name}\" threw: ${err instanceof Error ? err.message : String(err)}`,\n        );\n        evalItem.scores[scorer.name] = null;\n      }\n    }\n    evalItems.push(evalItem);\n  }\n\n  let index = 0;\n  async function runNext(): Promise<void> {\n    while (index < items.length) {\n      const currentIndex = index++;\n      await processItem(items[currentIndex]);\n    }\n  }\n\n  const workers = Array.from({ length: Math.min(concurrency, items.length) }, () => runNext());\n  await Promise.all(workers);\n\n  const failures = evalItems.filter((i) => i.error).length;\n  const scorerNames = config.scorers.map((s) => s.name);\n  const scorerStats: EvalSummary['scorers'] = {};\n  for (const name of scorerNames) {\n    const scores = evalItems\n      .filter((i) => !i.error && i.scores[name] != null)\n      .map((i) => i.scores[name] as number);\n    scorerStats[name] = computeStats(scores);\n  }\n\n  return {\n    id,\n    workflow: config.workflow,\n    dataset: config.dataset.name,\n    metadata: config.metadata ?? {},\n    timestamp: new Date().toISOString(),\n    totalCost,\n    duration: Date.now() - startTime,\n    items: evalItems,\n    summary: { count: items.length, failures, scorers: scorerStats },\n  };\n}\n"],"mappings":"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","names":["round"]}