auto-model-router 0.1.0

package/src/cli/explain.ts

@@ -0,0 +1,167 @@
+/**
+ * `auto-model-router explain` - route a real request and show the reasoning, without
+ * dispatching it.
+ *
+ * The only network call this can make is a catalog refresh; no completion is
+ * ever requested, so it never spends money on inference. It is also
+ * side-effect-free on conversation state, because `createRouter` is read-only
+ * there by construction.
+ */
+
+import { existsSync } from "node:fs";
+
+import { createCatalog } from "../catalog/openrouter-catalog.ts";
+import { loadConfig } from "../config/load.ts";
+import { createLedger } from "../cost/ledger.ts";
+import { createRouter } from "../router/index.ts";
+import { createConversationStore } from "../router/state.ts";
+import type { Candidate, Decision, Features, Rejection } from "../router/types.ts";
+import { createOpenRouterClient } from "../upstream/openrouter.ts";
+import { openDb } from "../util/sqlite.ts";
+import { parseChatRequest } from "../wire/openai/request.ts";
+import { configOpts, flagString, type CliArgs } from "./args.ts";
+
+/** Sub-cent routing decisions need real significant figures, not two decimals. */
+function usd(value: number): string {
+	return `$${value.toFixed(6)}`;
+}
+
+/**
+ * Feature rows worth printing even at zero, because their absence is itself
+ * the signal that explains a cheap route.
+ */
+const ALWAYS_SHOW: Record<string, true> = {
+	promptTokens: true,
+	newContentTokens: true,
+	toolCount: true,
+	isToolResultContinuation: true,
+	toolLoopDepth: true,
+	lastToolFailed: true,
+	repeatedToolCall: true,
+	turnDepth: true,
+};
+
+function renderFeatures(f: Features): void {
+	console.log("features:");
+	const entries = Object.entries(f) as [string, unknown][];
+	const width = Math.max(...entries.map(([k]) => k.length));
+	for (const [key, value] of entries) {
+		const empty =
+			value === false ||
+			value === 0 ||
+			value === undefined ||
+			(Array.isArray(value) && value.length === 0);
+		if (empty && ALWAYS_SHOW[key] !== true) continue;
+		const rendered = Array.isArray(value) ? (value.length === 0 ? "-" : value.join(", ")) : String(value);
+		console.log(`  ${key.padEnd(width)}  ${rendered}`);
+	}
+}
+
+function renderCandidates(considered: Candidate[]): void {
+	console.log("\nranked candidates:");
+	if (considered.length === 0) {
+		console.log("  (none survived filtering)");
+		return;
+	}
+	const rows = considered.slice(0, 10);
+	const width = Math.max(5, ...rows.map((c) => c.model.slug.length));
+	console.log(
+		`  ${"model".padEnd(width)}  ${"qual".padStart(5)}  ${"trust".padStart(5)}  ${"expected".padStart(10)}  ${"cold".padStart(10)}  ${"score".padStart(12)}`,
+	);
+	for (const c of rows) {
+		console.log(
+			`  ${c.model.slug.padEnd(width)}  ${c.qualityScore.toFixed(1).padStart(5)}  ${c.trustScore.toFixed(2).padStart(5)}  ${usd(c.forecast.expectedUsd).padStart(10)}  ${usd(c.forecast.coldUsd).padStart(10)}  ${c.score.toExponential(3).padStart(12)}`,
+		);
+	}
+	if (considered.length > rows.length) console.log(`  ... ${considered.length - rows.length} more`);
+}
+
+function renderRejections(rejected: Rejection[]): void {
+	if (rejected.length === 0) return;
+	const byReason = new Map<string, string[]>();
+	for (const r of rejected) {
+		const list = byReason.get(r.reason);
+		if (list === undefined) byReason.set(r.reason, [r.slug]);
+		else list.push(r.slug);
+	}
+	console.log("\nexcluded:");
+	for (const [reason, slugs] of [...byReason.entries()].sort((a, b) => b[1].length - a[1].length)) {
+		console.log(`  ${reason.padEnd(22)} ${String(slugs.length).padStart(4)}  e.g. ${slugs.slice(0, 3).join(", ")}`);
+	}
+}
+
+function renderDecision(d: Decision): void {
+	console.log("\ndecision:");
+	console.log(`  model            ${d.slug}`);
+	console.log(`  fallbacks        ${d.fallbacks.length === 0 ? "-" : d.fallbacks.join(", ")}`);
+	console.log(`  tier             ${d.tier}`);
+	console.log(`  sticky           ${d.sticky}`);
+	console.log(`  budgetDowngraded ${d.budgetDowngraded}`);
+	console.log(`  expected cost    ${usd(d.forecast.expectedUsd)}  (cold ${usd(d.forecast.coldUsd)})`);
+	console.log(`  reasoning        ${d.reasoning ?? "-"}`);
+	console.log(`  maxTokens        ${d.maxTokens ?? "-"}`);
+	console.log(`  stripReasoning   ${d.stripAssistantReasoning}`);
+	console.log(
+		`  cache points     ${d.cacheBreakpointMessageIndices.length === 0 ? "none" : d.cacheBreakpointMessageIndices.join(", ")}`,
+	);
+	console.log(
+		`  probe            ${d.probe.enabled ? `${d.probe.maxTokens} tokens / ${d.probe.maxHoldMs}ms, escalate to ${d.probe.escalateTo ?? "-"}` : "disabled"}`,
+	);
+	console.log(`  session          ${d.sessionId}`);
+	if (d.reasons.length > 0) {
+		console.log("  why:");
+		for (const reason of d.reasons) console.log(`    - ${reason}`);
+	}
+}
+
+export async function explainCommand(args: CliArgs): Promise<void> {
+	const cfg = loadConfig(configOpts(args));
+	const file = flagString(args, "file");
+	const raw = file === undefined ? await Bun.stdin.text() : await Bun.file(file).text();
+	if (raw.trim() === "") throw new Error("no request body supplied (pass --file <request.json> or pipe JSON on stdin)");
+
+	let body: unknown;
+	try {
+		body = JSON.parse(raw);
+	} catch (err) {
+		throw new Error(`request body is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+	}
+
+	const req = parseChatRequest(body, new Headers());
+
+	const db = openDb(cfg.ledger.path);
+	try {
+		const ledger = createLedger(db, cfg);
+		const upstream = createOpenRouterClient(cfg);
+		const catalog = createCatalog(cfg, upstream, db);
+		const conversations = createConversationStore(db);
+		const router = createRouter({ config: cfg, catalog, ledger, conversations, upstream });
+
+		const decision = await router.route(req, { attempt: 0 });
+
+		if (args.flags.has("json")) {
+			console.log(JSON.stringify(decision, null, 2));
+			return;
+		}
+
+		const state = conversations.get(req.conversationKey);
+		console.log(`request: ${req.messages.length} messages, ${req.tools.length} tools, model "${req.requestedModel}"`);
+		console.log(`conversation: ${req.conversationKey} (turn ${state?.turn ?? 0}, prior model ${state?.currentSlug ?? "none"})`);
+		console.log(
+			`ledger: ${existsSync(cfg.ledger.path) ? `${cfg.ledger.path}` : "(new)"}  spent so far ${usd(state?.spentUsd ?? 0)}`,
+		);
+		console.log("");
+		renderFeatures(decision.features);
+		const c = decision.classification;
+		console.log(
+			`\nclassification: ${c.tier}  (score ${c.score.toFixed(3)}, confidence ${c.confidence.toFixed(3)}, source ${c.source})`,
+		);
+		for (const reason of c.reasons) console.log(`  - ${reason}`);
+		renderCandidates(decision.considered);
+		renderRejections(decision.rejected);
+		renderDecision(decision);
+		console.log("\n(no completion was dispatched; nothing was billed)");
+	} finally {
+		db.close();
+	}
+}

package/src/cli/models.ts

@@ -0,0 +1,240 @@
+/**
+ * `auto-model-router models` - the operator's window into routing policy.
+ *
+ * Eligibility is computed by calling the REAL `buildCandidates` path against a
+ * representative synthetic request, not by reimplementing the filters here.
+ * A second copy of the filter logic would drift from the router and this
+ * command's whole value is that it cannot lie about what would be chosen.
+ */
+
+import { existsSync } from "node:fs";
+import type { Database } from "bun:sqlite";
+
+import { createCatalog } from "../catalog/openrouter-catalog.ts";
+import { effectiveQualityFloor, tierPlanFor } from "../router/tier-plan.ts";
+import { loadConfig } from "../config/load.ts";
+import type { QualityAxis, RouterConfig } from "../config/types.ts";
+import { createLedger } from "../cost/ledger.ts";
+import type { Ledger } from "../cost/types.ts";
+import { buildCandidates } from "../router/candidates.ts";
+import { classifyTask } from "../router/classify.ts";
+import { extractFeatures } from "../router/features.ts";
+import { TIER_ORDER, type Candidate, type Rejection, type Tier } from "../router/types.ts";
+import { estimatePromptTokens } from "../tokens/estimate.ts";
+import { createOpenRouterClient } from "../upstream/openrouter.ts";
+import { openDb } from "../util/sqlite.ts";
+import { parseChatRequest } from "../wire/openai/request.ts";
+import { configOpts, flagInt, flagString, type CliArgs } from "./args.ts";
+
+/** Mid-range completion assumption, matching select.ts so forecasts line up. */
+const EXPECTED_COMPLETION_TOKENS = 1024;
+const DEFAULT_LIMIT = 15;
+
+/**
+ * A representative agent turn: tools offered, some history, no images. The
+ * survey is only meaningful relative to a concrete request shape, and this is
+ * the shape omp actually sends.
+ */
+function syntheticRequest() {
+	const tools = [
+		{
+			type: "function",
+			function: {
+				name: "read",
+				description: "Read a file from disk",
+				parameters: { type: "object", properties: { path: { type: "string" } }, required: ["path"] },
+			},
+		},
+		{
+			type: "function",
+			function: {
+				name: "edit",
+				description: "Apply a line-anchored patch to a file",
+				parameters: { type: "object", properties: { path: { type: "string" }, patch: { type: "string" } } },
+			},
+		},
+	];
+	return parseChatRequest(
+		{
+			model: "auto",
+			stream: true,
+			tools,
+			messages: [
+				{ role: "system", content: "You are a coding agent operating in a repository." },
+				{ role: "user", content: "Refactor the retry helper so the backoff is testable." },
+			],
+		},
+		new Headers(),
+	);
+}
+
+function perMtok(perToken: number): string {
+	return (perToken * 1e6).toFixed(3);
+}
+
+/**
+ * "no published benchmark" and "benchmarked as weak" are different facts, and
+ * collapsing both to 0.0 would misrepresent why a model is or is not eligible.
+ */
+function qualityCell(c: Candidate): string {
+	const q = c.model.quality;
+	const unscored = q.coding === undefined && q.agentic === undefined && q.intelligence === undefined;
+	return unscored ? "-" : c.qualityScore.toFixed(1);
+}
+
+interface TierReport {
+	tier: Tier;
+	/** The tier's configured `minQuality`. */
+	minQuality: number;
+	/** Floor actually enforced; differs under adaptive floors or a task floor. */
+	effectiveQuality: number;
+	/** `tasks.*.minQuality`, 0 when unset. Never relaxed by adaptive floors. */
+	taskFloor: number;
+	axis: QualityAxis;
+	candidates: Candidate[];
+	rejected: Rejection[];
+}
+
+function renderTier(report: TierReport, limit: number): void {
+	const { tier, candidates, rejected } = report;
+	// Name the mechanism that moved the floor, so a surprising eligible set is
+	// explainable: a task floor RAISES it, an adaptive band LOWERS it.
+	const { minQuality, effectiveQuality, taskFloor } = report;
+	let floor = String(minQuality);
+	if (effectiveQuality !== minQuality) {
+		const why = taskFloor > 0 && effectiveQuality === taskFloor ? "task floor" : "adaptive";
+		floor = `${minQuality} → ${effectiveQuality.toFixed(1)} (${why})`;
+	}
+	console.log(
+		`\n[${tier}]  quality floor ${floor} on the ${report.axis} axis  -  ${candidates.length} eligible, ${rejected.length} excluded`,
+	);
+	if (candidates.length === 0) {
+		console.log("  (nothing eligible: loosen the tier's floor or price ceiling)");
+	} else {
+		const rows = candidates.slice(0, limit);
+		const slugWidth = Math.max(5, ...rows.map((c) => c.model.slug.length));
+		console.log(
+			`  ${"model".padEnd(slugWidth)}  ${"qual".padStart(5)}  ${"trust".padStart(5)}  ${"$/Mtok in".padStart(10)}  ${"$/Mtok out".padStart(10)}  ${"ctx".padStart(9)}  ${"turn $".padStart(9)}`,
+		);
+		console.log(
+			`  ${"-".repeat(slugWidth)}  ${"-".repeat(5)}  ${"-".repeat(5)}  ${"-".repeat(10)}  ${"-".repeat(10)}  ${"-".repeat(9)}  ${"-".repeat(9)}`,
+		);
+		for (const c of rows) {
+			console.log(
+				`  ${c.model.slug.padEnd(slugWidth)}  ${qualityCell(c).padStart(5)}  ${c.trustScore.toFixed(2).padStart(5)}  ${perMtok(c.model.price.prompt).padStart(10)}  ${perMtok(c.model.price.completion).padStart(10)}  ${c.model.contextLength.toLocaleString("en-US").padStart(9)}  ${`$${c.forecast.expectedUsd.toFixed(5)}`.padStart(9)}`,
+			);
+		}
+		if (candidates.length > rows.length) console.log(`  ... ${candidates.length - rows.length} more`);
+	}
+
+	// Hundreds of rejections per tier: summarise by cause, with examples.
+	const byReason = new Map<string, string[]>();
+	for (const r of rejected) {
+		const list = byReason.get(r.reason);
+		if (list === undefined) byReason.set(r.reason, [r.slug]);
+		else list.push(r.slug);
+	}
+	if (byReason.size > 0) {
+		console.log("  excluded:");
+		const ordered = [...byReason.entries()].sort((a, b) => b[1].length - a[1].length);
+		for (const [reason, slugs] of ordered) {
+			console.log(`    ${reason.padEnd(22)} ${String(slugs.length).padStart(4)}  e.g. ${slugs.slice(0, 3).join(", ")}`);
+		}
+	}
+}
+
+export async function modelsCommand(args: CliArgs): Promise<void> {
+	const cfg: RouterConfig = loadConfig(configOpts(args));
+	const limit = flagInt(args, "limit") ?? DEFAULT_LIMIT;
+	const tierFlag = flagString(args, "tier");
+	if (tierFlag !== undefined && !(TIER_ORDER as readonly string[]).includes(tierFlag)) {
+		throw new Error(`--tier must be one of ${TIER_ORDER.join(", ")}, got "${tierFlag}"`);
+	}
+	const tiers = tierFlag === undefined ? TIER_ORDER : [tierFlag as Tier];
+
+	// Reuse the on-disk catalog cache when present so a survey costs no network.
+	const db: Database = openDb(cfg.ledger.path);
+	const ledger: Ledger | null = existsSync(cfg.ledger.path) ? createLedger(db, cfg) : null;
+	try {
+		const upstream = createOpenRouterClient(cfg);
+		const catalog = createCatalog(cfg, upstream, db);
+		const snapshot = await catalog.get();
+
+		const req = syntheticRequest();
+		const promptTokens = estimatePromptTokens(req, "gpt", ledger);
+		const features = extractFeatures(req, promptTokens);
+
+		const reports: TierReport[] = tiers.map((tier) => {
+			const tierCfg = cfg.tiers[tier];
+			const task = classifyTask(features);
+			const axis = cfg.tasks[task].axis;
+			const { candidates, rejected } = buildCandidates({
+				req,
+				features,
+				tier,
+				task,
+				snapshot,
+				ledger,
+				cfg,
+				expectedCompletionTokens: EXPECTED_COMPLETION_TOKENS,
+				warmSlug: null,
+			});
+			// Report the floor actually enforced, which is what `buildCandidates`
+			// computes: the adaptive tier floor raised by any task floor. Printing
+			// the bare tier constant made an eligible tier look impossible under
+			// adaptive floors, and hid a `tasks.*.minQuality` entirely.
+			const adaptive = cfg.adaptiveTierFloors
+				? effectiveQualityFloor(tierCfg.minQuality, tier, axis, tierPlanFor(snapshot, cfg))
+				: tierCfg.minQuality;
+			const taskFloor = cfg.tasks[task].minQuality ?? 0;
+			return {
+				tier,
+				minQuality: tierCfg.minQuality,
+				effectiveQuality: Math.max(adaptive, taskFloor),
+				taskFloor,
+				axis,
+				candidates,
+				rejected,
+			};
+		});
+
+		if (args.flags.has("json")) {
+			console.log(
+				JSON.stringify(
+					{
+						catalogModels: snapshot.models.length,
+						catalogAgeMs: Date.now() - snapshot.fetchedAtMs,
+						promptTokens,
+						tiers: reports.map((r) => ({
+							tier: r.tier,
+							minQuality: r.minQuality,
+							axis: r.axis,
+							eligible: r.candidates.slice(0, limit).map((c) => ({
+								slug: c.model.slug,
+								quality: c.qualityScore,
+								trust: c.trustScore,
+								inputPerMtok: c.model.price.prompt * 1e6,
+								outputPerMtok: c.model.price.completion * 1e6,
+								contextLength: c.model.contextLength,
+								expectedUsd: c.forecast.expectedUsd,
+								score: c.score,
+							})),
+							excluded: r.rejected.length,
+						})),
+					},
+					null,
+					2,
+				),
+			);
+			return;
+		}
+
+		console.log(
+			`catalog: ${snapshot.models.length} usable models, fetched ${Math.round((Date.now() - snapshot.fetchedAtMs) / 1000)}s ago`,
+		);
+		console.log(`survey request: ${promptTokens} estimated prompt tokens, ${req.tools.length} tools offered`);
+		for (const report of reports) renderTier(report, limit);
+	} finally {
+		db.close();
+	}
+}

package/src/cli/stats.ts

@@ -0,0 +1,69 @@
+import { existsSync } from "node:fs";
+import type { Database } from "bun:sqlite";
+import { loadConfig } from "../config/load.ts";
+import { createLedger } from "../cost/ledger.ts";
+import { computeStats, type RouterStats } from "../server/http.ts";
+import { openDb } from "../util/sqlite.ts";
+import { configOpts, flagInt, type CliArgs } from "./args.ts";
+
+function usd(v: number): string {
+	return `$${v.toFixed(4)}`;
+}
+
+function renderStats(stats: RouterStats): void {
+	const windowLabel = stats.windowDays === null ? "all time" : `last ${stats.windowDays}d`;
+	console.log(`window: ${windowLabel}   requests: ${stats.requests}   escalations: ${stats.escalations} (${(stats.escalationRate * 100).toFixed(1)}%)`);
+	console.log(`spend: window ${usd(stats.windowSpendUsd)}   today ${usd(stats.spendTodayUsd)}   7d ${usd(stats.spend7dUsd)}   all-time ${usd(stats.spendAllTimeUsd)}`);
+	console.log(
+		`predicted-vs-reported drift: ${stats.meanPredictionError === null ? "n/a (no reported costs yet)" : `${(stats.meanPredictionError * 100).toFixed(1)}% mean relative error`}`,
+	);
+	console.log("");
+
+	const slugWidth = Math.max(5, ...stats.perModel.map((r) => r.slug.length));
+	console.log(`${"model".padEnd(slugWidth)}  ${"req".padStart(5)}  ${"spend".padStart(9)}  ${"share".padStart(6)}`);
+	console.log(`${"-".repeat(slugWidth)}  ${"-".repeat(5)}  ${"-".repeat(9)}  ${"-".repeat(6)}`);
+	if (stats.perModel.length === 0) {
+		console.log("(no ledger entries in this window)");
+		return;
+	}
+	for (const r of stats.perModel) {
+		console.log(
+			`${r.slug.padEnd(slugWidth)}  ${String(r.requests).padStart(5)}  ${usd(r.spendUsd).padStart(9)}  ${(r.share * 100).toFixed(1).padStart(5)}%`,
+		);
+	}
+}
+
+export async function statsCommand(args: CliArgs): Promise<void> {
+	const days = flagInt(args, "days") ?? 7;
+	const cfg = loadConfig(configOpts(args));
+
+	// A stats query must not create the ledger file just by looking.
+	let db: Database | null = null;
+	let stats: RouterStats;
+	if (existsSync(cfg.ledger.path)) {
+		db = openDb(cfg.ledger.path);
+		stats = computeStats(createLedger(db, cfg), { windowDays: days });
+	} else {
+		stats = {
+			generatedAtMs: Date.now(),
+			windowDays: days,
+			spendTodayUsd: 0,
+			spend7dUsd: 0,
+			spendAllTimeUsd: 0,
+			windowSpendUsd: 0,
+			requests: 0,
+			escalations: 0,
+			escalationRate: 0,
+			meanPredictionError: null,
+			perModel: [],
+			trust: [],
+		};
+	}
+
+	try {
+		if (args.flags.has("json")) console.log(JSON.stringify(stats, null, 2));
+		else renderStats(stats);
+	} finally {
+		db?.close();
+	}
+}

package/src/config/defaults.ts

@@ -0,0 +1,136 @@
+import type { RouterConfig } from "./types.ts";
+
+/**
+ * Built-in configuration. Layered beneath `$AUTO_MODEL_ROUTER_HOME/config.yml`,
+ * environment variables, and CLI overrides (see `load.ts`).
+ *
+ * `ledger.path` is intentionally empty: `loadConfig` resolves it to
+ * `$AUTO_MODEL_ROUTER_HOME/router.db`, which is only known at load time.
+ */
+export const DEFAULT_CONFIG: RouterConfig = {
+	server: {
+		host: "127.0.0.1",
+		port: 8788,
+	},
+	openrouter: {
+		baseUrl: "https://openrouter.ai/api/v1",
+		// May stay empty: catalog and `config` work keyless; only dispatch fails.
+		apiKey: "",
+		title: "auto-model-router",
+		// Agent turns are long; a frontier model with tools can stream for minutes.
+		timeoutMs: 600_000,
+		catalogTtlMs: 6 * 60 * 60 * 1000,
+		// Refetch the key-scoped catalog every 5 minutes in the background so
+		// guardrail changes are picked up without waiting for traffic + TTL.
+		catalogRefreshMs: 5 * 60 * 1000,
+	},
+	tiers: {
+		// minQuality 0 ⇒ unscored models are eligible here; the floor does the
+		// quality work on every other tier (qualityExponent 0 ⇒ cheapest above floor).
+		trivial: { minQuality: 0, maxInputPerMtok: 0.3, qualityExponent: 0, pin: [] },
+		simple: { minQuality: 40, maxInputPerMtok: 1.5, qualityExponent: 0, pin: [] },
+		moderate: { minQuality: 60, maxInputPerMtok: 4.0, qualityExponent: 1, pin: [] },
+		// No price ceiling on `hard`: quality is the point of the top tier.
+		hard: { minQuality: 72, qualityExponent: 3, pin: [] },
+	},
+	tasks: {
+		// Task selects the axis + capability; the tier's quality floor, price
+		// ceiling, and budget guard still govern cost. A task minQuality only
+		// RAISES the tier floor for special cases (e.g. vision needs quality);
+		// it must not force cheap tiers to be expensive, or escalation has no
+		// room to move.
+		coding: { axis: "coding" },
+		vision: { axis: "intelligence", requireImage: true },
+		documentation: { axis: "intelligence" },
+		data: { axis: "intelligence" },
+		chat: { axis: "intelligence" },
+	},
+	filters: {
+		allow: [],
+		deny: [],
+		// Free models are rate-limited hard enough that retries cost more than they save.
+		includeFree: false,
+		requireToolSupport: true,
+		minTrust: 0.7,
+		minTrustSamples: 12,
+		// Shared trust by default: more samples, demotion guard stays effective
+		// even with a tiny guardrail-narrowed catalog.
+		trustScopedByHarness: false,
+		contextHeadroom: 1.25,
+	},
+	classifier: {
+		ambiguityThreshold: 0.6,
+		// Cheapest competent slug in the catalog; adjudication prompts are tiny.
+		model: "qwen/qwen3.7-flash",
+		maxCostFraction: 0.02,
+		maxCostUsd: 0.002,
+		timeoutMs: 4_000,
+		cacheSize: 512,
+		toolAxis: "coding",
+		chatAxis: "intelligence",
+		agenticLoopDepth: 3,
+	},
+	escalation: {
+		enabled: true,
+		probeTokens: 48,
+		maxHoldMs: 8_000,
+		// 3 attempts = the original try plus two retries: enough runway for a
+		// probe-driven escalation AND a same-tier failover on an upstream error.
+		// Each attempt beyond the first can abandon already-generated tokens, so
+		// this is the direct dial between turn reliability and wasted spend.
+		maxAttempts: 3,
+		// Never probe `hard`: the top tier has nowhere to escalate to.
+		probeTiers: ["trivial", "simple", "moderate"],
+		triggers: [
+			"malformed_tool_args",
+			"refusal",
+			"empty_completion",
+			"repeat_tool_call",
+			"missing_expected_tool_call",
+		],
+		// Scoped to the case it can actually fix: a `length` finish that truncated
+		// tool-call arguments leaves unusable output, and another model may emit a
+		// well-formed call before the cap. A length finish on prose does NOT
+		// escalate — that is the caller's own max_tokens, and the retry truncates
+		// in the same place, so escalating just bills twice for one truncation.
+		escalateOnLengthStop: true,
+	},
+	hysteresis: {
+		holdTurns: 2,
+		holdTurnsAfterEscalation: 4,
+		switchMargin: 1.3,
+		// OpenRouter sticky sessions expire in 5-10 minutes.
+		cacheWarmTtlMs: 300_000,
+		maxDowngradePerTurn: 1,
+	},
+	cache: {
+		injectBreakpoints: true,
+		// Anthropic allows 4 breakpoints; OpenRouter translates for other vendors.
+		maxBreakpoints: 4,
+		minPromptTokens: 2_048,
+	},
+	budget: {
+		// No caps by default; at a configured ceiling, downgrade rather than fail.
+		onExceeded: "downgrade",
+	},
+	profiles: [
+		{ id: "auto", name: "Auto (auto-model-router)", minTier: "trivial", maxTier: "hard", contextWindow: 400_000, maxTokens: 32_000 },
+		{ id: "auto-cheap", name: "Auto Cheap (auto-model-router)", minTier: "trivial", maxTier: "simple", contextWindow: 400_000, maxTokens: 32_000 },
+		{ id: "auto-max", name: "Auto Max (auto-model-router)", minTier: "moderate", maxTier: "hard", contextWindow: 400_000, maxTokens: 32_000 },
+	],
+	ledger: {
+		// Resolved by loadConfig: empty ⇒ `$AUTO_MODEL_ROUTER_HOME/router.db`.
+		path: "",
+		blendWindowDays: 7,
+		blendMinSamples: 25,
+		// Pre-measurement blend for omp's cost display: a moderate-heavy mix.
+		// Consumers publish cache tokens at the full input rate until measured,
+		// so early cost reporting never underreports.
+		fallbackBlend: { inputPerMtok: 1.5, outputPerMtok: 7.5 },
+		conversationTtlMs: 7 * 24 * 60 * 60 * 1000,
+	},
+	// On by default: an absolute floor that no available model meets is how the
+	// router ends up serving every turn from the cheapest tier.
+	adaptiveTierFloors: true,
+	logLevel: "info",
+};