textopt 0.0.0

package/dist/reflection-Cr_upzU0.d.mts

@@ -0,0 +1,283 @@
+import { i as EvaluationBatch, n as Candidate, o as EvaluationPhase, s as EvaluationSplit, t as Adapter, u as TextModel } from "./types-CWv4IQFF.mjs";
+import { t as CachedScore } from "./cache-CuSo0NJ8.mjs";
+import { t as Rng } from "./rng-BR5MOedA.mjs";
+//#region src/gepa/types.d.ts
+/**
+ * One piece of evidence reflection reads: what went in, what came out, and how
+ * it scored. `Evidence` is the adapter's own slot — trace steps, retrieved
+ * documents, errors — typed rather than smuggled in through an index signature.
+ */
+interface ReflectiveRecord<Evidence = unknown> {
+  inputs: unknown;
+  generatedOutputs: unknown;
+  feedback: string;
+  score?: number;
+  evidence?: Evidence;
+}
+/**
+ * Component name -> records shown to the reflection model for that component.
+ *
+ * Partial, not total: an adapter only fills the components it was asked to
+ * update, so a component with nothing to diagnose is simply absent.
+ */
+type ReflectiveDataset<K extends string = string> = Partial<Record<K, ReflectiveRecord[]>>;
+interface MakeReflectiveDatasetArgs<Datum, Trajectory, Output, K extends string = string> {
+  candidate: Candidate<K>;
+  batch: readonly Datum[];
+  evaluation: EvaluationBatch<Trajectory, Output>;
+  componentsToUpdate: readonly K[];
+}
+/** New text for the subset of components a proposal actually changed. */
+type ComponentPatch<K extends string = string> = Partial<Record<K, string>>;
+/**
+ * A component text that was proposed and lost on the minibatch. Showing these
+ * back to the reflection model is what stops a run from re-deriving the same
+ * dead end: only exact duplicates are filtered structurally, so without this
+ * the model can spend the whole budget circling one bad idea.
+ */
+interface RejectedProposal {
+  text: string;
+  parentScore: number;
+  childScore: number;
+}
+interface ProposeArgs<K extends string = string> {
+  candidate: Candidate<K>;
+  reflectiveDataset: ReflectiveDataset<K>;
+  componentsToUpdate: readonly K[];
+  /** Component name -> texts already tried and rejected for it. */
+  rejectedProposals?: Partial<Record<K, RejectedProposal[]>>;
+  /**
+   * Which proposal this is in the run, counting from 0. Assigned when the
+   * iteration is planned rather than when it executes, so concurrent
+   * proposals get stable, distinct values instead of racing for a counter.
+   * The default proposer rotates its strategies on it.
+   */
+  attempt?: number;
+  reflect: TextModel;
+  signal?: AbortSignal;
+}
+/**
+ * An adapter GEPA can reflect against: evaluation, plus the traces reflection
+ * reads. `makeReflectiveDataset` is what turns a scored batch into the
+ * per-component evidence a reflection call is written from.
+ */
+interface GepaAdapter<Datum, Trajectory = unknown, Output = unknown, K extends string = string> extends Adapter<Datum, Trajectory, Output, K> {
+  makeReflectiveDataset(args: MakeReflectiveDatasetArgs<Datum, Trajectory, Output, K>): Promise<ReflectiveDataset<K>> | ReflectiveDataset<K>;
+  proposeNewTexts?(args: ProposeArgs<K>): Promise<ComponentPatch<K>> | ComponentPatch<K>;
+}
+type CandidateSource = "seed" | "mutation" | "merge";
+interface CandidateRecord<K extends string = string> {
+  id: number;
+  candidate: Candidate<K>;
+  parentIds: number[];
+  /**
+   * One entry per validation instance. `undefined` marks an instance the
+   * evaluation policy did not select for this candidate — unknown, not zero.
+   */
+  instanceScores: (number | undefined)[];
+  /** Mean over the instances that were scored. */
+  aggregateScore: number;
+  /** Mean of each objective over the evaluated validation instances. */
+  objectiveScores?: Record<string, number>;
+  source: CandidateSource;
+  updatedComponents: K[];
+  iteration: number;
+  /**
+   * Round-robin position this candidate resumes from the next time it is
+   * chosen as a parent. Per-candidate rather than global: a lineage that is
+   * only reselected every fifth iteration must still walk its own components
+   * one at a time instead of being pinned to whichever one the global counter
+   * happens to land on.
+   */
+  componentCursor: number;
+}
+/** What a Pareto frontier is taken over. */
+type ParetoFrontier = "instance" | "objective" | "hybrid";
+/** Read-only view handed to candidate selectors. */
+interface SelectionState {
+  scoreMatrix: readonly (readonly (number | undefined)[])[];
+  aggregateScores: readonly number[];
+  /** Per-candidate objective means, absent when the adapter reports none. */
+  objectiveScores?: readonly (Readonly<Record<string, number>> | undefined)[];
+}
+type CandidateSelector = (args: {
+  state: SelectionState;
+  rng: Rng;
+}) => number;
+type ComponentSelector<K extends string = string> = (args: {
+  candidate: Candidate<K>;
+  /** This candidate's own round-robin position, advanced after each selection. */
+  cursor: number;
+  iteration: number;
+  rng: Rng;
+}) => K[];
+type AcceptancePolicy = (args: {
+  parentScores: readonly number[];
+  childScores: readonly number[];
+}) => boolean;
+/**
+ * Which validation instances a candidate is scored on, and how the best
+ * candidate is read back out of possibly partial coverage.
+ *
+ * A full sweep per accepted candidate is the published behaviour and the
+ * default. Swapping in a partial policy trades frontier fidelity for rollouts:
+ * candidates scored on different instances are no longer strictly comparable,
+ * which is why picking the best is the policy's job too.
+ */
+interface ValEvaluationPolicy<Datum = unknown, K extends string = string> {
+  selectInstances(args: {
+    validationSet: readonly Datum[];
+    candidate: Candidate<K>;
+    records: readonly CandidateRecord<K>[];
+    iteration: number;
+    rng: Rng;
+  }): number[];
+  bestCandidate(records: readonly CandidateRecord<K>[]): number;
+}
+type GepaStopReason = "budgetExhausted" | "costExhausted" | "deadlineReached" | "reflectionBudgetExhausted" | "aborted" | "maxIterations";
+type GepaEvent<K extends string = string> = {
+  type: "start";
+  components: K[];
+  validationSetSize: number;
+} | {
+  type: "iterationStart";
+  iteration: number;
+  parentIds: number[];
+} | {
+  type: "evaluation";
+  iteration: number;
+  phase: EvaluationPhase;
+  split: EvaluationSplit;
+  candidateId: number | null;
+  metricCalls: number;
+  cacheHits: number;
+  meanScore: number;
+} | {
+  type: "proposal";
+  iteration: number;
+  parentId: number;
+  componentsToUpdate: K[];
+  changed: boolean;
+} | {
+  type: "candidateAccepted";
+  iteration: number;
+  candidateId: number;
+  parentIds: number[];
+  aggregateScore: number;
+  source: CandidateSource;
+} | {
+  type: "candidateRejected";
+  iteration: number;
+  parentId: number;
+  parentScore: number;
+  childScore: number;
+  source: CandidateSource;
+  /**
+   * "worse" lost to its parent on the minibatch. "notSelected" beat its
+   * parent but lost to a stronger proposal from the same iteration — it is
+   * not a dead end, and is never fed back to reflection as one.
+   */
+  reason: "worse" | "notSelected";
+} | {
+  type: "error";
+  iteration: number;
+  err: unknown;
+} | {
+  type: "finish";
+  reason: GepaStopReason;
+  bestCandidateId: number;
+  metricCalls: number;
+  /** The winner's held-out score, when a testSet was given. */
+  testScore?: number;
+};
+/**
+ * Everything needed to continue a run: the candidate pool with its scores, the
+ * budget already spent, the position of the random stream, and the bookkeeping
+ * that stops merges and proposals from being relitigated. Plain JSON — write it
+ * wherever you like and hand it back as `resumeFrom`.
+ *
+ * Deliberately not generic over component names. It leaves the process and
+ * comes back through `JSON.parse` with plain string keys, so the narrowing back
+ * to a run's own components happens once inside the engine, guarded by the
+ * fingerprint, rather than being a type the caller has to reconstruct.
+ *
+ * A resumed run follows the same trajectory an uninterrupted one would, as long
+ * as the batch sampler reports its state and the evaluation cache is either
+ * checkpointed or disabled — a cache that is neither leaves the resumed run
+ * paying again for rollouts the first one had already bought.
+ */
+interface GepaSnapshot {
+  version: 1;
+  /**
+   * Identifies the run this checkpoint came from — seed candidate, instance
+   * ids and seed. Resuming against a different setup is refused rather than
+   * silently scoring old candidates against new data.
+   */
+  fingerprint: string;
+  records: CandidateRecord[];
+  iteration: number;
+  metricCalls: number;
+  reflectionCalls: number;
+  cacheHits: number;
+  rngState: number;
+  /** Whatever the batch sampler reports from `state()`, when it has one. */
+  sampler?: unknown;
+  rejectedProposals: Record<string, RejectedProposal[]>;
+  merge: {
+    attempts: string[];
+    descriptions: string[];
+    due: number;
+    tested: number;
+    lastIterationAccepted: boolean;
+  };
+  /** Cached instance scores, when the cache can enumerate them. */
+  cache?: [string, CachedScore][];
+}
+//#endregion
+//#region src/gepa/reflection.d.ts
+interface ReflectionPromptArgs {
+  componentName: string;
+  currentText: string;
+  records: readonly ReflectiveRecord[];
+  /** Texts already tried for this component that lost to their parent. */
+  rejected?: readonly RejectedProposal[];
+}
+type ReflectionPromptBuilder = (args: ReflectionPromptArgs) => string;
+/**
+ * Adapted from the reflection prompt in the GEPA paper (Agrawal et al., 2025).
+ * The instruction to mine domain facts out of the traces matters as much as the
+ * instruction to fix failures — most of the lift comes from the model writing
+ * down knowledge the traces revealed.
+ */
+declare function buildReflectionPrompt(args: ReflectionPromptArgs): string;
+/**
+ * Cut rather than add. Reflective evolution only ever appends — every
+ * iteration diagnoses a failure and writes a rule preventing it — so an
+ * instruction grows monotonically until it is mostly edge cases that no longer
+ * fire. Nothing else in the loop ever removes one.
+ */
+declare function buildSimplifyPrompt(args: ReflectionPromptArgs): string;
+/**
+ * Replace a rule that fits the instances it was written from with the
+ * principle behind it. Feedback is drawn from minibatches, so a rule written
+ * to fix three examples routinely encodes those three examples.
+ */
+declare function buildGeneralizePrompt(args: ReflectionPromptArgs): string;
+/**
+ * Start from the evidence rather than from the incumbent. Every other strategy
+ * edits the current text, which anchors each proposal to whatever the search
+ * happened to reach first; this one is the only escape from a bad opening.
+ */
+declare function buildRewritePrompt(args: ReflectionPromptArgs): string;
+/**
+ * A rotation covering the four directions a proposal can move in: fix what is
+ * broken, cut what is dead, widen what is too narrow, and start over.
+ *
+ * Drawing a proposal k times from one template samples one direction k times.
+ * Rotating costs nothing extra — same call count, same rollouts — and is the
+ * cheapest diversity available. Opt in via `reflection.strategies`; the
+ * default stays the published single prompt.
+ */
+declare function diverseReflectionStrategies(): ReflectionPromptBuilder[];
+//#endregion
+export { RejectedProposal as C, ReflectiveRecord as S, ValEvaluationPolicy as T, GepaStopReason as _, buildRewritePrompt as a, ProposeArgs as b, AcceptancePolicy as c, CandidateSource as d, ComponentPatch as f, GepaSnapshot as g, GepaEvent as h, buildReflectionPrompt as i, CandidateRecord as l, GepaAdapter as m, ReflectionPromptBuilder as n, buildSimplifyPrompt as o, ComponentSelector as p, buildGeneralizePrompt as r, diverseReflectionStrategies as s, ReflectionPromptArgs as t, CandidateSelector as u, MakeReflectiveDatasetArgs as v, SelectionState as w, ReflectiveDataset as x, ParetoFrontier as y };

