@elizaos/plugin-training 2.0.3-beta.6 → 2.0.3-beta.7

package/dist/optimizers/bootstrap-fewshot.js

@@ -0,0 +1,92 @@
+const DEMONSTRATION_HEADER = "Demonstrations:";
+function trimDemonstrationInput(rawInput) {
+  const userMatch = rawInput.match(
+    /(?:^|\n)user(?:\s+message)?\s*:\s*([^\n]+(?:\n(?!\w+:)[^\n]+)*)/i
+  ) ?? rawInput.match(/(?:^|\n)user_message\s*:\s*([^\n]+(?:\n(?!\w+:)[^\n]+)*)/i);
+  const candidate = userMatch?.[1]?.trim();
+  if (candidate && candidate.length > 0 && candidate.length <= 600) {
+    return candidate;
+  }
+  if (candidate && candidate.length > 0) {
+    return `${candidate.slice(0, 600).trimEnd()} \u2026`;
+  }
+  if (rawInput.length <= 600) return rawInput;
+  return rawInput.slice(0, 400).trimEnd() + "\n\u2026\n" + rawInput.slice(-200).trimStart();
+}
+function renderDemonstrations(examples) {
+  if (examples.length === 0) return "";
+  const lines = [DEMONSTRATION_HEADER, ""];
+  let idx = 1;
+  for (const example of examples) {
+    lines.push(`Example ${idx}:`);
+    lines.push(`Input:
+${trimDemonstrationInput(example.input.user)}`);
+    lines.push(`Expected:
+${example.expectedOutput}`);
+    lines.push("");
+    idx += 1;
+  }
+  return lines.join("\n").trimEnd();
+}
+function withDemonstrations(baseline, examples) {
+  if (examples.length === 0) return baseline;
+  const demos = renderDemonstrations(examples);
+  return `${baseline.trimEnd()}
+
+${demos}
+`;
+}
+async function runBootstrapFewshot(input) {
+  const k = Math.max(1, input.options?.k ?? 5);
+  const lineage = [];
+  const baselineScore = await input.scorer(input.baselinePrompt, input.dataset);
+  lineage.push({
+    round: 0,
+    variant: 0,
+    score: baselineScore,
+    notes: "baseline"
+  });
+  const ranked = await rankExamples(input);
+  const fewShot = ranked.slice(0, Math.min(k, ranked.length));
+  const optimizedPrompt = withDemonstrations(input.baselinePrompt, fewShot);
+  const optimizedScore = await input.scorer(optimizedPrompt, input.dataset);
+  lineage.push({
+    round: 1,
+    variant: 1,
+    score: optimizedScore,
+    notes: `injected ${fewShot.length} demonstrations`
+  });
+  return {
+    optimizedPrompt,
+    score: optimizedScore,
+    baseline: baselineScore,
+    lineage,
+    fewShotExamples: fewShot
+  };
+}
+async function rankExamples(input) {
+  if (input.options?.rankByScorer) {
+    const scored = [];
+    for (const example of input.dataset) {
+      const score = await input.scorer(input.baselinePrompt, [example]);
+      scored.push({ example, score });
+    }
+    scored.sort(
+      (a, b) => b.score - a.score || (b.example.reward ?? 0) - (a.example.reward ?? 0)
+    );
+    return scored.map((entry) => entry.example);
+  }
+  const ordered = input.dataset.map((example, index) => ({
+    example,
+    index,
+    reward: example.reward ?? 0
+  }));
+  ordered.sort((a, b) => b.reward - a.reward || a.index - b.index);
+  return ordered.map((entry) => entry.example);
+}
+export {
+  renderDemonstrations,
+  runBootstrapFewshot,
+  withDemonstrations
+};
+//# sourceMappingURL=bootstrap-fewshot.js.map

