textopt 0.0.0

package/dist/mipro/index.cjs

@@ -0,0 +1,739 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_evaluation = require("../evaluation-OZOp6TB7.cjs");
+const require_concurrency = require("../concurrency-C-cFzWW2.cjs");
+const require_math = require("../math-COOofUyv.cjs");
+const require_demos = require("../demos-B9BJiNKz.cjs");
+const require_text = require("../text-CK_HB3su.cjs");
+const require_rng = require("../rng-DbA_rPIo.cjs");
+const require_sampling = require("../sampling-Dars7ctR.cjs");
+//#region src/mipro/tpe.ts
+const DEFAULT_SAMPLES = 24;
+const GOOD_FRACTION = .1;
+const MAX_GOOD = 25;
+const DEFAULT_STARTUP = 10;
+const DEFAULT_PRIOR_WEIGHT = 1;
+/**
+* Tree-structured Parzen Estimator over a categorical space.
+*
+* The search space here is a menu index per component. A TPE splits the
+* observations into the good ones and the rest, models the density of each,
+* and proposes the configuration that maximizes their ratio: sample where
+* good configurations live, prefer where bad ones do not.
+*
+* The densities are mixtures with one kernel centred on each observation,
+* rather than one histogram per component. That distinction is the whole
+* reason this optimizer exists. Per-component histograms only record how often
+* an option appears among good trials, so a space where every option is
+* equally common and only the *pairing* matters looks completely flat to them.
+* A kernel centred on an observed configuration keeps its components together,
+* so "B works, but only alongside A" survives into the proposal. It is what
+* Optuna calls a multivariate sampler, and what MIPROv2 turns on.
+*
+* What this buys over sampling every combination: a candidate with five
+* components and four options each has 1024 configurations and a budget for
+* perhaps thirty evaluations. Per-component hill climbing cannot see
+* interactions at all; enumerating cannot afford to. This can do both, at the
+* cost of being an estimate.
+*/
+function proposeConfiguration(args) {
+	const { observations, menuSizes, gamma, samples = DEFAULT_SAMPLES, startupTrials = DEFAULT_STARTUP, priorWeight = DEFAULT_PRIOR_WEIGHT, multivariate = true, rng } = args;
+	for (const size of menuSizes) if (!Number.isInteger(size) || size < 1) throw new Error(`every component needs a menu of at least one option, received ${size}`);
+	if (observations.length < startupTrials) return menuSizes.map((size) => rng.nextInt(size));
+	const scores = observations.map((observation) => observation.score);
+	if (Math.max(...scores) === Math.min(...scores)) return menuSizes.map((size) => rng.nextInt(size));
+	const ranked = [...observations].sort((a, b) => b.score - a.score);
+	const requested = gamma === void 0 ? Math.min(Math.ceil(GOOD_FRACTION * ranked.length), MAX_GOOD) : Math.floor(gamma * ranked.length);
+	const goodCount = Math.min(ranked.length - 1, Math.max(1, requested));
+	const good = ranked.slice(0, goodCount);
+	const bad = ranked.slice(goodCount);
+	let best;
+	let bestScore = Number.NEGATIVE_INFINITY;
+	const goodModel = fit({
+		observations: good,
+		menuSizes,
+		priorWeight,
+		multivariate
+	});
+	const badModel = fit({
+		observations: bad,
+		menuSizes,
+		priorWeight,
+		multivariate
+	});
+	for (let sample = 0; sample < samples; sample += 1) {
+		const choices = goodModel.sample(rng);
+		const score = Math.log(goodModel.density(choices)) - Math.log(badModel.density(choices));
+		if (score > bestScore) {
+			bestScore = score;
+			best = choices;
+		}
+	}
+	return best;
+}
+/**
+* Builds the density over a set of observations.
+*
+* Joint: a mixture with one kernel centred on each observation, plus a uniform
+* kernel. Because a kernel keeps an observation's components together, the
+* mixture assigns high density to combinations that were seen together — which
+* is what carries a dependency between components.
+*
+* Independent: one smoothed histogram per component, multiplied. Evidence
+* about a component generalizes across every combination it appears in, which
+* converges far faster when the components really are independent, and cannot
+* express a dependency at all.
+*
+* Both keep a uniform component — Optuna's `consider_prior` — so an option
+* nobody has drawn never falls to zero probability and stays reachable.
+*/
+function fit(args) {
+	const { observations, menuSizes, priorWeight, multivariate } = args;
+	const kernelCount = observations.length + 1;
+	if (multivariate) return {
+		density: (choices) => {
+			let total = uniformKernel(menuSizes);
+			for (const observation of observations) total += kernel({
+				choices,
+				center: observation.choices,
+				menuSizes,
+				priorWeight,
+				kernelCount
+			});
+			return total / kernelCount;
+		},
+		sample: (rng) => {
+			const picked = rng.nextInt(kernelCount);
+			if (picked === observations.length) return menuSizes.map((size) => rng.nextInt(size));
+			const center = observations[picked].choices;
+			const share = priorWeight / kernelCount;
+			return menuSizes.map((size, component) => drawWeighted(Array.from({ length: size }, (_, option) => option === center[component] ? share + 1 : share), rng));
+		}
+	};
+	const histograms = menuSizes.map((size, component) => {
+		const counts = new Array(size).fill(priorWeight);
+		for (const observation of observations) {
+			const choice = observation.choices[component];
+			if (choice !== void 0 && choice < size) counts[choice] = counts[choice] + 1;
+		}
+		const total = observations.length + priorWeight * size;
+		return counts.map((count) => count / total);
+	});
+	return {
+		density: (choices) => {
+			let product = 1;
+			for (let component = 0; component < histograms.length; component += 1) {
+				const histogram = histograms[component];
+				product *= histogram[choices[component]];
+			}
+			return product;
+		},
+		sample: (rng) => histograms.map((histogram) => drawWeighted(histogram, rng))
+	};
+}
+/**
+* One kernel of the mixture, centred on a single observation.
+*
+* The prior is spread across the kernels rather than added whole to each, so
+* `share` shrinks as the mixture grows and a kernel sits more sharply on what
+* it observed: matched and unmatched options stand at `1 + kernelCount /
+* priorWeight`, which is 2:1 for a lone kernel and 13:1 once twelve
+* observations back it. Optuna spells the same thing as a weight matrix filled
+* with `prior_weight / n_kernels` and incremented at each observed choice
+* (`_calculate_categorical_distributions`); dividing the prior by the count is
+* what makes accumulated evidence narrow the density instead of leaving it as
+* flat as it was on the first trial.
+*/
+function kernel(args) {
+	const { choices, center, menuSizes, priorWeight, kernelCount } = args;
+	const share = priorWeight / kernelCount;
+	let product = 1;
+	for (let component = 0; component < menuSizes.length; component += 1) {
+		const size = menuSizes[component];
+		const matched = choices[component] === center[component];
+		product *= (share + (matched ? 1 : 0)) / (share * size + 1);
+	}
+	return product;
+}
+function uniformKernel(menuSizes) {
+	let product = 1;
+	for (const size of menuSizes) product /= size;
+	return product;
+}
+function drawWeighted(weights, rng) {
+	return rng.weighted(weights.map((_, option) => option), weights);
+}
+//#endregion
+//#region src/mipro/optimize.ts
+const DEFAULT_INSTRUCTIONS = 3;
+const DEFAULT_MINIBATCH_SIZE = 35;
+const DEFAULT_MAX_TRIALS = 30;
+const DEFAULT_FULL_EVAL_INTERVAL = 5;
+const DEFAULT_DEMO_SETS = 3;
+const DEFAULT_MAX_DEMOS = 4;
+const DEFAULT_EXEMPLARS = 3;
+const DEFAULT_SUMMARY_EXAMPLES = 10;
+/**
+* Style hints, one per generated instruction. Drawing four instructions from
+* one prompt yields four rewordings of one idea; varying the hint is what
+* makes the menu a spread of approaches instead.
+*/
+const DEFAULT_TIPS = [
+	"Be concise. Say only what changes the output.",
+	"Be specific and detailed. Spell out the edge cases and the output format.",
+	"Describe the reasoning the component should do before it answers.",
+	"State the constraints as hard rules the component must never break.",
+	"Write it as a role description: who the component is and what it cares about."
+];
+/**
+* Joint search over a fixed menu, guided by a surrogate.
+*
+* The gap this fills is interaction between components. Reflective search
+* updates one component per iteration and screens it in isolation, so a pair
+* of components that only pay off together is invisible to it — a routing rule
+* and the prompt it routes to, an output format and the instruction that
+* assumes it. Merge recombines lineages after the fact but never proposes a
+* joint move.
+*
+* This search proposes a menu of options per component up front, then treats
+* the choice of one option per component as a single categorical
+* configuration and lets a TPE decide which to spend a trial on. Trials run on
+* minibatches; a configuration that beats the best minibatch reading earns a
+* full sweep before it can become the incumbent, so the number reported is
+* never a lucky minibatch.
+*
+* What it gives up is the ability to write text it did not think of at the
+* start. The menu is fixed at trial one — reflective search keeps writing new
+* text for the whole run. Neither dominates; they fail differently.
+*/
+var MiproOptimizer = class {
+	#config;
+	constructor(config = {}) {
+		assertConfig(config);
+		this.#config = config;
+	}
+	async optimize(task) {
+		return runMipro({
+			config: this.#config,
+			task
+		});
+	}
+};
+function buildMiproPrompt(args) {
+	const { componentName, seedText, exemplars, tip, siblings = {}, datasetSummary } = args;
+	const others = Object.entries(siblings).filter(([, text]) => text.length > 0);
+	return [
+		`I am writing the "${componentName}" component of a larger system. Here is the instruction it currently uses:`,
+		"",
+		"<current_instruction>",
+		seedText,
+		"</current_instruction>",
+		...others.length === 0 ? [] : [
+			"",
+			"The rest of the system reads as follows. Write something that fits alongside it rather than repeating or contradicting it:",
+			"",
+			"<system>",
+			others.map(([name, text]) => `<${name}>\n${text}\n</${name}>`).join("\n"),
+			"</system>"
+		],
+		...datasetSummary === void 0 ? [] : [
+			"",
+			"Here is what the data it runs on looks like:",
+			"",
+			"<dataset_summary>",
+			datasetSummary,
+			"</dataset_summary>"
+		],
+		...exemplars.length === 0 ? [] : [
+			"",
+			"Here are examples of the inputs this component receives:",
+			"",
+			"<inputs>",
+			exemplars.join("\n\n"),
+			"</inputs>"
+		],
+		"",
+		"Write an alternative instruction for this component — a different approach to the same job, not an edit of the one above.",
+		`Follow this style: ${tip}`,
+		"",
+		"Return only the new instruction, inside a ``` block."
+	].join("\n");
+}
+function buildDatasetSummaryPrompt(examples) {
+	return [
+		"Below are entries from a dataset a system is being tuned against.",
+		"",
+		"<examples>",
+		examples.join("\n\n"),
+		"</examples>",
+		"",
+		"Describe what this dataset is: what the inputs are, what varies between them, and what answering one well requires. Two or three sentences, concrete rather than generic.",
+		"",
+		"Return only the description, inside a ``` block."
+	].join("\n");
+}
+async function runMipro(args) {
+	const { config, task } = args;
+	const { instructionsPerComponent = DEFAULT_INSTRUCTIONS, minibatchSize = DEFAULT_MINIBATCH_SIZE, maxTrials = DEFAULT_MAX_TRIALS, startupTrials, gamma, surrogateSamples, multivariate, fullEvalInterval = DEFAULT_FULL_EVAL_INTERVAL, demoSets = DEFAULT_DEMO_SETS, maxDemos = DEFAULT_MAX_DEMOS, demoMinScore, exemplars = DEFAULT_EXEMPLARS, datasetSummary = true, summaryExamples = DEFAULT_SUMMARY_EXAMPLES, concurrency = 1, seed = 0, buildPrompt = buildMiproPrompt, tips = DEFAULT_TIPS, trackBestOutputs = false, checkpointCache = true } = config;
+	const { seedCandidate, trainingSet, validationSet = trainingSet, testSet, adapter, reflect, componentOptions, demoComponents, renderDemo, goldOutput, maxMetricCalls, renderDatum = renderDefault, batchSampler = require_sampling.createEpochShuffledSampler({ minibatchSize }), cache, cacheNamespace, retry, maxCostUsd, maxWallClockMs, instanceId = defaultInstanceId, onEvent, onCheckpoint, resumeFrom, signal } = task;
+	const deadline = require_evaluation.createDeadline({ maxWallClockMs });
+	const components = require_evaluation.componentNames(seedCandidate);
+	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 (components.length === 0) throw new Error("optimize requires a seed candidate with at least one component");
+	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");
+	for (const name of demoComponents ?? []) if (componentOptions?.[name] !== void 0) throw new Error(`component "${name}" is listed in both demoComponents and componentOptions; pick one source for its menu`);
+	const trainingIds = trainingSet.map((datum, index) => instanceId({
+		datum,
+		index
+	}));
+	const validationIds = validationSet.map((datum, index) => instanceId({
+		datum,
+		index
+	}));
+	const testIds = testSet?.map((datum, index) => instanceId({
+		datum,
+		index
+	})) ?? [];
+	const fingerprint = require_evaluation.runFingerprint({
+		seedCandidate,
+		trainingIds,
+		validationIds,
+		seed,
+		...cacheNamespace === void 0 ? {} : { cacheNamespace }
+	});
+	require_evaluation.assertResumable({
+		fingerprint,
+		...resumeFrom === void 0 ? {} : { snapshot: resumeFrom }
+	});
+	const rng = require_rng.createSeededRng(seed, resumeFrom?.rngState);
+	const budget = require_evaluation.createBudget({
+		maxMetricCalls,
+		spent: resumeFrom?.metricCalls ?? 0
+	});
+	const evaluationCache = cache === false ? void 0 : cache ?? require_evaluation.createMemoryCache();
+	const evaluator = require_evaluation.createEvaluator({
+		adapter,
+		budget,
+		...retry === void 0 ? {} : { retry },
+		...cacheNamespace === void 0 ? {} : { cacheNamespace },
+		...evaluationCache === void 0 ? {} : { cache: evaluationCache },
+		trackOutputs: trackBestOutputs,
+		cacheHits: resumeFrom?.cacheHits ?? 0,
+		...signal === void 0 ? {} : { signal },
+		onEvaluation: (event) => onEvent?.({
+			type: "evaluation",
+			...event
+		})
+	});
+	evaluator.restore(resumeFrom?.cache ?? []);
+	if (resumeFrom?.sampler !== void 0) batchSampler.restore?.(resumeFrom.sampler);
+	onEvent?.({
+		type: "start",
+		components,
+		validationSetSize: validationSet.length
+	});
+	const shown = rng.sample(trainingSet, Math.min(exemplars, trainingSet.length)).map(renderDatum);
+	let reflectionCalls = resumeFrom?.reflectionCalls ?? 0;
+	const menu = {};
+	const demoNames = new Set(demoComponents ?? []);
+	const proposing = components.some((name) => !demoNames.has(name) && componentOptions?.[name] === void 0);
+	let summary;
+	if (resumeFrom === void 0 && datasetSummary && proposing && trainingSet.length > 0) {
+		reflectionCalls += 1;
+		summary = require_text.parseProposedText(await reflect({
+			prompt: buildDatasetSummaryPrompt(rng.sample(trainingSet, Math.min(summaryExamples, trainingSet.length)).map(renderDatum)),
+			...signal === void 0 ? {} : { signal }
+		}));
+	}
+	let bootstrapMetricCalls = resumeFrom?.bootstrapMetricCalls ?? 0;
+	/**
+	* Builds a demo component's menu from rollouts the metric rewarded.
+	*
+	* Each set gets its own harvesting pass over a freshly shuffled training set, as
+	* MIPROv2 does. Drawing every set from a single pool would be cheaper and
+	* identical under deterministic scoring, but a system that answers at
+	* temperature does not give the same verdict twice: a second pass can turn a
+	* previously failing example into a demo, and one pass can never show it.
+	* Sizes vary across the sets because more demos is not monotonically better
+	* — a long block crowds out the instruction, and which length wins is
+	* exactly what the search settles.
+	*
+	* Not covered here: MIPROv2 also builds label-only sets from gold outputs,
+	* and pads bootstrapped sets with them. A gold output is something only the
+	* adapter knows, so there is nothing generic for this to read.
+	*/
+	async function bootstrapMenu(name) {
+		const blocks = [];
+		if (goldOutput !== void 0) {
+			const labelled = rng.shuffle(trainingSet).map((datum) => ({
+				input: datum,
+				output: goldOutput(datum)
+			})).filter((demo) => demo.output !== void 0).slice(0, maxDemos);
+			if (labelled.length > 0) blocks.push(require_demos.formatDemos(labelled, renderDemo === void 0 ? {} : { render: renderDemo }));
+		}
+		for (let index = 0; index < demoSets; index += 1) {
+			const affordable = Math.min(trainingSet.length, budget.remaining() - validationSet.length);
+			if (affordable < 1) break;
+			const requested = demoSets === 1 ? maxDemos : Math.round(1 + index * (maxDemos - 1) / (demoSets - 1));
+			const harvest = await require_demos.bootstrapDemos({
+				adapter,
+				candidate: seedCandidate,
+				trainingSet,
+				...demoMinScore === void 0 ? {} : { minScore: demoMinScore },
+				maxDemos: requested,
+				maxMetricCalls: affordable,
+				rng,
+				...renderDemo === void 0 ? {} : { renderDemo },
+				...signal === void 0 ? {} : { signal }
+			});
+			bootstrapMetricCalls += harvest.metricCalls;
+			budget.reserve(harvest.metricCalls);
+			if (harvest.demos.length > 0) blocks.push(require_demos.formatDemos(harvest.demos, renderDemo === void 0 ? {} : { render: renderDemo }));
+		}
+		return [.../* @__PURE__ */ new Set([
+			seedCandidate[name],
+			"",
+			...blocks
+		])].filter((text, index) => index === 0 || text.length === 0 || text.includes("<demo>"));
+	}
+	for (const name of components) {
+		const supplied = componentOptions?.[name];
+		const restored = resumeFrom?.menu[name];
+		if (restored !== void 0) {
+			menu[name] = [...restored];
+			continue;
+		}
+		if (demoNames.has(name)) {
+			menu[name] = await bootstrapMenu(name);
+			continue;
+		}
+		if (supplied !== void 0) {
+			menu[name] = [seedCandidate[name], ...supplied];
+			continue;
+		}
+		const drawn = await require_concurrency.mapWithConcurrency({
+			items: Array.from({ length: instructionsPerComponent }, (_, index) => index),
+			limit: concurrency,
+			signal,
+			task: async (index) => {
+				reflectionCalls += 1;
+				return require_text.parseProposedText(await reflect({
+					prompt: buildPrompt({
+						componentName: name,
+						seedText: seedCandidate[name],
+						exemplars: shown,
+						tip: tips[index % tips.length],
+						...summary === void 0 || summary.length === 0 ? {} : { datasetSummary: summary },
+						siblings: Object.fromEntries(components.filter((other) => other !== name).map((other) => [other, seedCandidate[other]]))
+					}),
+					...signal === void 0 ? {} : { signal }
+				}));
+			}
+		});
+		menu[name] = [seedCandidate[name], ...drawn.filter((text) => text.length > 0)];
+	}
+	onEvent?.({
+		type: "menu",
+		menu,
+		reflectionCalls
+	});
+	const menuSizes = components.map((name) => menu[name].length);
+	function candidateFor(choices) {
+		const candidate = {};
+		components.forEach((name, index) => {
+			candidate[name] = menu[name][choices[index]];
+		});
+		return candidate;
+	}
+	let trial = resumeFrom?.trial ?? 0;
+	let fullEvaluations = resumeFrom?.fullEvaluations ?? 0;
+	const observations = [...resumeFrom?.observations ?? []];
+	const surrogateInput = [...resumeFrom?.surrogateInput ?? []];
+	let stopReason = "maxTrials";
+	async function fullSweep(candidate, phase) {
+		return evaluator.evaluate({
+			candidate,
+			batch: validationSet,
+			ids: validationIds,
+			split: "val",
+			phase,
+			candidateId: null,
+			iteration: trial
+		});
+	}
+	const seedEvaluation = resumeFrom === void 0 ? await fullSweep(seedCandidate, "seed") : void 0;
+	const seedScore = seedEvaluation === void 0 ? resumeFrom.seedScore : require_evaluation.requireMeasuredMean({
+		batch: seedEvaluation,
+		phase: "seed"
+	});
+	if (seedEvaluation !== void 0) fullEvaluations += 1;
+	if (resumeFrom === void 0) surrogateInput.push({
+		choices: menuSizes.map(() => 0),
+		score: seedScore
+	});
+	let best = resumeFrom?.best ?? seedCandidate;
+	let bestScore = resumeFrom?.bestScore ?? seedScore;
+	/** Absent on a resumed run until a sweep wins: outputs are not checkpointed. */
+	let bestOutputs = seedEvaluation?.outputs;
+	const readings = new Map(resumeFrom?.readings ?? []);
+	const swept = new Set(resumeFrom?.swept ?? []);
+	function takeSnapshot() {
+		const cached = checkpointCache ? evaluationCache?.entries?.() : void 0;
+		const samplerState = batchSampler.state?.();
+		return {
+			version: 1,
+			fingerprint,
+			menu: { ...menu },
+			best,
+			bestScore,
+			seedScore,
+			trial,
+			fullEvaluations,
+			reflectionCalls,
+			bootstrapMetricCalls,
+			metricCalls: budget.spent(),
+			cacheHits: evaluator.cacheHits(),
+			rngState: rng.state(),
+			observations: [...observations],
+			surrogateInput: surrogateInput.map((entry) => ({
+				choices: [...entry.choices],
+				score: entry.score
+			})),
+			readings: [...readings].map(([key, values]) => [key, [...values]]),
+			swept: [...swept],
+			...samplerState === void 0 ? {} : { sampler: samplerState },
+			...cached === void 0 ? {} : { cache: cached }
+		};
+	}
+	async function checkpoint() {
+		if (onCheckpoint === void 0) return;
+		await onCheckpoint(takeSnapshot());
+	}
+	await checkpoint();
+	/**
+	* Full-evaluates the strongest configuration by mean minibatch reading that
+	* has not been swept yet. Only a full sweep can move the incumbent, so a
+	* lucky minibatch buys a candidate a closer look and nothing more.
+	*/
+	async function sweepBestUnswept() {
+		let bestKey;
+		let bestMean = Number.NEGATIVE_INFINITY;
+		for (const [key, values] of readings) {
+			if (swept.has(key)) continue;
+			const value = require_math.mean(values);
+			if (value > bestMean) {
+				bestMean = value;
+				bestKey = key;
+			}
+		}
+		if (bestKey === void 0) return "none";
+		if (!budget.canAfford(validationSet.length)) return "unaffordable";
+		const choices = bestKey.split(",").map(Number);
+		const candidate = candidateFor(choices);
+		swept.add(bestKey);
+		let evaluation;
+		try {
+			evaluation = await fullSweep(candidate, "validation");
+		} catch (err) {
+			if (err instanceof require_evaluation.BudgetExhausted) return "budgetExhausted";
+			if (signal?.aborted) return "aborted";
+			throw err;
+		}
+		fullEvaluations += 1;
+		const score = require_evaluation.measuredMean(evaluation);
+		if (score === void 0) return "swept";
+		surrogateInput.push({
+			choices,
+			score
+		});
+		for (const observation of observations) if (observation.choices.join(",") === bestKey) {
+			observation.promoted = true;
+			observation.score = score;
+		}
+		if (score > bestScore) {
+			best = candidate;
+			bestScore = score;
+			bestOutputs = evaluation.outputs;
+			onEvent?.({
+				type: "incumbent",
+				trial,
+				choices,
+				score
+			});
+		}
+		return "swept";
+	}
+	while (trial < maxTrials) {
+		if (signal?.aborted) {
+			stopReason = "aborted";
+			break;
+		}
+		if (require_evaluation.costExhausted({
+			usage: evaluator.usage(),
+			maxCostUsd
+		})) {
+			stopReason = "costExhausted";
+			break;
+		}
+		if (deadline.exceeded()) {
+			stopReason = "deadlineReached";
+			break;
+		}
+		if (!budget.canAfford(minibatchSize)) {
+			stopReason = "budgetExhausted";
+			break;
+		}
+		if (!budget.canAfford(validationSet.length)) {
+			stopReason = "budgetExhausted";
+			break;
+		}
+		const choices = proposeConfiguration({
+			observations: surrogateInput,
+			menuSizes,
+			...gamma === void 0 ? {} : { gamma },
+			...surrogateSamples === void 0 ? {} : { samples: surrogateSamples },
+			...startupTrials === void 0 ? {} : { startupTrials },
+			...multivariate === void 0 ? {} : { multivariate },
+			rng
+		});
+		const candidate = candidateFor(choices);
+		const batchIndices = batchSampler({
+			trainingSet,
+			iteration: trial,
+			rng
+		});
+		let minibatchScore;
+		try {
+			const evaluation = await evaluator.evaluate({
+				candidate,
+				batch: batchIndices.map((index) => trainingSet[index]),
+				ids: batchIndices.map((index) => trainingIds[index]),
+				split: "train",
+				phase: "minibatch",
+				candidateId: null,
+				iteration: trial
+			});
+			minibatchScore = require_evaluation.measuredMean(evaluation);
+		} catch (err) {
+			if (err instanceof require_evaluation.BudgetExhausted) {
+				stopReason = "budgetExhausted";
+				break;
+			}
+			if (signal?.aborted) {
+				stopReason = "aborted";
+				break;
+			}
+			throw err;
+		}
+		if (minibatchScore === void 0) {
+			trial += 1;
+			continue;
+		}
+		surrogateInput.push({
+			choices,
+			score: minibatchScore
+		});
+		const key = choices.join(",");
+		readings.set(key, [...readings.get(key) ?? [], minibatchScore]);
+		const observation = {
+			trial,
+			choices,
+			minibatchScore,
+			promoted: false
+		};
+		observations.push(observation);
+		onEvent?.({
+			type: "trial",
+			trial,
+			choices,
+			minibatchScore,
+			promoted: false
+		});
+		trial += 1;
+		await checkpoint();
+		if (trial % fullEvalInterval === 0) {
+			const outcome = await sweepBestUnswept();
+			if (outcome === "budgetExhausted" || outcome === "aborted") {
+				stopReason = outcome;
+				break;
+			}
+			if (outcome === "unaffordable") {
+				stopReason = "budgetExhausted";
+				break;
+			}
+		}
+	}
+	if (stopReason === "maxTrials" && !signal?.aborted) await sweepBestUnswept();
+	if (signal?.aborted) stopReason = "aborted";
+	const testScore = testSet === void 0 ? void 0 : require_evaluation.measuredMean(await evaluator.evaluate({
+		candidate: best,
+		batch: testSet,
+		ids: testIds,
+		split: "test",
+		phase: "test",
+		candidateId: null,
+		iteration: trial,
+		charge: false
+	}));
+	onEvent?.({
+		type: "finish",
+		reason: stopReason,
+		bestScore,
+		metricCalls: budget.spent(),
+		...testScore === void 0 ? {} : { testScore }
+	});
+	return {
+		snapshot: takeSnapshot(),
+		bestCandidate: best,
+		bestScore,
+		usage: evaluator.usage(),
+		seedScore,
+		...trackBestOutputs ? { bestOutputs } : {},
+		...testScore === void 0 ? {} : {
+			testScore,
+			testMetricCalls: evaluator.unchargedCalls()
+		},
+		trials: trial,
+		menu,
+		observations,
+		fullEvaluations,
+		bootstrapMetricCalls,
+		metricCalls: budget.spent(),
+		reflectionCalls,
+		cacheHits: evaluator.cacheHits(),
+		stopReason
+	};
+}
+function renderDefault(datum) {
+	if (typeof datum === "string") return datum;
+	try {
+		return JSON.stringify(datum, null, 2) ?? String(datum);
+	} catch {
+		return String(datum);
+	}
+}
+function assertConfig(config) {
+	const positive = [
+		["minibatchSize", config.minibatchSize],
+		["maxTrials", config.maxTrials],
+		["surrogateSamples", config.surrogateSamples],
+		["concurrency", config.concurrency]
+	];
+	for (const [name, value] of positive) if (value !== void 0 && (!Number.isInteger(value) || value < 1)) throw new Error(`${name} must be a positive integer, received ${value}`);
+	const nonNegative = [
+		["instructionsPerComponent", config.instructionsPerComponent],
+		["startupTrials", config.startupTrials],
+		["exemplars", config.exemplars]
+	];
+	for (const [name, value] of nonNegative) if (value !== void 0 && (!Number.isInteger(value) || value < 0)) throw new Error(`${name} must be a non-negative integer, received ${value}`);
+	if (config.gamma !== void 0 && (!Number.isFinite(config.gamma) || config.gamma <= 0 || config.gamma > 1)) throw new Error(`gamma must be within (0, 1], received ${config.gamma}`);
+	if (config.tips !== void 0 && config.tips.length === 0) throw new Error("tips must not be empty");
+}
+function defaultInstanceId(args) {
+	const hash = require_evaluation.stableHash(args.datum);
+	return hash === "" ? String(args.index) : hash;
+}
+//#endregion
+exports.MiproOptimizer = MiproOptimizer;
+exports.buildMiproPrompt = buildMiproPrompt;
+exports.proposeConfiguration = proposeConfiguration;