textopt 0.0.0

package/dist/reflection-mwMhrjs_.mjs

@@ -0,0 +1,214 @@
+import { t as parseProposedText } from "./text--v4Ffbus.mjs";
+//#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 = 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
+export { createDefaultProposer as a, buildSimplifyPrompt as i, buildReflectionPrompt as n, diverseReflectionStrategies as o, buildRewritePrompt as r, buildGeneralizePrompt as t };

package/dist/rng-BR5MOedA.d.cts

@@ -0,0 +1,22 @@
+//#region src/rng.d.ts
+/**
+ * Seeded pseudo-random number generator.
+ *
+ * Optimization runs are expensive and long-lived, so every stochastic decision
+ * in the engine flows through an explicit Rng instance rather than Math.random.
+ * That makes runs reproducible and checkpoints replayable.
+ */
+interface Rng {
+  next(): number;
+  nextInt(maxExclusive: number): number;
+  pick<T>(items: readonly T[]): T;
+  shuffle<T>(items: readonly T[]): T[];
+  /** `k` distinct items, or every item when `k` exceeds the input length. */
+  sample<T>(items: readonly T[], k: number): T[];
+  /** Picks proportionally to `weights`; falls back to uniform when all are 0. */
+  weighted<T>(items: readonly T[], weights: readonly number[]): T;
+  /** Position in the stream, for checkpointing. Restore via `createSeededRng`. */
+  state(): number;
+}
+//#endregion
+export { Rng as t };

package/dist/rng-BR5MOedA.d.mts

@@ -0,0 +1,22 @@
+//#region src/rng.d.ts
+/**
+ * Seeded pseudo-random number generator.
+ *
+ * Optimization runs are expensive and long-lived, so every stochastic decision
+ * in the engine flows through an explicit Rng instance rather than Math.random.
+ * That makes runs reproducible and checkpoints replayable.
+ */
+interface Rng {
+  next(): number;
+  nextInt(maxExclusive: number): number;
+  pick<T>(items: readonly T[]): T;
+  shuffle<T>(items: readonly T[]): T[];
+  /** `k` distinct items, or every item when `k` exceeds the input length. */
+  sample<T>(items: readonly T[], k: number): T[];
+  /** Picks proportionally to `weights`; falls back to uniform when all are 0. */
+  weighted<T>(items: readonly T[], weights: readonly number[]): T;
+  /** Position in the stream, for checkpointing. Restore via `createSeededRng`. */
+  state(): number;
+}
+//#endregion
+export { Rng as t };

package/dist/rng-DbA_rPIo.cjs

@@ -0,0 +1,67 @@
+//#region src/rng.ts
+const DEFAULT_SEED = 2654435769;
+function createSeededRng(seed, resumeState) {
+	let state = resumeState ?? normalizeSeed(seed);
+	function next() {
+		state = state + 1831565813 >>> 0;
+		let t = state;
+		t = Math.imul(t ^ t >>> 15, t | 1);
+		t ^= t + Math.imul(t ^ t >>> 7, t | 61);
+		return ((t ^ t >>> 14) >>> 0) / 4294967296;
+	}
+	function nextInt(maxExclusive) {
+		if (!Number.isFinite(maxExclusive) || maxExclusive <= 0) throw new Error(`nextInt requires a positive bound, received ${maxExclusive}`);
+		return Math.floor(next() * maxExclusive);
+	}
+	function pick(items) {
+		if (items.length === 0) throw new Error("Cannot pick from an empty array");
+		return items[nextInt(items.length)];
+	}
+	function shuffle(items) {
+		const copy = [...items];
+		for (let i = copy.length - 1; i > 0; i -= 1) {
+			const j = nextInt(i + 1);
+			const swap = copy[i];
+			copy[i] = copy[j];
+			copy[j] = swap;
+		}
+		return copy;
+	}
+	function sample(items, k) {
+		if (k <= 0) return [];
+		return shuffle(items).slice(0, k);
+	}
+	function weighted(items, weights) {
+		if (items.length === 0) throw new Error("Cannot pick from an empty array");
+		const positive = items.map((_, index) => Math.max(0, weights[index] ?? 0));
+		const total = positive.reduce((sum, weight) => sum + weight, 0);
+		if (total <= 0) return pick(items);
+		let threshold = next() * total;
+		for (let index = 0; index < items.length; index += 1) {
+			threshold -= positive[index];
+			if (threshold < 0) return items[index];
+		}
+		return items[items.length - 1];
+	}
+	return {
+		next,
+		nextInt,
+		pick,
+		shuffle,
+		sample,
+		weighted,
+		state: () => state
+	};
+}
+function normalizeSeed(seed) {
+	if (!Number.isFinite(seed)) return DEFAULT_SEED;
+	const normalized = Math.floor(seed) >>> 0;
+	return normalized === 0 ? DEFAULT_SEED : normalized;
+}
+//#endregion
+Object.defineProperty(exports, "createSeededRng", {
+	enumerable: true,
+	get: function() {
+		return createSeededRng;
+	}
+});

