@tangle-network/agent-eval 0.17.3 → 0.18.0

package/dist/index.js

@@ -12692,6 +12692,274 @@ function samePopulation(a, b) {
   return b.every((id) => setA.has(id));
 }
 
+// src/multi-shot-optimization.ts
+async function runMultiShotOptimization(config) {
+  validateConfig(config);
+  const scoreAdapter = {
+    score: (args) => scoreOne(config, args.variant, args.scenarioId, args.rep, "search")
+  };
+  const evolution = await runPromptEvolution({
+    runId: config.runId,
+    target: config.target,
+    seedVariants: config.seedVariants,
+    scenarioIds: config.searchScenarioIds,
+    reps: config.reps,
+    generations: config.generations,
+    populationSize: config.populationSize,
+    scoreConcurrency: config.scoreConcurrency ?? 1,
+    scoreAdapter,
+    mutateAdapter: {
+      mutate: (args) => config.mutateAdapter.mutate({
+        ...args,
+        topTrials: args.topTrials,
+        bottomTrials: args.bottomTrials
+      })
+    },
+    objectives: config.objectives ?? defaultMultiShotObjectives(),
+    scalarWeights: config.scalarWeights,
+    earlyStopOnNoImprovement: config.earlyStopOnNoImprovement,
+    cache: config.cache,
+    onProgress: config.onProgress
+  });
+  let gate = null;
+  const baseline = config.seedVariants[0];
+  let promotedVariant = evolution.bestVariant;
+  let promotedAggregate = evolution.bestAggregate;
+  if (config.gate && evolution.bestVariant.id !== baseline.id) {
+    gate = await evaluateMultiShotGate(config, baseline, evolution.bestVariant);
+    if (!gate.decision.promote) {
+      promotedVariant = baseline;
+      promotedAggregate = aggregateFor(evolution, baseline.id);
+    }
+  }
+  return {
+    evolution,
+    searchBestVariant: evolution.bestVariant,
+    searchBestAggregate: evolution.bestAggregate,
+    promotedVariant,
+    promotedAggregate,
+    gate
+  };
+}
+function defaultMultiShotObjectives() {
+  return [
+    { name: "score", direction: "maximize", value: (a) => a.meanScore },
+    { name: "cost", direction: "minimize", value: (a) => a.meanCost }
+  ];
+}
+function trialTraceFromMultiShotTrial(trial) {
+  return {
+    id: `${trial.variantId}/${trial.scenarioId}/r${trial.rep}`,
+    score: trial.score,
+    inputName: trial.scenarioId,
+    expectations: (trial.asi ?? []).map((item, i) => ({
+      id: item.expectationId ?? `asi-${i}`,
+      phrase: item.message,
+      matched: item.matched ?? false
+    })),
+    emitted: trial.emitted ?? traceExcerpt(trial.trace),
+    metrics: trial.metrics
+  };
+}
+async function evaluateMultiShotGate(config, baseline, candidate) {
+  const gateConfig = config.gate;
+  const reps = gateConfig.reps ?? config.reps;
+  const candidateRuns = [];
+  const baselineRuns = [];
+  const searchIds = gateConfig.searchScenarioIds ?? config.searchScenarioIds;
+  for (const scenarioId of searchIds) {
+    for (let rep = 0; rep < reps; rep++) {
+      const seed = seedFor(config, scenarioId, rep);
+      const baseTrial = await scoreOne(config, baseline, scenarioId, rep, "search");
+      const candTrial = await scoreOne(config, candidate, scenarioId, rep, "search");
+      baselineRuns.push(toValidatedRecord(config, baseline, scenarioId, rep, "search", seed, baseTrial));
+      candidateRuns.push(toValidatedRecord(config, candidate, scenarioId, rep, "search", seed, candTrial));
+    }
+  }
+  for (const scenarioId of gateConfig.holdoutScenarioIds) {
+    for (let rep = 0; rep < reps; rep++) {
+      const seed = seedFor(config, scenarioId, rep);
+      const baseTrial = await scoreOne(config, baseline, scenarioId, rep, "holdout");
+      const candTrial = await scoreOne(config, candidate, scenarioId, rep, "holdout");
+      baselineRuns.push(toValidatedRecord(config, baseline, scenarioId, rep, "holdout", seed, baseTrial));
+      candidateRuns.push(toValidatedRecord(config, candidate, scenarioId, rep, "holdout", seed, candTrial));
+    }
+  }
+  const decision = new HeldOutGate(gateConfig.gate).evaluate(candidateRuns, baselineRuns);
+  return { decision, candidateRuns, baselineRuns };
+}
+async function scoreOne(config, variant, scenarioId, rep, split) {
+  const seed = seedFor(config, scenarioId, rep);
+  const input = { variant, scenarioId, rep, split, seed };
+  try {
+    const run = await config.runner.run(input);
+    const scored = await config.scorer.score({ ...input, run });
+    const asi = scored.asi ?? [];
+    return {
+      variantId: variant.id,
+      scenarioId,
+      rep,
+      ok: scored.ok ?? true,
+      score: clamp013(scored.score),
+      cost: scored.costUsd ?? run.costUsd ?? 0,
+      durationMs: scored.durationMs ?? run.durationMs ?? 0,
+      metrics: {
+        ...numericMetrics(scored.metrics),
+        ...asiMetrics(asi)
+      },
+      split,
+      seed,
+      trace: run.trace,
+      asi,
+      emitted: scored.emitted ?? traceExcerpt(run.trace),
+      metadata: scored.metadata
+    };
+  } catch (err) {
+    return {
+      variantId: variant.id,
+      scenarioId,
+      rep,
+      ok: false,
+      score: 0,
+      cost: 0,
+      durationMs: 0,
+      metrics: { error: 1 },
+      error: err instanceof Error ? err.message : String(err),
+      split,
+      seed,
+      asi: [{
+        severity: "critical",
+        message: err instanceof Error ? err.message : String(err),
+        responsibleSurface: config.target
+      }],
+      emitted: ""
+    };
+  }
+}
+function toValidatedRecord(config, variant, scenarioId, rep, split, seed, trial) {
+  const record = config.gate.toRunRecord({ variant, scenarioId, rep, split, seed, trial });
+  return validateRunRecord(record);
+}
+function validateConfig(config) {
+  if (!config.runId.trim()) throw new Error("runMultiShotOptimization: runId must not be empty");
+  if (!config.target.trim()) throw new Error("runMultiShotOptimization: target must not be empty");
+  if (config.seedVariants.length === 0) {
+    throw new Error("runMultiShotOptimization: seedVariants must not be empty");
+  }
+  if (config.searchScenarioIds.length === 0) {
+    throw new Error("runMultiShotOptimization: searchScenarioIds must not be empty");
+  }
+  requirePositiveInteger(config.reps, "reps");
+  requirePositiveInteger(config.generations, "generations");
+  requirePositiveInteger(config.populationSize, "populationSize");
+  if (config.scoreConcurrency !== void 0) requirePositiveInteger(config.scoreConcurrency, "scoreConcurrency");
+  if (config.populationSize < config.seedVariants.length) {
+    throw new Error("runMultiShotOptimization: populationSize must be >= seedVariants.length");
+  }
+  assertUnique(config.seedVariants.map((v) => v.id), "seedVariants.id");
+  assertUnique(config.searchScenarioIds, "searchScenarioIds");
+  if (config.gate) {
+    if (config.gate.holdoutScenarioIds.length === 0) {
+      throw new Error("runMultiShotOptimization: gate.holdoutScenarioIds must not be empty");
+    }
+    if (config.gate.reps !== void 0) requirePositiveInteger(config.gate.reps, "gate.reps");
+    assertUnique(config.gate.holdoutScenarioIds, "gate.holdoutScenarioIds");
+    if (config.gate.searchScenarioIds) assertUnique(config.gate.searchScenarioIds, "gate.searchScenarioIds");
+    const searchIds = new Set(config.searchScenarioIds);
+    for (const id of config.gate.holdoutScenarioIds) {
+      if (searchIds.has(id)) {
+        throw new Error(`runMultiShotOptimization: holdout scenario "${id}" also appears in searchScenarioIds`);
+      }
+    }
+    const baselineId = config.seedVariants[0].id;
+    if (config.gate.gate.baselineKey !== baselineId) {
+      throw new Error(
+        `runMultiShotOptimization: gate.gate.baselineKey must match first seed variant id "${baselineId}"`
+      );
+    }
+  }
+}
+function requirePositiveInteger(value, name) {
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new Error(`runMultiShotOptimization: ${name} must be a positive integer`);
+  }
+}
+function assertUnique(values, name) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const value of values) {
+    if (!value.trim()) throw new Error(`runMultiShotOptimization: ${name} must not contain empty values`);
+    if (seen.has(value)) throw new Error(`runMultiShotOptimization: duplicate ${name} "${value}"`);
+    seen.add(value);
+  }
+}
+function aggregateFor(evolution, variantId) {
+  const final = evolution.generations[evolution.generations.length - 1];
+  const aggregate2 = final?.aggregates.find((a) => a.variantId === variantId);
+  if (!aggregate2) {
+    throw new Error(`runMultiShotOptimization: missing aggregate for variant "${variantId}"`);
+  }
+  return aggregate2;
+}
+function seedFor(config, scenarioId, rep) {
+  const base = config.seedBase ?? 0;
+  return (base + stableHash2(`${scenarioId}${rep}`)) % Number.MAX_SAFE_INTEGER;
+}
+function stableHash2(input) {
+  let h = 2166136261;
+  for (let i = 0; i < input.length; i++) {
+    h ^= input.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  return h >>> 0;
+}
+function clamp013(n) {
+  if (!Number.isFinite(n)) return 0;
+  return Math.max(0, Math.min(1, n));
+}
+function numericMetrics(metrics) {
+  const out = {};
+  for (const [k, v] of Object.entries(metrics ?? {})) {
+    if (Number.isFinite(v)) out[k] = v;
+  }
+  return out;
+}
+function asiMetrics(asi) {
+  const out = { asi: asi.length };
+  for (const item of asi.slice(0, 1e3)) {
+    const sev = normalizeSeverity(item.severity);
+    out[`asi.${sev}`] = (out[`asi.${sev}`] ?? 0) + 1;
+    if (item.responsibleSurface) {
+      const key = `surface.${metricKeySegment(item.responsibleSurface)}`;
+      out[key] = (out[key] ?? 0) + 1;
+    }
+  }
+  return out;
+}
+function normalizeSeverity(severity) {
+  if (severity === "info" || severity === "warning" || severity === "error" || severity === "critical") {
+    return severity;
+  }
+  return "error";
+}
+function metricKeySegment(raw) {
+  return raw.trim().replace(/[^a-zA-Z0-9._-]+/g, "_").slice(0, 80) || "unknown";
+}
+function traceExcerpt(trace) {
+  if (!trace) return void 0;
+  if (typeof trace.output === "string") return trace.output;
+  if (trace.transcript) return trace.transcript;
+  if (trace.turns) {
+    try {
+      const clipped = trace.turns.slice(0, 20);
+      const suffix = trace.turns.length > clipped.length ? ` ... ${trace.turns.length - clipped.length} more turn(s)` : "";
+      return `${JSON.stringify(clipped).slice(0, 2e3)}${suffix}`;
+    } catch {
+      return "[unserializable trace turns]";
+    }
+  }
+  return void 0;
+}
+
 // src/jsonl-trial-cache.ts
 import { appendFileSync as appendFileSync4, existsSync as existsSync6, mkdirSync as mkdirSync4, readFileSync as readFileSync5 } from "fs";
 import { dirname as dirname4 } from "path";
@@ -13811,6 +14079,7 @@ export {
   decideReferenceReplayPromotion,
   decideReferenceReplayRunPromotion,
   defaultJudges,
+  defaultMultiShotObjectives,
   defaultReferenceReplayMatcher,
   deployGateLayer,
   distillPlaybook,
@@ -13948,6 +14217,7 @@ export {
   runJudgeFleet,
   runKeywordCoverageJudge,
   runKeywordCoverageJudgeUrl,
+  runMultiShotOptimization,
   runPromptEvolution,
   runProposeReview,
   runProposeReviewAsControlLoop,
@@ -13991,6 +14261,7 @@ export {
   toolSpans,
   toolSuccessRubric,
   toolWasteView,
+  trialTraceFromMultiShotTrial,
   typoMutator,
   urlContains,
   validateRunRecord,