textopt 0.0.0

package/dist/gepa/index.d.mts

@@ -0,0 +1,385 @@
+import { l as ScoreResult, u as TextModel } from "../types-CWv4IQFF.mjs";
+import { n as EvaluationCache } from "../cache-CuSo0NJ8.mjs";
+import { r as DemoRenderer } from "../demos-B0pVQjYC.mjs";
+import { n as OptimizerResult, r as OptimizerTask, t as Optimizer } from "../optimizer-DqCoth_w.mjs";
+import { C as RejectedProposal, S as ReflectiveRecord, T as ValEvaluationPolicy, _ as GepaStopReason, a as buildRewritePrompt, b as ProposeArgs, c as AcceptancePolicy, d as CandidateSource, f as ComponentPatch, g as GepaSnapshot, h as GepaEvent, i as buildReflectionPrompt, l as CandidateRecord, m as GepaAdapter, n as ReflectionPromptBuilder, o as buildSimplifyPrompt, p as ComponentSelector, r as buildGeneralizePrompt, s as diverseReflectionStrategies, t as ReflectionPromptArgs, u as CandidateSelector, v as MakeReflectiveDatasetArgs, w as SelectionState, x as ReflectiveDataset, y as ParetoFrontier } from "../reflection-Cr_upzU0.mjs";
+import { t as BatchSampler } from "../sampling-DFo_7RNJ.mjs";
+//#region src/gepa/demos.d.ts
+/**
+ * A proposer that fills demonstration components from rollouts the run has
+ * already paid for.
+ *
+ * The reflective dataset carries every minibatch rollout's input, output and
+ * score, so the successful ones are a few-shot block sitting in memory. Taking
+ * them costs no rollout and no reflection call — the search buys demos as a
+ * side effect of the evaluations it was making anyway.
+ *
+ * A proposal appends to the block its parent already holds rather than
+ * replacing it: a block built from one minibatch alone would hold three or
+ * four examples and forget every earlier one. Accumulation therefore follows
+ * the accepted lineage — a demo only persists if the candidate carrying it
+ * beat its parent, which is the same bar every other component is held to.
+ */
+declare function createDemoProposer<K extends string = string>(args: {
+  /** Components that hold demonstrations rather than instructions. */
+  components: readonly K[];
+  /** Score a rollout must reach to be kept as a demo. Default 1. */
+  minScore?: number;
+  /** Demos a block holds before the oldest are dropped. Default 4. */
+  maxDemos?: number;
+  render?: DemoRenderer;
+  /**
+   * Handles the components not named above. Defaults to ordinary reflection,
+   * so a candidate mixing instructions and demos needs nothing else wired up.
+   */
+  fallback?: (args: ProposeArgs<K>) => Promise<ComponentPatch<K>>;
+}): (args: ProposeArgs<K>) => Promise<ComponentPatch<K>>;
+//#endregion
+//#region src/gepa/pipeline.d.ts
+/** One module of the system: a component's text, applied to what reached it. */
+interface PipelineModule<Datum, K extends string> {
+  /** The candidate component holding this module's instruction. */
+  component: K;
+  run: (args: {
+    instruction: string;
+    /** The previous module's output, or the pipeline input for the first. */
+    input: unknown;
+    datum: Datum;
+    signal?: AbortSignal;
+  }) => Promise<unknown> | unknown;
+}
+interface PipelineStep {
+  component: string;
+  input: unknown;
+  output: unknown;
+}
+/** What each module in one rollout received and produced, in order. */
+interface PipelineTrace {
+  steps: PipelineStep[];
+}
+/**
+ * A GEPA adapter for a system built from several modules in sequence, where
+ * each module's instruction is its own candidate component.
+ *
+ * The work this saves is attribution. Reflection on a multi-module system is
+ * only as good as the evidence it sees, and the evidence a module needs is what
+ * *it* received and produced — not the pipeline's input and final answer, which
+ * is what an adapter written in a hurry ends up showing every component.
+ *
+ * The feedback is end-to-end, and every module sees the same string. That is
+ * the honest default rather than a shortcut: a metric scores the final output,
+ * so nothing in a score alone says which module lost the point. A caller who
+ * can attribute better should score the steps themselves — `score` is handed
+ * the whole trace for exactly that.
+ *
+ * Errors from a module are not caught. A helper cannot tell a rate limit from a
+ * bug in a module, and guessing wrong either buries the bug or fails the run
+ * over a blip. Classify inside `run` and return a transient `ScoreResult` from
+ * `score`, or let the optimizer's `raiseOnError` decide.
+ */
+declare function createPipelineAdapter<Datum, Output = unknown, K extends string = string>(args: {
+  modules: readonly PipelineModule<Datum, K>[];
+  /** What the first module receives. Defaults to the datum itself. */
+  input?: (datum: Datum) => unknown;
+  score: (args: {
+    datum: Datum;
+    output: Output;
+    steps: readonly PipelineStep[];
+  }) => Promise<ScoreResult> | ScoreResult;
+  /** Rollouts in flight at once. Default 1. */
+  concurrency?: number;
+}): GepaAdapter<Datum, PipelineTrace, Output, K>;
+//#endregion
+//#region src/gepa/optimize.d.ts
+/**
+ * How GEPA searches. Immutable, reusable across runs, and free of both the
+ * component names and the datum type — the honest line between this and
+ * `GepaTask` is "type-free and stateless" rather than "how it searches".
+ *
+ * Holds no run state: the candidate pool, the budget spent, the position of the
+ * random stream, rejected proposals and merge bookkeeping all live in
+ * `GepaSnapshot`.
+ */
+interface GepaConfig {
+  minibatchSize?: number;
+  maxIterations?: number;
+  seed?: number;
+  candidateSelector?: CandidateSelector;
+  acceptance?: AcceptancePolicy;
+  /**
+   * System-aware merge. Enabled by default for multi-component candidates,
+   * where two lineages can improve different components independently.
+   *
+   * The reference defaults `use_merge=False`, and the paper reports merge as
+   * the separate GEPA+Merge variant rather than as part of GEPA — a variant
+   * that helped on most models it was tried on and hurt on one. On by default
+   * here because the case it needs, several components moving along different
+   * lineages, is the case this library is usually pointed at. The cost is that
+   * a multi-component run is GEPA+Merge unless this is turned off, which
+   * spends rollouts on merge attempts and consumes the random stream
+   * differently, so trajectories will not line up with a reference run at the
+   * same seed. Set `enabled: false` for GEPA as published.
+   */
+  merge?: {
+    enabled?: boolean;
+    maxInvocations?: number;
+    /**
+     * Validation instances two lineages must share before they may be merged.
+     * Default 5, GEPA's `val_overlap_floor`. A merge is judged only on
+     * instances both parents were scored on, so below this the gate deciding
+     * whether to keep the child is reading noise. A validation set smaller than the
+     * floor can never merge.
+     */
+    valOverlapFloor?: number;
+  };
+  /**
+   * Skip reflection when the parent already scores `perfectScore` on every
+   * minibatch instance. There is no failure to diagnose, so the rollouts a
+   * proposal would cost are better spent elsewhere. Default true.
+   */
+  skipPerfectScore?: boolean;
+  /** Per-instance score treated as leaving no room to improve. Default 1. */
+  perfectScore?: number;
+  /**
+   * How many rejected proposals per component are shown back to the reflection
+   * model, most recent first. 0 disables the feedback. Default 3.
+   *
+   * Not in the paper or the reference implementation, where a rejected
+   * proposal fires a callback and is otherwise forgotten: whenever a proposal
+   * has been rejected, the prompt this builds is not the published one. Set 0
+   * for GEPA as written.
+   *
+   * It is not the only default that departs from the reference — the
+   * evaluation cache and, for multi-component seeds, merge are both on here
+   * and off there. See those options.
+   */
+  rejectedProposalMemory?: number;
+  /**
+   * How many mutations an iteration proposes, and what happens to them.
+   *
+   * One proposal per iteration is GEPA as published. Raising `perIteration`
+   * samples the reflection model more than once against the same frontier —
+   * more shots at an improvement, screened on cheap minibatches before any of
+   * them costs a validation sweep — and `concurrency` is what turns that into
+   * wall-clock savings rather than just more rollouts.
+   */
+  proposals?: {
+    /** Proposals drawn per iteration, each with its own parent and minibatch. */
+    perIteration?: number;
+    /** How many of them may be in flight at once. Default 1. */
+    concurrency?: number;
+    /**
+     * Which improving proposals are kept. "all" accepts every proposal that
+     * beat its own parent, "best" only the largest improvement, `{ keep: n }`
+     * the strongest n. Default "all".
+     */
+    selection?: "all" | "best" | {
+      keep: number;
+    };
+  };
+  /**
+   * Bounds on the reflection model, which no metric budget covers: reflection
+   * calls are often the most expensive part of a run and the prompt carries
+   * traces of unbounded size.
+   */
+  reflection?: {
+    /** Hard ceiling on reflection calls. The run stops once it is reached. */
+    maxCalls?: number;
+    /** Records shown per component. The worst scoring ones are kept. */
+    maxRecords?: number;
+    /** Rough ceiling on the characters the records serialize to. */
+    maxCharacters?: number;
+    /** Replaces the default prompt template. Ignored by custom proposers. */
+    buildPrompt?: ReflectionPromptBuilder;
+    /**
+     * Prompt templates rotated one per proposal, so raising
+     * `proposals.perIteration` samples different directions rather than the
+     * same one repeatedly. `diverseReflectionStrategies()` is a ready set.
+     * Mutually exclusive with `buildPrompt`. Ignored by custom proposers.
+     */
+    strategies?: readonly ReflectionPromptBuilder[];
+  };
+  /**
+   * Include cached instance scores in every checkpoint. Leaving them out keeps
+   * snapshots small at the cost of a resumed run re-paying for rollouts it
+   * cannot look up. Default true.
+   */
+  checkpointCache?: boolean;
+  /**
+   * Keep what each candidate produced on the validation instances it was
+   * scored on, so the winning outputs can be read back without re-running.
+   * Costs memory proportional to the outputs of every accepted candidate.
+   */
+  trackBestOutputs?: boolean;
+  /** Rethrow adapter failures instead of skipping the iteration. Default true. */
+  raiseOnError?: boolean;
+}
+/**
+ * One run: what is being optimized, over what data, with what run-scoped state
+ * and IO.
+ *
+ * `seedCandidate` and `trainingSet` are the inference sites for the component
+ * names and the datum type; every other position is `NoInfer`, so it is checked
+ * against them instead of widening them.
+ */
+interface GepaTask<Datum, Trajectory = unknown, Output = unknown, K extends string = string> extends OptimizerTask<Datum, Trajectory, Output, K> {
+  adapter: GepaAdapter<Datum, Trajectory, Output, NoInfer<K>>;
+  reflect: TextModel;
+  componentSelector?: ComponentSelector<NoInfer<K>>;
+  batchSampler?: BatchSampler<NoInfer<Datum>>;
+  /**
+   * Which validation instances each candidate is scored on. Defaults to a full
+   * sweep per accepted candidate, which is what makes the frontier exact.
+   */
+  valEvaluationPolicy?: ValEvaluationPolicy<NoInfer<Datum>, NoInfer<K>>;
+  instanceId?: (args: {
+    datum: NoInfer<Datum>;
+    index: number;
+  }) => string;
+  /**
+   * Pass `false` to disable caching entirely.
+   *
+   * On by default, where the reference defaults `cache_evaluation=False`. A
+   * cache hit is free and uncharged, so the same `maxMetricCalls` buys a
+   * longer run here than there — the budget counts fresh rollouts, which is
+   * what costs money, rather than scorings. Pass `false` to compare rollout
+   * counts against a reference run directly.
+   */
+  cache?: EvaluationCache | false;
+  onEvent?: (event: GepaEvent<NoInfer<K>>) => void;
+  /**
+   * Called with a resumable snapshot after the seed is scored and after every
+   * iteration. Persist it and a killed run costs the last iteration, not all
+   * of them.
+   */
+  onCheckpoint?: (snapshot: GepaSnapshot) => void | Promise<void>;
+  /** Snapshot to continue from, instead of starting at the seed candidate. */
+  resumeFrom?: GepaSnapshot;
+}
+interface GepaResult<K extends string = string, Output = unknown> extends OptimizerResult<K, GepaStopReason, Output> {
+  bestCandidateId: number;
+  candidates: CandidateRecord<K>[];
+  paretoFrontier: CandidateRecord<K>[];
+  /**
+   * Per objective: the best value reached and every candidate that reached it.
+   * Absent when the adapter reports no objective scores.
+   */
+  perObjectiveBest?: Record<string, {
+    score: number;
+    candidateIds: number[];
+  }>;
+  scoreMatrix: (number | undefined)[][];
+  iterations: number;
+  /** Calls made to the reflection model, which no metric budget covers. */
+  reflectionCalls: number;
+  cacheHits: number;
+  /** State as of the last iteration, ready to hand back as `resumeFrom`. */
+  snapshot: GepaSnapshot;
+}
+/**
+ * Reflective prompt evolution: propose, screen on a minibatch, promote what
+ * survives, and track the Pareto frontier of everything promoted.
+ *
+ * One instance is a configured search that can be run against any number of
+ * tasks. It holds no run state, so two runs never share a shuffle position, a
+ * budget or a candidate pool.
+ */
+declare class GepaOptimizer implements Optimizer<GepaStopReason> {
+  #private;
+  constructor(config?: GepaConfig);
+  optimize<Datum, Trajectory = unknown, Output = unknown, const K extends string = string>(task: GepaTask<Datum, Trajectory, Output, K>): Promise<GepaResult<K, Output>>;
+}
+//#endregion
+//#region src/gepa/strategies.d.ts
+/**
+ * Default parent selection: sample from the instance-wise Pareto frontier with
+ * probability proportional to how many validation instances a candidate is best
+ * on. This is what keeps GEPA from tunnelling into one lineage.
+ *
+ * `frontier` chooses what the fronts are taken over. "instance" is GEPA as
+ * published. "objective" tracks candidates leading each named objective the
+ * adapter reports, and "hybrid" pools both — a candidate then earns selection
+ * weight for every instance it wins *and* every objective it leads.
+ */
+declare function paretoSelector(args?: {
+  epsilon?: number;
+  frontier?: ParetoFrontier;
+}): CandidateSelector;
+/** Greedy hill climbing. Useful as an ablation baseline. */
+declare function currentBestSelector(): CandidateSelector;
+declare function epsilonGreedySelector(args: {
+  epsilon: number;
+}): CandidateSelector;
+/** Pareto selection restricted to the top k candidates by aggregate score. */
+declare function topKParetoSelector(args: {
+  k: number;
+  epsilon?: number;
+}): CandidateSelector;
+/**
+ * Score every accepted candidate on the whole validation set. This is GEPA as
+ * published: the frontier is exact, and the cost is one full sweep per
+ * acceptance.
+ */
+declare function fullEvaluationPolicy<Datum = unknown, K extends string = string>(): ValEvaluationPolicy<Datum, K>;
+/**
+ * A full sweep, with the winner chosen by a lower confidence bound on its mean
+ * rather than by the mean itself: `mean - z * standardError`, over the
+ * instances the candidate was scored on.
+ *
+ * The reference picks the highest mean. That is an argmax over every candidate
+ * a run produced, all measured on the same instances, so the winner is
+ * systematically the one whose instance-level noise happened to land in its
+ * favour — the gap this library reports between `bestScore` and `testScore`.
+ * Penalising spread prefers a candidate that was even across the set to one
+ * carried by a few instances, at the cost of sometimes returning a genuinely
+ * better but less consistent candidate. It changes only which candidate is
+ * reported, never which ones the search explores.
+ */
+declare function lowerBoundEvaluationPolicy<Datum = unknown, K extends string = string>(args?: {
+  z?: number;
+}): ValEvaluationPolicy<Datum, K>;
+/**
+ * Score each candidate on a random subset of the validation set. Cheaper per
+ * acceptance, at the cost of comparing candidates measured on different
+ * instances — coverage breaks ties, so a candidate cannot win by having been
+ * asked fewer questions.
+ */
+declare function subsampledEvaluationPolicy<Datum = unknown, K extends string = string>(args: {
+  size: number;
+}): ValEvaluationPolicy<Datum, K>;
+/**
+ * One component per selection, cycling in declaration order from the parent's
+ * own cursor. Updating a single component at a time is what makes the minibatch
+ * acceptance test attributable; keying off the parent's cursor rather than the
+ * global iteration is what guarantees every component of a rarely-selected
+ * lineage eventually gets a turn.
+ */
+declare function roundRobinComponentSelector<K extends string = string>(): ComponentSelector<K>;
+/** Update every component in a single reflection call. */
+declare function allComponentsSelector<K extends string = string>(): ComponentSelector<K>;
+/**
+ * Accept a mutation only when it beats its parent on the same minibatch. Cheap
+ * gate that keeps full validation sweeps for candidates that showed a signal.
+ */
+declare function improvementAcceptance(args?: {
+  minImprovement?: number;
+}): AcceptancePolicy;
+/**
+ * Accepts a child only when a paired permutation test over the minibatch says
+ * its gain is unlikely to be noise. Pairs are the same instances run by both
+ * candidates, so the test is over the per-instance differences.
+ *
+ * The reference accepts on any sum improvement. On a minibatch of three that
+ * promotes a candidate one lucky rollout ahead, which is what fills a pool
+ * with children the validation sweep then discards. The cost is that small
+ * batches cannot produce small p-values at all — with three instances the
+ * smallest attainable is 0.125 — so this accepts only a clean sweep there.
+ * That is the honest reading of three rollouts, not a limitation to tune
+ * around: raise `minibatchSize` to buy the power to detect smaller gains.
+ */
+declare function pairedPermutationAcceptance(args?: {
+  alpha?: number;
+  maxExact?: number;
+}): AcceptancePolicy;
+//#endregion
+export { type AcceptancePolicy, type CandidateRecord, type CandidateSelector, type CandidateSource, type ComponentPatch, type ComponentSelector, type GepaAdapter, type GepaConfig, type GepaEvent, GepaOptimizer, type GepaResult, type GepaSnapshot, type GepaStopReason, type GepaTask, type MakeReflectiveDatasetArgs, type PipelineModule, type PipelineStep, type PipelineTrace, type ProposeArgs, type ReflectionPromptArgs, type ReflectionPromptBuilder, type ReflectiveDataset, type ReflectiveRecord, type RejectedProposal, type SelectionState, type ValEvaluationPolicy, allComponentsSelector, buildGeneralizePrompt, buildReflectionPrompt, buildRewritePrompt, buildSimplifyPrompt, createDemoProposer, createPipelineAdapter, currentBestSelector, diverseReflectionStrategies, epsilonGreedySelector, fullEvaluationPolicy, improvementAcceptance, lowerBoundEvaluationPolicy, pairedPermutationAcceptance, paretoSelector, roundRobinComponentSelector, subsampledEvaluationPolicy, topKParetoSelector };