package/dist/rng-Dtc5eZ_W.mjs

@@ -0,0 +1,62 @@
+//#region src/rng.ts
+const DEFAULT_SEED = 2654435769;
+function createSeededRng(seed, resumeState) {
+	let state = resumeState ?? normalizeSeed(seed);
+	function next() {
+		state = state + 1831565813 >>> 0;
+		let t = state;
+		t = Math.imul(t ^ t >>> 15, t | 1);
+		t ^= t + Math.imul(t ^ t >>> 7, t | 61);
+		return ((t ^ t >>> 14) >>> 0) / 4294967296;
+	}
+	function nextInt(maxExclusive) {
+		if (!Number.isFinite(maxExclusive) || maxExclusive <= 0) throw new Error(`nextInt requires a positive bound, received ${maxExclusive}`);
+		return Math.floor(next() * maxExclusive);
+	}
+	function pick(items) {
+		if (items.length === 0) throw new Error("Cannot pick from an empty array");
+		return items[nextInt(items.length)];
+	}
+	function shuffle(items) {
+		const copy = [...items];
+		for (let i = copy.length - 1; i > 0; i -= 1) {
+			const j = nextInt(i + 1);
+			const swap = copy[i];
+			copy[i] = copy[j];
+			copy[j] = swap;
+		}
+		return copy;
+	}
+	function sample(items, k) {
+		if (k <= 0) return [];
+		return shuffle(items).slice(0, k);
+	}
+	function weighted(items, weights) {
+		if (items.length === 0) throw new Error("Cannot pick from an empty array");
+		const positive = items.map((_, index) => Math.max(0, weights[index] ?? 0));
+		const total = positive.reduce((sum, weight) => sum + weight, 0);
+		if (total <= 0) return pick(items);
+		let threshold = next() * total;
+		for (let index = 0; index < items.length; index += 1) {
+			threshold -= positive[index];
+			if (threshold < 0) return items[index];
+		}
+		return items[items.length - 1];
+	}
+	return {
+		next,
+		nextInt,
+		pick,
+		shuffle,
+		sample,
+		weighted,
+		state: () => state
+	};
+}
+function normalizeSeed(seed) {
+	if (!Number.isFinite(seed)) return DEFAULT_SEED;
+	const normalized = Math.floor(seed) >>> 0;
+	return normalized === 0 ? DEFAULT_SEED : normalized;
+}
+//#endregion
+export { createSeededRng as t };

package/dist/sampling-CfHt7Gue.mjs

@@ -0,0 +1,59 @@
+//#region src/sampling.ts
+/**
+* Shuffles the training set once per epoch and walks it in fixed-size chunks, so
+* every training example is seen once before any is seen twice.
+*/
+function createEpochShuffledSampler(args) {
+	const { minibatchSize } = args;
+	let shuffled = [];
+	let epoch = -1;
+	let lastTrainsetSize = -1;
+	const sampler = ({ trainingSet, iteration, rng }) => {
+		if (trainingSet.length === 0) throw new Error("Cannot sample a minibatch from an empty trainingSet");
+		const baseIndex = iteration * minibatchSize;
+		const currentEpoch = shuffled.length === 0 ? 0 : Math.floor(baseIndex / shuffled.length);
+		if (shuffled.length === 0 || trainingSet.length !== lastTrainsetSize || currentEpoch > epoch) {
+			epoch = currentEpoch;
+			lastTrainsetSize = trainingSet.length;
+			shuffled = buildPaddedShuffle({
+				size: trainingSet.length,
+				minibatchSize,
+				rng
+			});
+		}
+		const start = baseIndex % shuffled.length;
+		return shuffled.slice(start, start + minibatchSize);
+	};
+	sampler.state = () => ({
+		shuffled: [...shuffled],
+		epoch,
+		lastTrainsetSize
+	});
+	sampler.restore = (state) => {
+		if (!isSamplerState(state)) return;
+		shuffled = [...state.shuffled];
+		epoch = state.epoch;
+		lastTrainsetSize = state.lastTrainsetSize;
+	};
+	return sampler;
+}
+function isSamplerState(state) {
+	if (state === null || typeof state !== "object") return false;
+	const candidate = state;
+	return Array.isArray(candidate.shuffled) && typeof candidate.epoch === "number" && typeof candidate.lastTrainsetSize === "number";
+}
+function buildPaddedShuffle(args) {
+	const { size, minibatchSize, rng } = args;
+	const indices = rng.shuffle(Array.from({ length: size }, (_, i) => i));
+	const remainder = indices.length % minibatchSize;
+	const padding = remainder === 0 ? 0 : minibatchSize - remainder;
+	const frequencies = new Map(indices.map((index) => [index, 1]));
+	for (let i = 0; i < padding; i += 1) {
+		const leastUsed = indices.reduce((best, index) => frequencies.get(index) < frequencies.get(best) ? index : best);
+		indices.push(leastUsed);
+		frequencies.set(leastUsed, frequencies.get(leastUsed) + 1);
+	}
+	return indices;
+}
+//#endregion
+export { createEpochShuffledSampler as t };

