textopt 0.0.0

package/dist/simba/index.mjs

@@ -0,0 +1,700 @@
+import { d as createMemoryCache, i as measuredMean, l as runFingerprint, n as costExhausted, o as createDeadline, p as createBudget, r as createEvaluator, s as assertResumable, t as BudgetExhausted, u as componentNames } from "../evaluation-BV0nSZVx.mjs";
+import { n as formatDemos, r as parseDemos } from "../demos-Degx6UmP.mjs";
+import { t as createSeededRng } from "../rng-Dtc5eZ_W.mjs";
+import { t as createEpochShuffledSampler } from "../sampling-CfHt7Gue.mjs";
+//#region src/simba/advice.ts
+const ADVICE_BLOCK = /<advice\s+component="([^"]+)"\s*>([\s\S]*?)<\/advice>/g;
+/**
+* Adapted from SIMBA's `OfferFeedback` signature (Opsahl-Ong et al.'s DSPy).
+*
+* The framing that matters is "build up experience": the component will not
+* see this instance again, so advice that only fixes this one input is wasted.
+* Contrasting two runs of the *same* input is what makes that possible — the
+* inputs are held constant, so the difference in reward is attributable to the
+* behaviour rather than to the instance being easier.
+*/
+function buildAdvicePrompt(args) {
+	const { components, input, better, worse } = args;
+	return [
+		"Two runs of the same system on the same input are shown below, with the reward each earned.",
+		"Your job is to write advice that would make the system behave like the higher scoring run the next time it sees a similar input.",
+		"",
+		"<input>",
+		serialize(input),
+		"</input>",
+		...worse === void 0 ? [] : trajectoryBlock("worse", worse),
+		...better === void 0 ? [] : trajectoryBlock("better", better),
+		"",
+		"Write advice for each of these components:",
+		"",
+		"<components>",
+		components.join("\n"),
+		"</components>",
+		"",
+		"The component will not have access to this example, so advice that only covers this input is wasted. State the general behaviour it should adopt, and be concrete about when it applies.",
+		"Address each component's own sub-task rather than the system as a whole.",
+		"Base the advice on what actually differed between the two runs. If nothing useful can be said for a component, leave it out.",
+		"",
+		"Return one block per component, in the form <advice component=\"name\">…</advice>, and nothing else."
+	].join("\n");
+}
+/**
+* Read the per-component advice out of the model's response, ignoring anything
+* written around it. A component the model had nothing to say about is absent
+* rather than empty, so the caller appends nothing instead of appending noise.
+*/
+function parseAdvice(response) {
+	const advice = {};
+	for (const match of response.matchAll(ADVICE_BLOCK)) {
+		const component = match[1];
+		const text = (match[2] ?? "").trim();
+		if (text.length > 0) advice[component] = text;
+	}
+	return advice;
+}
+function trajectoryBlock(label, trajectory) {
+	return [
+		"",
+		`<${label}_trajectory>`,
+		`reward: ${trajectory.score}`,
+		"<output>",
+		serialize(trajectory.output),
+		"</output>",
+		...trajectory.feedback === void 0 ? [] : [
+			"<feedback>",
+			trajectory.feedback,
+			"</feedback>"
+		],
+		`</${label}_trajectory>`
+	];
+}
+function serialize(value) {
+	if (typeof value === "string") return value;
+	try {
+		return JSON.stringify(value, null, 2) ?? String(value);
+	} catch {
+		return String(value);
+	}
+}
+//#endregion
+//#region src/simba/strategies.ts
+/**
+* Group the step's samples by instance and rank the instances by how much the
+* programs disagreed about them.
+*
+* Disagreement is the signal SIMBA runs on. An instance every program gets
+* right teaches nothing, and one every program gets wrong is usually beyond
+* the reach of a prompt edit; the instructive ones are where one program
+* succeeded and another failed, because the pair is a controlled experiment
+* the reflection model can read directly.
+*
+* Ranked on the max-to-min gap first, then the best score, then the max-to-avg
+* gap: widest disagreement first, ties broken toward instances where something
+* actually worked, since a bucket whose best rollout is bad has no success to
+* generalize from.
+*/
+function buildBuckets(args) {
+	const { batch, samples } = args;
+	return batch.map((datum, index) => {
+		const rollouts = samples.map((sample) => ({
+			programIndex: sample.programIndex,
+			score: sample.scores[index] ?? 0,
+			...sample.outputs === void 0 ? {} : { output: sample.outputs[index] },
+			...sample.feedback === void 0 ? {} : { feedback: sample.feedback[index] }
+		})).sort((a, b) => b.score - a.score);
+		const scores = rollouts.map((rollout) => rollout.score);
+		const maxScore = Math.max(...scores);
+		const minScore = Math.min(...scores);
+		const average = scores.reduce((total, score) => total + score, 0) / scores.length;
+		return {
+			index,
+			datum,
+			rollouts,
+			maxToMinGap: maxScore - minScore,
+			maxScore,
+			maxToAvgGap: maxScore - average
+		};
+	}).sort((a, b) => b.maxToMinGap - a.maxToMinGap || b.maxScore - a.maxScore || b.maxToAvgGap - a.maxToAvgGap);
+}
+/**
+* Linear-interpolated percentile, matching numpy's default so the thresholds
+* behave the way the reference implementation's do.
+*/
+function percentile(values, p) {
+	if (values.length === 0) return 0;
+	const sorted = [...values].sort((a, b) => a - b);
+	const position = p / 100 * (sorted.length - 1);
+	const lower = Math.floor(position);
+	const upper = Math.ceil(position);
+	if (lower === upper) return sorted[lower];
+	return sorted[lower] + (position - lower) * (sorted[upper] - sorted[lower]);
+}
+/**
+* Softmax weights over program scores, for picking which program to mutate
+* next. Shifted by the maximum before exponentiating — the same distribution,
+* but a score scale the caller chose freely cannot overflow it.
+*/
+function softmaxWeights(scores, temperature) {
+	if (scores.length === 0) return [];
+	const highest = Math.max(...scores);
+	return scores.map((score) => Math.exp((score - highest) / temperature));
+}
+/**
+* The `k` highest scoring programs, with the baseline forced into the pool.
+*
+* Keeping the baseline is what makes the search recoverable: every candidate
+* descends from a program already in the pool, so a pool that has drifted into
+* a bad region has nothing left to climb back from.
+*/
+function topKPlusBaseline(args) {
+	const { scores, k } = args;
+	const ranked = scores.map((score, index) => ({
+		score,
+		index
+	})).sort((a, b) => b.score - a.score).slice(0, k).map((entry) => entry.index);
+	if (ranked.length > 0 && !ranked.includes(0)) ranked[ranked.length - 1] = 0;
+	return [...new Set(ranked)];
+}
+/**
+* A Poisson draw by Knuth's method, used to decide how many demonstrations to
+* drop before a mutation. Random rather than fixed so a candidate can shed a
+* demo that is no longer earning its place — nothing else in the loop ever
+* removes one, and a block that only grows eventually crowds out the
+* instruction it was meant to support.
+*/
+function samplePoisson(rng, lambda) {
+	if (lambda <= 0) return 0;
+	const limit = Math.exp(-lambda);
+	let draws = 0;
+	let product = 1;
+	do {
+		draws += 1;
+		product *= rng.next();
+	} while (product > limit);
+	return draws - 1;
+}
+/**
+* Positions spread evenly across a sequence, first and last included.
+*
+* The step winners are held back and only a sample of them is scored on the
+* full validation set at the end, because scoring every one of them costs more
+* than the search did. Sampling evenly rather than taking the last few keeps
+* early winners in the running: minibatch scores are noisy, and the run's
+* genuine best is often not its most recent.
+*/
+function evenlySpacedIndices(args) {
+	const { length, count } = args;
+	if (length <= 1 || count <= 1) return [0];
+	const last = length - 1;
+	const indices = Array.from({ length: count }, (_, position) => Math.round(position * last / (count - 1)));
+	return [...new Set(indices)];
+}
+//#endregion
+//#region src/simba/optimize.ts
+const DEFAULT_MINIBATCH_SIZE = 32;
+const DEFAULT_CANDIDATES = 6;
+const DEFAULT_MAX_STEPS = 8;
+const DEFAULT_MAX_DEMOS = 4;
+const DEFAULT_TEMPERATURE = .2;
+/** What `maxDemos: 0` stands in as, so the drop rate stays defined. */
+const DEMO_DROP_SCALE = 3;
+/**
+* SIMBA — stochastic introspective mini-batch ascent.
+*
+* Run several programs over the same minibatch, find the instances they
+* disagree about most, and mutate toward whatever the winning run did. The
+* disagreement is the point: an instance one program solved and another failed
+* is a controlled experiment with the input held fixed, so the difference in
+* reward is attributable to behaviour rather than to difficulty. GEPA reflects
+* on failures; SIMBA reflects on the *contrast* between a success and a failure
+* of the same input, which is a strictly stronger signal when it exists — and
+* costs a pool of programs to produce.
+*
+* Two mutations, drawn at random per instance: append a demonstration the
+* metric already rewarded, or ask a model what the better run did differently
+* and append that as a rule. Neither replaces text, so a candidate accumulates;
+* demos are dropped at a Poisson rate to keep the block from crowding out
+* everything else.
+*
+* Ported from DSPy's SIMBA, with two deliberate changes. First, a trajectory
+* sample runs one program across the whole minibatch rather than resampling a
+* program per instance: the adapter here owns decoding, so there is no
+* temperature knob to vary, and the variability comes from the program pool
+* instead. Second, the percentile guards are strict rather than inclusive — on
+* a step where every rollout ties, an inclusive guard blocks every mutation and
+* the run does nothing at all, which is the one case where the guard's own
+* premise does not hold.
+*/
+var SimbaOptimizer = class {
+	#config;
+	constructor(config = {}) {
+		this.#config = config;
+	}
+	optimize(task) {
+		return run({
+			config: this.#config,
+			task
+		});
+	}
+};
+async function run(args) {
+	const { config, task } = args;
+	const { minibatchSize = DEFAULT_MINIBATCH_SIZE, candidates: candidateCount = DEFAULT_CANDIDATES, maxSteps = DEFAULT_MAX_STEPS, maxDemos = DEFAULT_MAX_DEMOS, samplingTemperature = DEFAULT_TEMPERATURE, candidateTemperature = DEFAULT_TEMPERATURE, strategies, maxReflectionCalls, seed = 0, trackBestOutputs = false, checkpointCache = true } = config;
+	const { seedCandidate, trainingSet, validationSet = trainingSet, testSet, adapter, reflect, demoComponents = [], instructionComponents, renderDemo, buildAdvicePrompt: buildPrompt = buildAdvicePrompt, sampler = createEpochShuffledSampler({ minibatchSize }), maxMetricCalls, cache, cacheNamespace, retry, maxCostUsd, maxWallClockMs, instanceId = defaultInstanceId, onEvent, onCheckpoint, resumeFrom, signal } = task;
+	const components = componentNames(seedCandidate);
+	const ruleComponents = instructionComponents ?? components.filter((name) => !demoComponents.includes(name));
+	const enabled = strategies ?? (demoComponents.length > 0 ? ["appendDemo", "appendRule"] : ["appendRule"]);
+	if (trainingSet.length === 0) throw new Error("optimize requires a non-empty trainingSet");
+	if (validationSet.length === 0) throw new Error("optimize requires a non-empty validationSet");
+	if (minibatchSize > trainingSet.length) throw new Error(`optimize requires a minibatchSize no larger than the trainingSet: ${minibatchSize} > ${trainingSet.length}`);
+	if (enabled.length === 0) throw new Error("optimize requires at least one strategy");
+	if (enabled.includes("appendDemo") && demoComponents.length === 0) throw new Error("the appendDemo strategy requires at least one entry in demoComponents");
+	if (enabled.includes("appendRule") && ruleComponents.length === 0) throw new Error("the appendRule strategy requires at least one instruction component to write into");
+	if (testSet !== void 0 && testSet.length === 0) throw new Error("optimize requires a non-empty testSet when one is given; omit it to skip held-out evaluation");
+	const validationIds = validationSet.map((datum, index) => instanceId({
+		datum,
+		index
+	}));
+	const testIds = testSet?.map((datum, index) => instanceId({
+		datum,
+		index
+	})) ?? [];
+	const fingerprint = runFingerprint({
+		seedCandidate,
+		trainingIds: trainingSet.map((datum, index) => instanceId({
+			datum,
+			index
+		})),
+		validationIds,
+		seed,
+		...cacheNamespace === void 0 ? {} : { cacheNamespace }
+	});
+	assertResumable({
+		fingerprint,
+		...resumeFrom === void 0 ? {} : { snapshot: resumeFrom }
+	});
+	const deadline = createDeadline({ maxWallClockMs });
+	const rng = createSeededRng(seed, resumeFrom?.rngState);
+	const budget = createBudget({
+		maxMetricCalls,
+		spent: resumeFrom?.metricCalls ?? 0
+	});
+	const evaluationCache = cache === false ? void 0 : cache ?? createMemoryCache();
+	const evaluator = createEvaluator({
+		adapter,
+		budget,
+		...retry === void 0 ? {} : { retry },
+		...cacheNamespace === void 0 ? {} : { cacheNamespace },
+		...evaluationCache === void 0 ? {} : { cache: evaluationCache },
+		trackOutputs: true,
+		cacheHits: resumeFrom?.cacheHits ?? 0,
+		...signal === void 0 ? {} : { signal },
+		onEvaluation: (event) => onEvent?.({
+			type: "evaluation",
+			...event
+		})
+	});
+	evaluator.restore(resumeFrom?.cache ?? []);
+	if (resumeFrom?.sampler !== void 0) sampler.restore?.(resumeFrom.sampler);
+	const programs = [...resumeFrom?.programs ?? [seedCandidate]];
+	const programScores = (resumeFrom?.programScores ?? [[]]).map((scores) => [...scores]);
+	const winners = [...resumeFrom?.winners ?? [{
+		candidate: seedCandidate,
+		step: 0
+	}]];
+	let step = resumeFrom?.step ?? 0;
+	let reflectionCalls = resumeFrom?.reflectionCalls ?? 0;
+	let stopReason = "maxSteps";
+	onEvent?.({
+		type: "start",
+		components,
+		validationSetSize: validationSet.length
+	});
+	const finalistReserve = Math.min(candidateCount + 1, maxSteps + 1) * validationSet.length;
+	const stepCost = candidateCount * minibatchSize + minibatchSize;
+	for (; step < maxSteps; step += 1) {
+		if (signal?.aborted) {
+			stopReason = "aborted";
+			break;
+		}
+		if (costExhausted({
+			usage: evaluator.usage(),
+			maxCostUsd
+		})) {
+			stopReason = "costExhausted";
+			break;
+		}
+		if (deadline.exceeded()) {
+			stopReason = "deadlineReached";
+			break;
+		}
+		if (budget.remaining() - finalistReserve < stepCost) {
+			stopReason = "budgetExhausted";
+			break;
+		}
+		if (available().length === 0) {
+			stopReason = "reflectionBudgetExhausted";
+			break;
+		}
+		const pool = topKPlusBaseline({
+			scores: programs.map((_, index) => averageScore(index)),
+			k: candidateCount
+		});
+		onEvent?.({
+			type: "stepStart",
+			step,
+			poolSize: pool.length
+		});
+		const batch = sampler({
+			trainingSet,
+			iteration: step,
+			rng
+		}).map((index) => trainingSet[index]);
+		const samples = [];
+		for (let slot = 0; slot < candidateCount; slot += 1) {
+			const programIndex = softmaxSample({
+				pool,
+				temperature: samplingTemperature
+			});
+			const evaluation = await evaluator.evaluateTraced({
+				candidate: programs[programIndex],
+				batch,
+				split: "train",
+				phase: "minibatch",
+				candidateId: programIndex,
+				iteration: step
+			});
+			if (evaluation === null) break;
+			samples.push({
+				programIndex,
+				scores: evaluation.scores,
+				outputs: evaluation.outputs,
+				...evaluation.feedback === void 0 ? {} : { feedback: evaluation.feedback }
+			});
+			programScores[programIndex].push(measuredMean(evaluation) ?? 0);
+		}
+		if (samples.length === 0) {
+			stopReason = "budgetExhausted";
+			break;
+		}
+		const buckets = buildBuckets({
+			batch,
+			samples
+		});
+		const allScores = samples.flatMap((sample) => [...sample.scores]);
+		const low = percentile(allScores, 10);
+		const high = percentile(allScores, 90);
+		const built = [];
+		for (const bucket of buckets) {
+			if (built.length >= candidateCount + 1) break;
+			const drawable = available();
+			if (drawable.length === 0) break;
+			const source = softmaxSample({
+				pool: topKPlusBaseline({
+					scores: programs.map((_, index) => averageScore(index)),
+					k: candidateCount
+				}),
+				temperature: candidateTemperature
+			});
+			const strategy = rng.pick(drawable);
+			const dropped = dropDemos(programs[source]);
+			let mutated;
+			try {
+				mutated = strategy === "appendDemo" ? appendDemo({
+					candidate: dropped,
+					bucket,
+					low
+				}) : await appendRule({
+					candidate: dropped,
+					bucket,
+					low,
+					high
+				});
+			} catch (err) {
+				onEvent?.({
+					type: "error",
+					step,
+					err
+				});
+				continue;
+			}
+			if (mutated === null || sameText(mutated, programs[source])) continue;
+			built.push({
+				candidate: mutated,
+				strategy,
+				source
+			});
+		}
+		let stepBest;
+		for (const entry of built) {
+			if (!budget.canAfford(batch.length)) {
+				stopReason = "budgetExhausted";
+				break;
+			}
+			let score;
+			try {
+				score = measuredMean(await evaluator.evaluate({
+					candidate: entry.candidate,
+					batch,
+					ids: batch.map((datum, index) => instanceId({
+						datum,
+						index
+					})),
+					split: "train",
+					phase: "minibatch",
+					candidateId: programs.length,
+					iteration: step
+				}));
+			} catch (err) {
+				if (err instanceof BudgetExhausted) {
+					stopReason = "budgetExhausted";
+					break;
+				}
+				throw err;
+			}
+			if (score === void 0) continue;
+			programs.push(entry.candidate);
+			programScores.push([score]);
+			onEvent?.({
+				type: "candidate",
+				step,
+				strategy: entry.strategy,
+				sourceProgram: entry.source,
+				minibatchScore: score
+			});
+			if (stepBest === void 0 || score > stepBest.score) stepBest = {
+				candidate: entry.candidate,
+				score
+			};
+		}
+		if (stepBest !== void 0) winners.push({
+			candidate: stepBest.candidate,
+			step: step + 1
+		});
+		await checkpoint(step + 1);
+		if (stopReason === "budgetExhausted") {
+			step += 1;
+			break;
+		}
+	}
+	if (signal?.aborted) stopReason = "aborted";
+	const finalists = [];
+	for (const index of evenlySpacedIndices({
+		length: winners.length,
+		count: candidateCount + 1
+	})) {
+		const winner = winners[index];
+		if (!budget.canAfford(evaluator.countUncached({
+			candidate: winner.candidate,
+			ids: validationIds,
+			split: "val"
+		}))) break;
+		let score;
+		try {
+			score = measuredMean(await evaluator.evaluate({
+				candidate: winner.candidate,
+				batch: validationSet,
+				ids: validationIds,
+				split: "val",
+				phase: index === 0 ? "seed" : "validation",
+				candidateId: index,
+				iteration: step
+			}));
+		} catch (err) {
+			if (err instanceof BudgetExhausted || signal?.aborted) break;
+			throw err;
+		}
+		if (score !== void 0) finalists.push({
+			candidate: winner.candidate,
+			score,
+			step: winner.step
+		});
+	}
+	const seedScore = finalists[0]?.score ?? 0;
+	finalists.sort((a, b) => b.score - a.score);
+	const best = finalists[0] ?? {
+		candidate: seedCandidate,
+		score: seedScore
+	};
+	let bestOutputs;
+	if (trackBestOutputs) bestOutputs = (await evaluator.evaluateTraced({
+		candidate: best.candidate,
+		batch: validationSet,
+		split: "val",
+		phase: "validation",
+		candidateId: null,
+		iteration: step
+	}))?.outputs;
+	const testScore = testSet === void 0 ? void 0 : measuredMean(await evaluator.evaluate({
+		candidate: best.candidate,
+		batch: testSet,
+		ids: testIds,
+		split: "test",
+		phase: "test",
+		candidateId: null,
+		iteration: step,
+		charge: false
+	}));
+	onEvent?.({
+		type: "finish",
+		reason: stopReason,
+		bestScore: best.score,
+		metricCalls: budget.spent(),
+		...testScore === void 0 ? {} : { testScore }
+	});
+	return {
+		bestCandidate: best.candidate,
+		bestScore: best.score,
+		usage: evaluator.usage(),
+		seedScore,
+		steps: step,
+		finalists,
+		reflectionCalls,
+		cacheHits: evaluator.cacheHits(),
+		metricCalls: budget.spent(),
+		snapshot: takeSnapshot(step),
+		...bestOutputs === void 0 ? {} : { bestOutputs },
+		...testScore === void 0 ? {} : {
+			testScore,
+			testMetricCalls: testSet?.length ?? 0
+		},
+		stopReason
+	};
+	/**
+	* The mutations still open. `appendRule` closes once the advice budget is
+	* spent; `appendDemo` never closes, because harvesting costs no model call.
+	*/
+	function available() {
+		if (maxReflectionCalls === void 0 || reflectionCalls < maxReflectionCalls) return enabled;
+		return enabled.filter((strategy) => strategy !== "appendRule");
+	}
+	function averageScore(index) {
+		const observed = programScores[index] ?? [];
+		if (observed.length === 0) return 0;
+		return observed.reduce((total, score) => total + score, 0) / observed.length;
+	}
+	function softmaxSample(args) {
+		const { pool, temperature } = args;
+		return rng.weighted(pool, softmaxWeights(pool.map((index) => averageScore(index)), temperature));
+	}
+	/**
+	* Drops a Poisson-distributed number of demos, always at least one once the
+	* block is at its ceiling. Sampled with replacement, matching the reference:
+	* a repeated draw drops fewer than the count suggests, which biases the loop
+	* toward keeping demos rather than shedding them.
+	*/
+	function dropDemos(candidate) {
+		if (demoComponents.length === 0) return { ...candidate };
+		const blocks = new Map(demoComponents.map((name) => [name, parseDemos(candidate[name] ?? "")]));
+		const held = Math.max(...[...blocks.values()].map((demos) => demos.length));
+		if (held === 0) return { ...candidate };
+		const scale = maxDemos > 0 ? maxDemos : DEMO_DROP_SCALE;
+		const wanted = Math.max(samplePoisson(rng, held / scale), held >= scale ? 1 : 0);
+		const drops = /* @__PURE__ */ new Set();
+		for (let draw = 0; draw < Math.min(wanted, held); draw += 1) drops.add(rng.nextInt(held));
+		const next = { ...candidate };
+		for (const [name, demos] of blocks) next[name] = formatDemos(demos.filter((_, index) => !drops.has(index)), renderDemo === void 0 ? {} : { render: renderDemo });
+		return next;
+	}
+	/**
+	* Keep the winning rollout of this instance as a demonstration.
+	*
+	* Declines when the winner is below the batch's tenth percentile: a demo is
+	* an assertion that this is what good looks like, and the worst rollouts of a
+	* bad step are not that.
+	*/
+	function appendDemo(args) {
+		const { candidate, bucket, low } = args;
+		const winner = bucket.rollouts[0];
+		if (winner === void 0 || winner.score < low || winner.output === void 0) return null;
+		const demo = {
+			input: bucket.datum,
+			output: winner.output,
+			score: winner.score
+		};
+		const next = { ...candidate };
+		for (const name of demoComponents) {
+			const kept = parseDemos(next[name] ?? "");
+			next[name] = formatDemos([...kept, demo], renderDemo === void 0 ? {} : { render: renderDemo });
+		}
+		return next;
+	}
+	/**
+	* Ask the reflection model what the better run did differently, and append
+	* its answer to each instruction component.
+	*
+	* Declines when the contrast is not informative: a winner below the tenth
+	* percentile is not a success to imitate, and a loser above the ninetieth is
+	* not a failure to avoid. When the two runs tied, the uninformative side is
+	* withheld and the model advises from one trajectory — a tie at a low score
+	* is shown as a failure, a tie at a high score as a success.
+	*/
+	async function appendRule(args) {
+		const { candidate, bucket, low, high } = args;
+		if (reflect === void 0) throw new Error("the appendRule strategy requires a reflect model");
+		const good = bucket.rollouts[0];
+		const bad = bucket.rollouts[bucket.rollouts.length - 1];
+		if (good === void 0 || bad === void 0) return null;
+		if (good.score < low || bad.score > high) return null;
+		const tied = good.score <= bad.score;
+		const better = tied && good.score <= high ? void 0 : trajectory(good);
+		const worse = tied && good.score > high ? void 0 : trajectory(bad);
+		if (better === void 0 && worse === void 0) return null;
+		const response = await reflect({
+			prompt: buildPrompt({
+				components: ruleComponents,
+				input: bucket.datum,
+				...better === void 0 ? {} : { better },
+				...worse === void 0 ? {} : { worse }
+			}),
+			...signal === void 0 ? {} : { signal }
+		});
+		reflectionCalls += 1;
+		const advice = parseAdvice(response);
+		const next = { ...candidate };
+		let changed = false;
+		for (const name of ruleComponents) {
+			const rule = advice[name];
+			if (rule === void 0) continue;
+			next[name] = [next[name] ?? "", rule].filter(Boolean).join("\n\n");
+			changed = true;
+		}
+		return changed ? next : null;
+	}
+	function trajectory(rollout) {
+		return {
+			output: rollout.output,
+			score: rollout.score,
+			...rollout.feedback === void 0 ? {} : { feedback: rollout.feedback }
+		};
+	}
+	function sameText(a, b) {
+		return components.every((name) => a[name] === b[name]);
+	}
+	function takeSnapshot(completed) {
+		const cached = checkpointCache ? evaluationCache?.entries?.() : void 0;
+		return {
+			version: 1,
+			fingerprint,
+			programs: [...programs],
+			programScores: programScores.map((scores) => [...scores]),
+			winners: [...winners],
+			step: completed,
+			metricCalls: budget.spent(),
+			reflectionCalls,
+			cacheHits: evaluator.cacheHits(),
+			rngState: rng.state(),
+			...sampler.state === void 0 ? {} : { sampler: sampler.state() },
+			...cached === void 0 ? {} : { cache: cached }
+		};
+	}
+	async function checkpoint(completed) {
+		if (onCheckpoint === void 0) return;
+		await onCheckpoint(takeSnapshot(completed));
+	}
+}
+function defaultInstanceId(args) {
+	return String(args.index);
+}
+//#endregion
+export { SimbaOptimizer, buildAdvicePrompt, buildBuckets, evenlySpacedIndices, parseAdvice, percentile, samplePoisson, softmaxWeights, topKPlusBaseline };