package/dist/reflection-DRfbk6hu.cjs

@@ -0,0 +1,249 @@
+const require_text = require("./text-CK_HB3su.cjs");
+//#region src/gepa/reflection.ts
+const TRUNCATION_MARKER = "… [truncated]";
+const MIN_STRING_BUDGET = 40;
+/**
+* Adapted from the reflection prompt in the GEPA paper (Agrawal et al., 2025).
+* The instruction to mine domain facts out of the traces matters as much as the
+* instruction to fix failures — most of the lift comes from the model writing
+* down knowledge the traces revealed.
+*/
+function buildReflectionPrompt(args) {
+	const { componentName, currentText, records, rejected = [] } = args;
+	return [
+		`I gave an assistant the following instruction for the "${componentName}" component of a larger system:`,
+		"",
+		"<current_instruction>",
+		currentText,
+		"</current_instruction>",
+		"",
+		"Below are task inputs the assistant received, the outputs it produced, and feedback on how each output could be better:",
+		"",
+		"<examples>",
+		serializeRecords(records),
+		"</examples>",
+		...rejected.length === 0 ? [] : [
+			"",
+			"These instructions have already been tried for this component and scored worse than the one they replaced. Do not propose them again, and do not propose a variation that repeats the idea that made them fail:",
+			"",
+			"<rejected_instructions>",
+			JSON.stringify(rejected, jsonSafeReplacer, 2),
+			"</rejected_instructions>"
+		],
+		"",
+		"Write a new instruction for this component.",
+		"Read the inputs carefully and infer a detailed description of the task the component is solving, including its input format.",
+		"Read every output and its feedback. Identify all niche or domain-specific factual information the task depends on and state it explicitly in the instruction — the assistant will not have access to these examples in future.",
+		"If the assistant used a generalizable strategy that worked, describe that strategy.",
+		"If the feedback shows a recurring failure, add a precise rule that prevents it.",
+		"",
+		"Return only the new instruction, inside a ``` block."
+	].join("\n");
+}
+/**
+* Cut rather than add. Reflective evolution only ever appends — every
+* iteration diagnoses a failure and writes a rule preventing it — so an
+* instruction grows monotonically until it is mostly edge cases that no longer
+* fire. Nothing else in the loop ever removes one.
+*/
+function buildSimplifyPrompt(args) {
+	const { componentName, currentText, records } = args;
+	return [
+		`The instruction below drives the "${componentName}" component of a larger system. It has been edited many times and has accumulated rules.`,
+		"",
+		"<current_instruction>",
+		currentText,
+		"</current_instruction>",
+		"",
+		"Here is how it behaved on recent inputs, with feedback on each output:",
+		"",
+		"<examples>",
+		serializeRecords(records),
+		"</examples>",
+		"",
+		"Write a shorter instruction.",
+		"Remove any rule that is redundant, that restates something already said, that contradicts another rule, or that no longer earns the space it takes.",
+		"Keep every rule the examples show is load-bearing. The component must still behave the same way on the inputs above.",
+		"Do not add new rules. If nothing can be removed, say the same thing in fewer words.",
+		"",
+		"Return only the new instruction, inside a ``` block."
+	].join("\n");
+}
+/**
+* Replace a rule that fits the instances it was written from with the
+* principle behind it. Feedback is drawn from minibatches, so a rule written
+* to fix three examples routinely encodes those three examples.
+*/
+function buildGeneralizePrompt(args) {
+	const { componentName, currentText, records } = args;
+	return [
+		`The instruction below drives the "${componentName}" component of a larger system.`,
+		"",
+		"<current_instruction>",
+		currentText,
+		"</current_instruction>",
+		"",
+		"It was written from a small sample of inputs, so parts of it may describe those specific inputs rather than the task. Here is how it behaved on recent inputs, with feedback on each output:",
+		"",
+		"<examples>",
+		serializeRecords(records),
+		"</examples>",
+		"",
+		"Write a new instruction that states the underlying principle instead of the special cases.",
+		"Where a rule names a specific input, value or phrasing, ask what general property that case is an instance of, and write that property.",
+		"Keep concrete domain facts that are genuinely fixed — names, thresholds, formats. Those are knowledge, not overfitting.",
+		"",
+		"Return only the new instruction, inside a ``` block."
+	].join("\n");
+}
+/**
+* Start from the evidence rather than from the incumbent. Every other strategy
+* edits the current text, which anchors each proposal to whatever the search
+* happened to reach first; this one is the only escape from a bad opening.
+*/
+function buildRewritePrompt(args) {
+	const { componentName, records } = args;
+	return [
+		`Write the instruction for the "${componentName}" component of a larger system, from scratch.`,
+		"",
+		"Below are task inputs the component received, the outputs it produced, and feedback on how each output could be better:",
+		"",
+		"<examples>",
+		serializeRecords(records),
+		"</examples>",
+		"",
+		"You are deliberately not being shown the instruction currently in use. Work out what the component is for from the inputs and outputs alone.",
+		"Infer the task, its input format, and what a correct output looks like.",
+		"State explicitly any domain-specific facts the task depends on — the component will not have access to these examples in future.",
+		"",
+		"Return only the new instruction, inside a ``` block."
+	].join("\n");
+}
+/**
+* A rotation covering the four directions a proposal can move in: fix what is
+* broken, cut what is dead, widen what is too narrow, and start over.
+*
+* Drawing a proposal k times from one template samples one direction k times.
+* Rotating costs nothing extra — same call count, same rollouts — and is the
+* cheapest diversity available. Opt in via `reflection.strategies`; the
+* default stays the published single prompt.
+*/
+function diverseReflectionStrategies() {
+	return [
+		buildReflectionPrompt,
+		buildSimplifyPrompt,
+		buildGeneralizePrompt,
+		buildRewritePrompt
+	];
+}
+/**
+* Trims a reflective dataset down to what one prompt should carry: the worst
+* scoring records first, since reflection is about diagnosing failures, and
+* long strings cut to a share of the character budget.
+*/
+function limitReflectiveRecords(args) {
+	const { records, maxRecords, maxCharacters } = args;
+	let kept = [...records];
+	if (maxRecords !== void 0 && kept.length > maxRecords) kept = kept.map((record, position) => ({
+		record,
+		position
+	})).sort((a, b) => (a.record.score ?? Number.POSITIVE_INFINITY) - (b.record.score ?? Number.POSITIVE_INFINITY)).slice(0, maxRecords).sort((a, b) => a.position - b.position).map((entry) => entry.record);
+	if (maxCharacters === void 0 || kept.length === 0) return kept;
+	const perRecord = Math.max(MIN_STRING_BUDGET, Math.floor(maxCharacters / kept.length));
+	kept = kept.map((record) => truncateStrings(record, perRecord));
+	while (kept.length > 1 && serializeRecords(kept).length > maxCharacters) kept.pop();
+	return kept;
+}
+/**
+* Default instruction proposer: one reflection call per component being
+* updated. Adapters override this via `proposeNewTexts` when components need
+* coupled updates or a structured proposal format; `buildPrompt` is the
+* lighter seam for changing only the wording.
+*/
+function createDefaultProposer(options = {}) {
+	const { buildPrompt, strategies, limits = {} } = options;
+	if (buildPrompt !== void 0 && strategies !== void 0) throw new Error("createDefaultProposer takes buildPrompt or strategies, not both");
+	if (strategies !== void 0 && strategies.length === 0) throw new Error("createDefaultProposer requires a non-empty strategies list");
+	const rotation = strategies ?? [buildPrompt ?? buildReflectionPrompt];
+	return async (args) => {
+		const { candidate, reflectiveDataset, componentsToUpdate, rejectedProposals, attempt = 0, reflect, signal } = args;
+		const proposed = {};
+		const strategy = rotation[attempt % rotation.length];
+		for (const componentName of componentsToUpdate) {
+			const records = reflectiveDataset[componentName];
+			if (records === void 0 || records.length === 0) continue;
+			const currentText = candidate[componentName] ?? "";
+			const response = await reflect({
+				prompt: strategy({
+					componentName,
+					currentText,
+					records: limitReflectiveRecords({
+						records,
+						...limits
+					}),
+					rejected: rejectedProposals?.[componentName]
+				}),
+				signal
+			});
+			const newText = require_text.parseProposedText(response);
+			if (newText.length > 0 && newText !== currentText) proposed[componentName] = newText;
+		}
+		return proposed;
+	};
+}
+function serializeRecords(records) {
+	return JSON.stringify(records, jsonSafeReplacer, 2);
+}
+/** Recursive so a long trace buried in a nested output is cut too. */
+function truncateStrings(value, budget) {
+	if (typeof value === "string") return value.length <= budget ? value : `${value.slice(0, budget)}${TRUNCATION_MARKER}`;
+	if (Array.isArray(value)) return value.map((item) => truncateStrings(item, budget));
+	if (value !== null && typeof value === "object") return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, truncateStrings(item, budget)]));
+	return value;
+}
+function jsonSafeReplacer(_key, value) {
+	if (value instanceof Error) return {
+		name: value.name,
+		message: value.message
+	};
+	if (value instanceof Map) return Object.fromEntries(value);
+	if (value instanceof Set) return [...value];
+	return value;
+}
+//#endregion
+Object.defineProperty(exports, "buildGeneralizePrompt", {
+	enumerable: true,
+	get: function() {
+		return buildGeneralizePrompt;
+	}
+});
+Object.defineProperty(exports, "buildReflectionPrompt", {
+	enumerable: true,
+	get: function() {
+		return buildReflectionPrompt;
+	}
+});
+Object.defineProperty(exports, "buildRewritePrompt", {
+	enumerable: true,
+	get: function() {
+		return buildRewritePrompt;
+	}
+});
+Object.defineProperty(exports, "buildSimplifyPrompt", {
+	enumerable: true,
+	get: function() {
+		return buildSimplifyPrompt;
+	}
+});
+Object.defineProperty(exports, "createDefaultProposer", {
+	enumerable: true,
+	get: function() {
+		return createDefaultProposer;
+	}
+});
+Object.defineProperty(exports, "diverseReflectionStrategies", {
+	enumerable: true,
+	get: function() {
+		return diverseReflectionStrategies;
+	}
+});