package/dist/sampling-DFo_7RNJ.d.mts

@@ -0,0 +1,23 @@
+import { t as Rng } from "./rng-BR5MOedA.mjs";
+//#region src/sampling.d.ts
+type BatchSampler<Datum> = ((args: {
+  trainingSet: readonly Datum[];
+  /**
+   * Position in the sequence of minibatches drawn so far, not the loop
+   * iteration. Draws made concurrently within one iteration arrive as
+   * consecutive positions, so siblings diagnose different failures instead of
+   * sharing a batch.
+   */
+  iteration: number;
+  rng: Rng;
+}) => number[]) & {
+  /**
+   * Position within the sampler's own schedule, checkpointed alongside the
+   * random stream. Without it a resumed run restarts its epoch and re-walks
+   * minibatches the interrupted run had already spent.
+   */
+  state?: () => unknown;
+  restore?: (state: unknown) => void;
+};
+//#endregion
+export { BatchSampler as t };

package/dist/sampling-Dars7ctR.cjs

@@ -0,0 +1,64 @@
+//#region src/sampling.ts
+/**
+* Shuffles the training set once per epoch and walks it in fixed-size chunks, so
+* every training example is seen once before any is seen twice.
+*/
+function createEpochShuffledSampler(args) {
+	const { minibatchSize } = args;
+	let shuffled = [];
+	let epoch = -1;
+	let lastTrainsetSize = -1;
+	const sampler = ({ trainingSet, iteration, rng }) => {
+		if (trainingSet.length === 0) throw new Error("Cannot sample a minibatch from an empty trainingSet");
+		const baseIndex = iteration * minibatchSize;
+		const currentEpoch = shuffled.length === 0 ? 0 : Math.floor(baseIndex / shuffled.length);
+		if (shuffled.length === 0 || trainingSet.length !== lastTrainsetSize || currentEpoch > epoch) {
+			epoch = currentEpoch;
+			lastTrainsetSize = trainingSet.length;
+			shuffled = buildPaddedShuffle({
+				size: trainingSet.length,
+				minibatchSize,
+				rng
+			});
+		}
+		const start = baseIndex % shuffled.length;
+		return shuffled.slice(start, start + minibatchSize);
+	};
+	sampler.state = () => ({
+		shuffled: [...shuffled],
+		epoch,
+		lastTrainsetSize
+	});
+	sampler.restore = (state) => {
+		if (!isSamplerState(state)) return;
+		shuffled = [...state.shuffled];
+		epoch = state.epoch;
+		lastTrainsetSize = state.lastTrainsetSize;
+	};
+	return sampler;
+}
+function isSamplerState(state) {
+	if (state === null || typeof state !== "object") return false;
+	const candidate = state;
+	return Array.isArray(candidate.shuffled) && typeof candidate.epoch === "number" && typeof candidate.lastTrainsetSize === "number";
+}
+function buildPaddedShuffle(args) {
+	const { size, minibatchSize, rng } = args;
+	const indices = rng.shuffle(Array.from({ length: size }, (_, i) => i));
+	const remainder = indices.length % minibatchSize;
+	const padding = remainder === 0 ? 0 : minibatchSize - remainder;
+	const frequencies = new Map(indices.map((index) => [index, 1]));
+	for (let i = 0; i < padding; i += 1) {
+		const leastUsed = indices.reduce((best, index) => frequencies.get(index) < frequencies.get(best) ? index : best);
+		indices.push(leastUsed);
+		frequencies.set(leastUsed, frequencies.get(leastUsed) + 1);
+	}
+	return indices;
+}
+//#endregion
+Object.defineProperty(exports, "createEpochShuffledSampler", {
+	enumerable: true,
+	get: function() {
+		return createEpochShuffledSampler;
+	}
+});

package/dist/sampling-axOwfZf5.d.cts

@@ -0,0 +1,23 @@
+import { t as Rng } from "./rng-BR5MOedA.cjs";
+//#region src/sampling.d.ts
+type BatchSampler<Datum> = ((args: {
+  trainingSet: readonly Datum[];
+  /**
+   * Position in the sequence of minibatches drawn so far, not the loop
+   * iteration. Draws made concurrently within one iteration arrive as
+   * consecutive positions, so siblings diagnose different failures instead of
+   * sharing a batch.
+   */
+  iteration: number;
+  rng: Rng;
+}) => number[]) & {
+  /**
+   * Position within the sampler's own schedule, checkpointed alongside the
+   * random stream. Without it a resumed run restarts its epoch and re-walks
+   * minibatches the interrupted run had already spent.
+   */
+  state?: () => unknown;
+  restore?: (state: unknown) => void;
+};
+//#endregion
+export { BatchSampler as t };