package/dist/optimizers/bootstrap-fewshot.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/optimizers/bootstrap-fewshot.ts"],"sourcesContent":["/**\n * Bootstrap-fewshot optimizer.\n *\n * Picks the top-K examples from the dataset (ranked by reward, then by\n * agreement against the baseline) and injects them as in-context\n * demonstrations into the prompt. The output prompt is the baseline plus a\n * `Demonstrations:` block that the runtime threads through unchanged.\n *\n * This is the cheapest optimizer — it does not propose new instructions, only\n * conditions the existing prompt on a curated few-shot set. It is the fallback\n * used when threshold-fired bootstrap runs need fast turnaround.\n */\n\nimport type {\n  LlmAdapter,\n  OptimizationExample,\n  OptimizerLineageEntry,\n  OptimizerResult,\n  PromptScorer,\n} from \"./types.js\";\n\nexport interface BootstrapFewshotOptions {\n  /** Number of demonstrations to inject. Defaults to 5. */\n  k?: number;\n  /**\n   * Optional scorer override. When supplied, examples are ranked by score\n   * against the baseline prompt instead of by `example.reward`.\n   */\n  rankByScorer?: boolean;\n}\n\nexport interface BootstrapFewshotInput {\n  baselinePrompt: string;\n  dataset: OptimizationExample[];\n  scorer: PromptScorer;\n  llm: LlmAdapter;\n  options?: BootstrapFewshotOptions;\n}\n\nconst DEMONSTRATION_HEADER = \"Demonstrations:\";\n\n/**\n * Trim a demonstration's `input.user` down to the bits that meaningfully\n * teach the model. The recorded planner inputs include the full provider\n * block + tool catalog + conversation history (often ~30K chars), but for\n * ICL we only need the user's current-turn request. Pulls the user message\n * out of the recorded transcript, falls back to a head/tail truncation if\n * we can't find one cleanly. Capped at ~600 chars so 5 demos stay well\n * under the model's context budget.\n */\nfunction trimDemonstrationInput(rawInput: string): string {\n  // Look for a `User:` / `User message:` / final speaker line. Recorded\n  // planner inputs typically end with \"<TURN-N>\\nuser: <message>\" or a\n  // similar marker.\n  const userMatch =\n    rawInput.match(\n      /(?:^|\\n)user(?:\\s+message)?\\s*:\\s*([^\\n]+(?:\\n(?!\\w+:)[^\\n]+)*)/i,\n    ) ??\n    rawInput.match(/(?:^|\\n)user_message\\s*:\\s*([^\\n]+(?:\\n(?!\\w+:)[^\\n]+)*)/i);\n  const candidate = userMatch?.[1]?.trim();\n  if (candidate && candidate.length > 0 && candidate.length <= 600) {\n    return candidate;\n  }\n  if (candidate && candidate.length > 0) {\n    return `${candidate.slice(0, 600).trimEnd()} …`;\n  }\n  // Fallback: first 400 chars + \"...\" + last 200 chars so the model sees\n  // both the framing and the request without the middle bulk.\n  if (rawInput.length <= 600) return rawInput;\n  return (\n    rawInput.slice(0, 400).trimEnd() +\n    \"\\n…\\n\" +\n    rawInput.slice(-200).trimStart()\n  );\n}\n\n/**\n * Render a demonstration block exactly the way the runtime wires it back into\n * the system prompt. Public so `OptimizedPromptService` can rebuild the\n * combined prompt at load time.\n */\nexport function renderDemonstrations(examples: OptimizationExample[]): string {\n  if (examples.length === 0) return \"\";\n  const lines: string[] = [DEMONSTRATION_HEADER, \"\"];\n  let idx = 1;\n  for (const example of examples) {\n    lines.push(`Example ${idx}:`);\n    lines.push(`Input:\\n${trimDemonstrationInput(example.input.user)}`);\n    lines.push(`Expected:\\n${example.expectedOutput}`);\n    lines.push(\"\");\n    idx += 1;\n  }\n  return lines.join(\"\\n\").trimEnd();\n}\n\n/**\n * Combine a baseline prompt with a rendered demonstration block. Idempotent\n * when `examples` is empty.\n */\nexport function withDemonstrations(\n  baseline: string,\n  examples: OptimizationExample[],\n): string {\n  if (examples.length === 0) return baseline;\n  const demos = renderDemonstrations(examples);\n  return `${baseline.trimEnd()}\\n\\n${demos}\\n`;\n}\n\nexport async function runBootstrapFewshot(\n  input: BootstrapFewshotInput,\n): Promise<OptimizerResult> {\n  const k = Math.max(1, input.options?.k ?? 5);\n  const lineage: OptimizerLineageEntry[] = [];\n  const baselineScore = await input.scorer(input.baselinePrompt, input.dataset);\n  lineage.push({\n    round: 0,\n    variant: 0,\n    score: baselineScore,\n    notes: \"baseline\",\n  });\n\n  const ranked = await rankExamples(input);\n  const fewShot = ranked.slice(0, Math.min(k, ranked.length));\n\n  const optimizedPrompt = withDemonstrations(input.baselinePrompt, fewShot);\n  const optimizedScore = await input.scorer(optimizedPrompt, input.dataset);\n  lineage.push({\n    round: 1,\n    variant: 1,\n    score: optimizedScore,\n    notes: `injected ${fewShot.length} demonstrations`,\n  });\n\n  return {\n    optimizedPrompt,\n    score: optimizedScore,\n    baseline: baselineScore,\n    lineage,\n    fewShotExamples: fewShot,\n  };\n}\n\nasync function rankExamples(\n  input: BootstrapFewshotInput,\n): Promise<OptimizationExample[]> {\n  if (input.options?.rankByScorer) {\n    const scored: Array<{ example: OptimizationExample; score: number }> = [];\n    for (const example of input.dataset) {\n      const score = await input.scorer(input.baselinePrompt, [example]);\n      scored.push({ example, score });\n    }\n    // Pull demonstrations the baseline already gets right; they are the\n    // highest-confidence anchors for the model to imitate. Tie-break by\n    // reward when the scorer is uninformative.\n    scored.sort(\n      (a, b) =>\n        b.score - a.score || (b.example.reward ?? 0) - (a.example.reward ?? 0),\n    );\n    return scored.map((entry) => entry.example);\n  }\n\n  // Reward-first ranking. Examples without a recorded reward fall through\n  // to a stable order at the back so the dataset's natural ordering wins\n  // the tie-break.\n  const ordered = input.dataset.map((example, index) => ({\n    example,\n    index,\n    reward: example.reward ?? 0,\n  }));\n  ordered.sort((a, b) => b.reward - a.reward || a.index - b.index);\n  return ordered.map((entry) => entry.example);\n}\n"],"mappings":"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","names":[]}

package/dist/optimizers/gepa.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Formal GEPA optimizer (Goyal et al. 2024, https://arxiv.org/abs/2407.10718).
+ *
+ * Distinct from `prompt-evolution.ts` (plain genetic mutation):
+ *   1. Reflective feedback — each generation the LLM is shown
+ *      (prompt, predicted, expected) and asked WHY it failed. The diagnostic
+ *      text feeds the next mutation step.
+ *   2. Pareto-frontier selection over (score, prompt_token_count). Survivors
+ *      are the non-dominated set, not the score top-half.
+ *   3. Two mutation flavors per survivor: feedback-guided rewrite and
+ *      token-compression rewrite.
+ *   4. Crossover step — top two by score merged via LLM.
+ *
+ * Returns the best-score candidate from the final Pareto frontier. Ties on
+ * score broken by fewer tokens. Lineage records (round, variant, score,
+ * feedback excerpt) so OptimizedPromptArtifact consumes it transparently.
+ */
+import type { LlmAdapter, OptimizationExample, OptimizerResult, PromptScorer } from "./types.js";
+export interface GepaOptions {
+    /** Population size. Defaults to 12. */
+    population?: number;
+    /** Generations. Defaults to 8. */
+    generations?: number;
+    /** Held-out examples scored per candidate. Defaults to all examples. */
+    scoringSubset?: number;
+    /** Examples shown per reflection call. Defaults to 3. */
+    reflectionBatchSize?: number;
+    /** Mutation sampling temperature. Defaults to 0.8. */
+    temperature?: number;
+    /** Reflection sampling temperature. Defaults to 0.4. */
+    reflectionTemperature?: number;
+    /** Mutation completion max tokens. Defaults to 1024. */
+    maxTokens?: number;
+    /** Reflection completion max tokens. Defaults to 512. */
+    reflectionMaxTokens?: number;
+    /** Enable crossover step. Defaults to true. */
+    crossover?: boolean;
+    /** Deterministic RNG (tests). Defaults to Math.random. */
+    rng?: () => number;
+}
+export interface GepaInput {
+    baselinePrompt: string;
+    dataset: OptimizationExample[];
+    scorer: PromptScorer;
+    llm: LlmAdapter;
+    options?: GepaOptions;
+}
+interface Candidate {
+    prompt: string;
+    score: number;
+    tokens: number;
+    feedback: string;
+    origin: string;
+}
+export declare function runGepa(input: GepaInput): Promise<OptimizerResult>;
+/**
+ * Pareto frontier over (score asc, tokens asc): a candidate is dominated when
+ * another has strictly higher score AND fewer-or-equal tokens, or
+ * higher-or-equal score AND strictly fewer tokens.
+ */
+export declare function paretoFrontier(pool: Candidate[]): Candidate[];
+export {};
+//# sourceMappingURL=gepa.d.ts.map

package/dist/optimizers/gepa.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gepa.d.ts","sourceRoot":"","sources":["../../src/optimizers/gepa.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,KAAK,EACV,UAAU,EACV,mBAAmB,EAEnB,eAAe,EACf,YAAY,EACb,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,WAAW;IAC1B,uCAAuC;IACvC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kCAAkC;IAClC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wEAAwE;IACxE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,yDAAyD;IACzD,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,sDAAsD;IACtD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wDAAwD;IACxD,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,wDAAwD;IACxD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,+CAA+C;IAC/C,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,0DAA0D;IAC1D,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,SAAS;IACxB,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,mBAAmB,EAAE,CAAC;IAC/B,MAAM,EAAE,YAAY,CAAC;IACrB,GAAG,EAAE,UAAU,CAAC;IAChB,OAAO,CAAC,EAAE,WAAW,CAAC;CACvB;AAkBD,UAAU,SAAS;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB;AAaD,wBAAsB,OAAO,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,eAAe,CAAC,CA0HxE;AAoGD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,EAAE,GAAG,SAAS,EAAE,CAuB7D"}

package/dist/optimizers/gepa.js

@@ -0,0 +1,232 @@
+import { subsample } from "./scoring.js";
+const SYS_FEEDBACK = `Revise the SYSTEM PROMPT below based on observed failure analysis.
+
+You will receive the current prompt and a short feedback note explaining what went wrong. Produce a revised prompt that addresses the feedback. Preserve the task contract (inputs, outputs, format) and every literal placeholder ({{agentName}}, {{providers}}, etc.) byte-identical. Output only the revised prompt body. No commentary, no fenced code blocks.`;
+const SYS_COMPRESS = `Reduce the SYSTEM PROMPT below to its essentials.
+
+Rewrite it shorter while preserving every contract guarantee. Drop redundant phrasing, collapse parallel rules, remove decorative bullets and meta-commentary. Keep every literal placeholder byte-identical. Output only the revised prompt body. No commentary, no fenced code blocks.`;
+const SYS_CROSSOVER = `Merge two candidate SYSTEM PROMPTS into one.
+
+You will receive PROMPT A and PROMPT B. Produce a single prompt that takes the strongest guidance from each. Preserve the task contract and every literal placeholder. Do not exceed 1.2x the longer parent's character count. Output only the merged prompt body. No commentary, no fenced code blocks.`;
+const SYS_REFLECT = `You are diagnosing why a SYSTEM PROMPT is failing.
+
+You will receive the current prompt and a small batch of examples: each shows the user input, the model's actual output, and the expected output. Write a SHORT diagnostic (max 4 sentences) naming the concrete failure mode and a specific change to the prompt that would fix it. No filler. No restatement of the prompt. No fenced code blocks. Output plain text only.`;
+async function runGepa(input) {
+  const population = Math.max(2, input.options?.population ?? 12);
+  const generations = input.options?.generations ?? 8;
+  const rng = input.options?.rng ?? Math.random;
+  const lineage = [];
+  const heldOut = typeof input.options?.scoringSubset === "number" ? subsample(input.dataset, input.options.scoringSubset, rng) : input.dataset;
+  const ctx = {
+    llm: input.llm,
+    scorer: input.scorer,
+    heldOut,
+    reflectionBatchSize: Math.max(1, input.options?.reflectionBatchSize ?? 3),
+    temperature: input.options?.temperature ?? 0.8,
+    reflectionTemperature: input.options?.reflectionTemperature ?? 0.4,
+    maxTokens: input.options?.maxTokens ?? 1024,
+    reflectionMaxTokens: input.options?.reflectionMaxTokens ?? 512
+  };
+  const enableCrossover = input.options?.crossover ?? true;
+  const baseline = await scoreCandidate(
+    ctx,
+    input.baselinePrompt,
+    "baseline",
+    0,
+    0,
+    lineage
+  );
+  let pool = [baseline];
+  for (let i = 1; i < population; i += 1) {
+    const mode = i % 2 === 0 ? "compress" : "feedback";
+    const seed = await mutate(
+      ctx,
+      input.baselinePrompt,
+      baseline.feedback,
+      mode
+    );
+    pool.push(await scoreCandidate(ctx, seed, `seed-${mode}`, 0, i, lineage));
+  }
+  for (let gen = 1; gen <= generations; gen += 1) {
+    const frontier = paretoFrontier(pool);
+    const next = [...frontier];
+    let variantIdx = next.length;
+    for (const parent of frontier) {
+      if (next.length >= population) break;
+      const child = await mutate(
+        ctx,
+        parent.prompt,
+        parent.feedback,
+        "feedback"
+      );
+      next.push(
+        await scoreCandidate(
+          ctx,
+          child,
+          "feedback-mut",
+          gen,
+          variantIdx++,
+          lineage
+        )
+      );
+      if (next.length >= population) break;
+      const comp = await mutate(ctx, parent.prompt, "", "compress");
+      next.push(
+        await scoreCandidate(
+          ctx,
+          comp,
+          "compress-mut",
+          gen,
+          variantIdx++,
+          lineage
+        )
+      );
+    }
+    if (enableCrossover && next.length < population && frontier.length >= 2) {
+      const [a, b] = [...frontier].sort((x, y) => y.score - x.score);
+      if (a && b && a.prompt !== b.prompt) {
+        const merged = await llmCall(
+          ctx.llm,
+          SYS_CROSSOVER,
+          `PROMPT A:
+${a.prompt}
+
+PROMPT B:
+${b.prompt}`,
+          ctx.temperature,
+          ctx.maxTokens,
+          a.prompt
+        );
+        next.push(
+          await scoreCandidate(
+            ctx,
+            merged,
+            "crossover",
+            gen,
+            variantIdx++,
+            lineage
+          )
+        );
+      }
+    }
+    pool = next;
+  }
+  const finalFrontier = paretoFrontier(pool);
+  const best = finalFrontier.reduce((acc, cur) => {
+    if (cur.score > acc.score) return cur;
+    if (cur.score === acc.score && cur.tokens < acc.tokens) return cur;
+    return acc;
+  }, finalFrontier[0] ?? pool[0]);
+  return {
+    optimizedPrompt: best.prompt,
+    score: best.score,
+    baseline: baseline.score,
+    lineage
+  };
+}
+async function scoreCandidate(ctx, prompt, origin, round, variant, lineage) {
+  const score = await ctx.scorer(prompt, ctx.heldOut);
+  const feedback = await reflect(ctx, prompt);
+  const tokens = approxTokenCount(prompt);
+  const note = origin === "baseline" ? "baseline" : origin === "compress-mut" || origin === "seed-compress" ? `${origin} | tokens=${tokens}` : `${origin} | ${truncate(feedback, 120)}`;
+  lineage.push({ round, variant, score, notes: note });
+  return { prompt, score, tokens, feedback, origin };
+}
+async function mutate(ctx, prompt, feedback, mode) {
+  if (mode === "compress") {
+    return llmCall(
+      ctx.llm,
+      SYS_COMPRESS,
+      prompt,
+      ctx.temperature,
+      ctx.maxTokens,
+      prompt
+    );
+  }
+  const user = `Current prompt:
+${prompt}
+
+Failure analysis:
+${feedback || "(none provided \u2014 explore a phrasing change)"}`;
+  return llmCall(
+    ctx.llm,
+    SYS_FEEDBACK,
+    user,
+    ctx.temperature,
+    ctx.maxTokens,
+    prompt
+  );
+}
+async function reflect(ctx, prompt) {
+  if (ctx.heldOut.length === 0) return "";
+  const batch = ctx.heldOut.slice(0, ctx.reflectionBatchSize);
+  const transcripts = [];
+  for (let i = 0; i < batch.length; i += 1) {
+    const ex = batch[i];
+    const actual = await ctx.llm.complete({
+      system: prompt,
+      user: ex.input.user,
+      temperature: 0,
+      maxTokens: 256
+    });
+    transcripts.push(
+      `Example ${i + 1}:
+User: ${truncate(ex.input.user, 400)}
+Actual: ${truncate(actual, 400)}
+Expected: ${truncate(ex.expectedOutput, 400)}`
+    );
+  }
+  const user = `Prompt:
+${prompt}
+
+${transcripts.join("\n\n")}`;
+  return llmCall(
+    ctx.llm,
+    SYS_REFLECT,
+    user,
+    ctx.reflectionTemperature,
+    ctx.reflectionMaxTokens,
+    ""
+  );
+}
+async function llmCall(llm, system, user, temperature, maxTokens, fallback) {
+  const result = await llm.complete({ system, user, temperature, maxTokens });
+  const cleaned = result.trim();
+  return cleaned.length > 0 ? cleaned : fallback;
+}
+function paretoFrontier(pool) {
+  const frontier = [];
+  for (const cur of pool) {
+    let dominated = false;
+    for (const other of pool) {
+      if (other === cur) continue;
+      const strictlyBetterScore = other.score > cur.score;
+      const strictlyFewerTokens = other.tokens < cur.tokens;
+      const noWorseScore = other.score >= cur.score;
+      const noMoreTokens = other.tokens <= cur.tokens;
+      if (strictlyBetterScore && noMoreTokens || noWorseScore && strictlyFewerTokens) {
+        dominated = true;
+        break;
+      }
+    }
+    if (!dominated && !frontier.some((c) => c.prompt === cur.prompt)) {
+      frontier.push(cur);
+    }
+  }
+  return frontier;
+}
+function approxTokenCount(text) {
+  if (text.length === 0) return 0;
+  const words = text.trim().split(/\s+/).filter((s) => s.length > 0).length;
+  const puncts = (text.match(/[.,;:!?(){}[\]"'`]/g) ?? []).length;
+  return words + Math.floor(puncts / 2);
+}
+function truncate(text, max) {
+  if (text.length <= max) return text;
+  return `${text.slice(0, max - 1)}\u2026`;
+}
+export {
+  paretoFrontier,
+  runGepa
+};
+//# sourceMappingURL=gepa.js.map

package/dist/optimizers/gepa.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/optimizers/gepa.ts"],"sourcesContent":["/**\n * Formal GEPA optimizer (Goyal et al. 2024, https://arxiv.org/abs/2407.10718).\n *\n * Distinct from `prompt-evolution.ts` (plain genetic mutation):\n *   1. Reflective feedback — each generation the LLM is shown\n *      (prompt, predicted, expected) and asked WHY it failed. The diagnostic\n *      text feeds the next mutation step.\n *   2. Pareto-frontier selection over (score, prompt_token_count). Survivors\n *      are the non-dominated set, not the score top-half.\n *   3. Two mutation flavors per survivor: feedback-guided rewrite and\n *      token-compression rewrite.\n *   4. Crossover step — top two by score merged via LLM.\n *\n * Returns the best-score candidate from the final Pareto frontier. Ties on\n * score broken by fewer tokens. Lineage records (round, variant, score,\n * feedback excerpt) so OptimizedPromptArtifact consumes it transparently.\n */\n\nimport { subsample } from \"./scoring.js\";\nimport type {\n  LlmAdapter,\n  OptimizationExample,\n  OptimizerLineageEntry,\n  OptimizerResult,\n  PromptScorer,\n} from \"./types.js\";\n\nexport interface GepaOptions {\n  /** Population size. Defaults to 12. */\n  population?: number;\n  /** Generations. Defaults to 8. */\n  generations?: number;\n  /** Held-out examples scored per candidate. Defaults to all examples. */\n  scoringSubset?: number;\n  /** Examples shown per reflection call. Defaults to 3. */\n  reflectionBatchSize?: number;\n  /** Mutation sampling temperature. Defaults to 0.8. */\n  temperature?: number;\n  /** Reflection sampling temperature. Defaults to 0.4. */\n  reflectionTemperature?: number;\n  /** Mutation completion max tokens. Defaults to 1024. */\n  maxTokens?: number;\n  /** Reflection completion max tokens. Defaults to 512. */\n  reflectionMaxTokens?: number;\n  /** Enable crossover step. Defaults to true. */\n  crossover?: boolean;\n  /** Deterministic RNG (tests). Defaults to Math.random. */\n  rng?: () => number;\n}\n\nexport interface GepaInput {\n  baselinePrompt: string;\n  dataset: OptimizationExample[];\n  scorer: PromptScorer;\n  llm: LlmAdapter;\n  options?: GepaOptions;\n}\n\nconst SYS_FEEDBACK = `Revise the SYSTEM PROMPT below based on observed failure analysis.\n\nYou will receive the current prompt and a short feedback note explaining what went wrong. Produce a revised prompt that addresses the feedback. Preserve the task contract (inputs, outputs, format) and every literal placeholder ({{agentName}}, {{providers}}, etc.) byte-identical. Output only the revised prompt body. No commentary, no fenced code blocks.`;\n\nconst SYS_COMPRESS = `Reduce the SYSTEM PROMPT below to its essentials.\n\nRewrite it shorter while preserving every contract guarantee. Drop redundant phrasing, collapse parallel rules, remove decorative bullets and meta-commentary. Keep every literal placeholder byte-identical. Output only the revised prompt body. No commentary, no fenced code blocks.`;\n\nconst SYS_CROSSOVER = `Merge two candidate SYSTEM PROMPTS into one.\n\nYou will receive PROMPT A and PROMPT B. Produce a single prompt that takes the strongest guidance from each. Preserve the task contract and every literal placeholder. Do not exceed 1.2x the longer parent's character count. Output only the merged prompt body. No commentary, no fenced code blocks.`;\n\nconst SYS_REFLECT = `You are diagnosing why a SYSTEM PROMPT is failing.\n\nYou will receive the current prompt and a small batch of examples: each shows the user input, the model's actual output, and the expected output. Write a SHORT diagnostic (max 4 sentences) naming the concrete failure mode and a specific change to the prompt that would fix it. No filler. No restatement of the prompt. No fenced code blocks. Output plain text only.`;\n\ninterface Candidate {\n  prompt: string;\n  score: number;\n  tokens: number;\n  feedback: string;\n  origin: string;\n}\n\ninterface Ctx {\n  llm: LlmAdapter;\n  scorer: PromptScorer;\n  heldOut: OptimizationExample[];\n  reflectionBatchSize: number;\n  temperature: number;\n  reflectionTemperature: number;\n  maxTokens: number;\n  reflectionMaxTokens: number;\n}\n\nexport async function runGepa(input: GepaInput): Promise<OptimizerResult> {\n  const population = Math.max(2, input.options?.population ?? 12);\n  const generations = input.options?.generations ?? 8;\n  const rng = input.options?.rng ?? Math.random;\n  const lineage: OptimizerLineageEntry[] = [];\n  const heldOut =\n    typeof input.options?.scoringSubset === \"number\"\n      ? subsample(input.dataset, input.options.scoringSubset, rng)\n      : input.dataset;\n  const ctx: Ctx = {\n    llm: input.llm,\n    scorer: input.scorer,\n    heldOut,\n    reflectionBatchSize: Math.max(1, input.options?.reflectionBatchSize ?? 3),\n    temperature: input.options?.temperature ?? 0.8,\n    reflectionTemperature: input.options?.reflectionTemperature ?? 0.4,\n    maxTokens: input.options?.maxTokens ?? 1024,\n    reflectionMaxTokens: input.options?.reflectionMaxTokens ?? 512,\n  };\n  const enableCrossover = input.options?.crossover ?? true;\n\n  const baseline = await scoreCandidate(\n    ctx,\n    input.baselinePrompt,\n    \"baseline\",\n    0,\n    0,\n    lineage,\n  );\n  let pool: Candidate[] = [baseline];\n\n  // Seed: alternate feedback-guided and compression mutations of the baseline.\n  for (let i = 1; i < population; i += 1) {\n    const mode: \"feedback\" | \"compress\" = i % 2 === 0 ? \"compress\" : \"feedback\";\n    const seed = await mutate(\n      ctx,\n      input.baselinePrompt,\n      baseline.feedback,\n      mode,\n    );\n    pool.push(await scoreCandidate(ctx, seed, `seed-${mode}`, 0, i, lineage));\n  }\n\n  for (let gen = 1; gen <= generations; gen += 1) {\n    const frontier = paretoFrontier(pool);\n    const next: Candidate[] = [...frontier];\n    let variantIdx = next.length;\n\n    // K=2 children per survivor: one feedback-guided, one compression.\n    for (const parent of frontier) {\n      if (next.length >= population) break;\n      const child = await mutate(\n        ctx,\n        parent.prompt,\n        parent.feedback,\n        \"feedback\",\n      );\n      next.push(\n        await scoreCandidate(\n          ctx,\n          child,\n          \"feedback-mut\",\n          gen,\n          variantIdx++,\n          lineage,\n        ),\n      );\n      if (next.length >= population) break;\n      const comp = await mutate(ctx, parent.prompt, \"\", \"compress\");\n      next.push(\n        await scoreCandidate(\n          ctx,\n          comp,\n          \"compress-mut\",\n          gen,\n          variantIdx++,\n          lineage,\n        ),\n      );\n    }\n\n    // Crossover: merge the top two on the frontier when budget remains.\n    if (enableCrossover && next.length < population && frontier.length >= 2) {\n      const [a, b] = [...frontier].sort((x, y) => y.score - x.score);\n      if (a && b && a.prompt !== b.prompt) {\n        const merged = await llmCall(\n          ctx.llm,\n          SYS_CROSSOVER,\n          `PROMPT A:\\n${a.prompt}\\n\\nPROMPT B:\\n${b.prompt}`,\n          ctx.temperature,\n          ctx.maxTokens,\n          a.prompt,\n        );\n        next.push(\n          await scoreCandidate(\n            ctx,\n            merged,\n            \"crossover\",\n            gen,\n            variantIdx++,\n            lineage,\n          ),\n        );\n      }\n    }\n\n    pool = next;\n  }\n\n  const finalFrontier = paretoFrontier(pool);\n  const best = finalFrontier.reduce<Candidate>((acc, cur) => {\n    if (cur.score > acc.score) return cur;\n    if (cur.score === acc.score && cur.tokens < acc.tokens) return cur;\n    return acc;\n  }, finalFrontier[0] ?? pool[0]!);\n\n  return {\n    optimizedPrompt: best.prompt,\n    score: best.score,\n    baseline: baseline.score,\n    lineage,\n  };\n}\n\n/**\n * Score a candidate prompt, run reflection on it, push lineage, and return\n * the populated Candidate. Centralized so seed / generation / crossover\n * paths share identical bookkeeping.\n */\nasync function scoreCandidate(\n  ctx: Ctx,\n  prompt: string,\n  origin: string,\n  round: number,\n  variant: number,\n  lineage: OptimizerLineageEntry[],\n): Promise<Candidate> {\n  const score = await ctx.scorer(prompt, ctx.heldOut);\n  const feedback = await reflect(ctx, prompt);\n  const tokens = approxTokenCount(prompt);\n  const note =\n    origin === \"baseline\"\n      ? \"baseline\"\n      : origin === \"compress-mut\" || origin === \"seed-compress\"\n        ? `${origin} | tokens=${tokens}`\n        : `${origin} | ${truncate(feedback, 120)}`;\n  lineage.push({ round, variant, score, notes: note });\n  return { prompt, score, tokens, feedback, origin };\n}\n\nasync function mutate(\n  ctx: Ctx,\n  prompt: string,\n  feedback: string,\n  mode: \"feedback\" | \"compress\",\n): Promise<string> {\n  if (mode === \"compress\") {\n    return llmCall(\n      ctx.llm,\n      SYS_COMPRESS,\n      prompt,\n      ctx.temperature,\n      ctx.maxTokens,\n      prompt,\n    );\n  }\n  const user = `Current prompt:\\n${prompt}\\n\\nFailure analysis:\\n${feedback || \"(none provided — explore a phrasing change)\"}`;\n  return llmCall(\n    ctx.llm,\n    SYS_FEEDBACK,\n    user,\n    ctx.temperature,\n    ctx.maxTokens,\n    prompt,\n  );\n}\n\n/**\n * Run the prompt against a small batch of examples, then ask the LLM to\n * diagnose what went wrong. The diagnostic feeds the next mutation step —\n * this is the \"reflective evolution\" half of GEPA.\n */\nasync function reflect(ctx: Ctx, prompt: string): Promise<string> {\n  if (ctx.heldOut.length === 0) return \"\";\n  const batch = ctx.heldOut.slice(0, ctx.reflectionBatchSize);\n  const transcripts: string[] = [];\n  for (let i = 0; i < batch.length; i += 1) {\n    const ex = batch[i]!;\n    const actual = await ctx.llm.complete({\n      system: prompt,\n      user: ex.input.user,\n      temperature: 0,\n      maxTokens: 256,\n    });\n    transcripts.push(\n      `Example ${i + 1}:\\nUser: ${truncate(ex.input.user, 400)}\\nActual: ${truncate(actual, 400)}\\nExpected: ${truncate(ex.expectedOutput, 400)}`,\n    );\n  }\n  const user = `Prompt:\\n${prompt}\\n\\n${transcripts.join(\"\\n\\n\")}`;\n  return llmCall(\n    ctx.llm,\n    SYS_REFLECT,\n    user,\n    ctx.reflectionTemperature,\n    ctx.reflectionMaxTokens,\n    \"\",\n  );\n}\n\nasync function llmCall(\n  llm: LlmAdapter,\n  system: string,\n  user: string,\n  temperature: number,\n  maxTokens: number,\n  fallback: string,\n): Promise<string> {\n  const result = await llm.complete({ system, user, temperature, maxTokens });\n  const cleaned = result.trim();\n  return cleaned.length > 0 ? cleaned : fallback;\n}\n\n/**\n * Pareto frontier over (score asc, tokens asc): a candidate is dominated when\n * another has strictly higher score AND fewer-or-equal tokens, or\n * higher-or-equal score AND strictly fewer tokens.\n */\nexport function paretoFrontier(pool: Candidate[]): Candidate[] {\n  const frontier: Candidate[] = [];\n  for (const cur of pool) {\n    let dominated = false;\n    for (const other of pool) {\n      if (other === cur) continue;\n      const strictlyBetterScore = other.score > cur.score;\n      const strictlyFewerTokens = other.tokens < cur.tokens;\n      const noWorseScore = other.score >= cur.score;\n      const noMoreTokens = other.tokens <= cur.tokens;\n      if (\n        (strictlyBetterScore && noMoreTokens) ||\n        (noWorseScore && strictlyFewerTokens)\n      ) {\n        dominated = true;\n        break;\n      }\n    }\n    if (!dominated && !frontier.some((c) => c.prompt === cur.prompt)) {\n      frontier.push(cur);\n    }\n  }\n  return frontier;\n}\n\n/**\n * Cheap token-count proxy: whitespace word count + half the punctuation\n * count. Good enough for relative Pareto comparisons; never persisted.\n */\nfunction approxTokenCount(text: string): number {\n  if (text.length === 0) return 0;\n  const words = text\n    .trim()\n    .split(/\\s+/)\n    .filter((s) => s.length > 0).length;\n  const puncts = (text.match(/[.,;:!?(){}[\\]\"'`]/g) ?? []).length;\n  return words + Math.floor(puncts / 2);\n}\n\nfunction truncate(text: string, max: number): string {\n  if (text.length <= max) return text;\n  return `${text.slice(0, max - 1)}…`;\n}\n"],"mappings":"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","names":[]}

package/dist/optimizers/index.d.ts

@@ -0,0 +1,7 @@
+export { type BootstrapFewshotInput, type BootstrapFewshotOptions, renderDemonstrations, runBootstrapFewshot, withDemonstrations, } from "./bootstrap-fewshot.js";
+export { type GepaInput, type GepaOptions, runGepa, } from "./gepa.js";
+export { type InstructionSearchInput, type InstructionSearchOptions, runInstructionSearch, } from "./instruction-search.js";
+export { type PromptEvolutionInput, type PromptEvolutionOptions, runPromptEvolution, } from "./prompt-evolution.js";
+export { createPromptScorer, createRuntimeAdapter, extractPlannerAction, extractPlannerView, LIFEOPS_SCORER_TASKS, LIFEOPS_STRUCTURED_SCORER_TASKS, scoreActionSet, scoreAgreement, scoreLifeOpsTask, scorePlannerAction, scoreStructuredFields, scoreViewSelection, subsample, type UseModelHandler, } from "./scoring.js";
+export type { LlmAdapter, OptimizationExample, OptimizedPromptArtifact, OptimizerLineageEntry, OptimizerName, OptimizerResult, PromptScorer, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/optimizers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/optimizers/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,qBAAqB,EAC1B,KAAK,uBAAuB,EAC5B,oBAAoB,EACpB,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,KAAK,SAAS,EACd,KAAK,WAAW,EAChB,OAAO,GACR,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,KAAK,sBAAsB,EAC3B,KAAK,wBAAwB,EAC7B,oBAAoB,GACrB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,KAAK,oBAAoB,EACzB,KAAK,sBAAsB,EAC3B,kBAAkB,GACnB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,kBAAkB,EAClB,oBAAoB,EACpB,oBAAoB,EACpB,kBAAkB,EAClB,oBAAoB,EACpB,+BAA+B,EAC/B,cAAc,EACd,cAAc,EACd,gBAAgB,EAChB,kBAAkB,EAClB,qBAAqB,EACrB,kBAAkB,EAClB,SAAS,EACT,KAAK,eAAe,GACrB,MAAM,cAAc,CAAC;AACtB,YAAY,EACV,UAAU,EACV,mBAAmB,EACnB,uBAAuB,EACvB,qBAAqB,EACrB,aAAa,EACb,eAAe,EACf,YAAY,GACb,MAAM,YAAY,CAAC"}

package/dist/optimizers/index.js

@@ -0,0 +1,51 @@
+import {
+  renderDemonstrations,
+  runBootstrapFewshot,
+  withDemonstrations
+} from "./bootstrap-fewshot.js";
+import {
+  runGepa
+} from "./gepa.js";
+import {
+  runInstructionSearch
+} from "./instruction-search.js";
+import {
+  runPromptEvolution
+} from "./prompt-evolution.js";
+import {
+  createPromptScorer,
+  createRuntimeAdapter,
+  extractPlannerAction,
+  extractPlannerView,
+  LIFEOPS_SCORER_TASKS,
+  LIFEOPS_STRUCTURED_SCORER_TASKS,
+  scoreActionSet,
+  scoreAgreement,
+  scoreLifeOpsTask,
+  scorePlannerAction,
+  scoreStructuredFields,
+  scoreViewSelection,
+  subsample
+} from "./scoring.js";
+export {
+  LIFEOPS_SCORER_TASKS,
+  LIFEOPS_STRUCTURED_SCORER_TASKS,
+  createPromptScorer,
+  createRuntimeAdapter,
+  extractPlannerAction,
+  extractPlannerView,
+  renderDemonstrations,
+  runBootstrapFewshot,
+  runGepa,
+  runInstructionSearch,
+  runPromptEvolution,
+  scoreActionSet,
+  scoreAgreement,
+  scoreLifeOpsTask,
+  scorePlannerAction,
+  scoreStructuredFields,
+  scoreViewSelection,
+  subsample,
+  withDemonstrations
+};
+//# sourceMappingURL=index.js.map

package/dist/optimizers/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/optimizers/index.ts"],"sourcesContent":["export {\n  type BootstrapFewshotInput,\n  type BootstrapFewshotOptions,\n  renderDemonstrations,\n  runBootstrapFewshot,\n  withDemonstrations,\n} from \"./bootstrap-fewshot.js\";\nexport {\n  type GepaInput,\n  type GepaOptions,\n  runGepa,\n} from \"./gepa.js\";\nexport {\n  type InstructionSearchInput,\n  type InstructionSearchOptions,\n  runInstructionSearch,\n} from \"./instruction-search.js\";\nexport {\n  type PromptEvolutionInput,\n  type PromptEvolutionOptions,\n  runPromptEvolution,\n} from \"./prompt-evolution.js\";\nexport {\n  createPromptScorer,\n  createRuntimeAdapter,\n  extractPlannerAction,\n  extractPlannerView,\n  LIFEOPS_SCORER_TASKS,\n  LIFEOPS_STRUCTURED_SCORER_TASKS,\n  scoreActionSet,\n  scoreAgreement,\n  scoreLifeOpsTask,\n  scorePlannerAction,\n  scoreStructuredFields,\n  scoreViewSelection,\n  subsample,\n  type UseModelHandler,\n} from \"./scoring.js\";\nexport type {\n  LlmAdapter,\n  OptimizationExample,\n  OptimizedPromptArtifact,\n  OptimizerLineageEntry,\n  OptimizerName,\n  OptimizerResult,\n  PromptScorer,\n} from \"./types.js\";\n"],"mappings":"AAAA;AAAA,EAGE;AAAA,EACA;AAAA,EACA;AAAA,OACK;AACP;AAAA,EAGE;AAAA,OACK;AACP;AAAA,EAGE;AAAA,OACK;AACP;AAAA,EAGE;AAAA,OACK;AACP;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OAEK;","names":[]}

package/dist/optimizers/instruction-search.d.ts

@@ -0,0 +1,39 @@
+/**
+ * MIPRO-style instruction search optimizer.
+ *
+ * Iterative improvement loop:
+ *   1. Ask the LLM to propose N rewrites of the current baseline prompt that
+ *      preserve the task contract but tighten language, add guardrails, or
+ *      reorder for clarity.
+ *   2. Score each candidate (plus the current baseline) on a held-out subset
+ *      of the dataset.
+ *   3. Keep the highest-scoring candidate as the next round's baseline.
+ *   4. Repeat for `rounds` iterations.
+ *
+ * Returns the best prompt observed across all rounds along with full lineage
+ * (every (round, variant) -> score), so the caller can render an audit trail.
+ */
+import type { LlmAdapter, OptimizationExample, OptimizerResult, PromptScorer } from "./types.js";
+export interface InstructionSearchOptions {
+    /** Variants to propose per round. Defaults to 8. */
+    variants?: number;
+    /** Search rounds. Defaults to 3. */
+    rounds?: number;
+    /** Held-out examples scored per candidate. Defaults to all examples. */
+    scoringSubset?: number;
+    /** Sampling temperature for variant generation. Defaults to 0.7. */
+    temperature?: number;
+    /** Max tokens for the rewrite completion. Defaults to 1024. */
+    maxTokens?: number;
+    /** Deterministic RNG override (tests). Defaults to Math.random. */
+    rng?: () => number;
+}
+export interface InstructionSearchInput {
+    baselinePrompt: string;
+    dataset: OptimizationExample[];
+    scorer: PromptScorer;
+    llm: LlmAdapter;
+    options?: InstructionSearchOptions;
+}
+export declare function runInstructionSearch(input: InstructionSearchInput): Promise<OptimizerResult>;
+//# sourceMappingURL=instruction-search.d.ts.map

package/dist/optimizers/instruction-search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instruction-search.d.ts","sourceRoot":"","sources":["../../src/optimizers/instruction-search.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,KAAK,EACV,UAAU,EACV,mBAAmB,EAEnB,eAAe,EACf,YAAY,EACb,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,wBAAwB;IACvC,oDAAoD;IACpD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oCAAoC;IACpC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wEAAwE;IACxE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,oEAAoE;IACpE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+DAA+D;IAC/D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mEAAmE;IACnE,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,sBAAsB;IACrC,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,mBAAmB,EAAE,CAAC;IAC/B,MAAM,EAAE,YAAY,CAAC;IACrB,GAAG,EAAE,UAAU,CAAC;IAChB,OAAO,CAAC,EAAE,wBAAwB,CAAC;CACpC;AAuBD,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,sBAAsB,GAC5B,OAAO,CAAC,eAAe,CAAC,CAgG1B"}