auto-model-router 0.1.0

package/src/index.ts

@@ -0,0 +1,93 @@
+#!/usr/bin/env bun
+/**
+ * CLI entry point.
+ *
+ * Argv parsing is hand-rolled in `cli/args.ts`: five subcommands and a dozen
+ * flags do not justify a dependency, and the shape stays obvious.
+ */
+
+import { join } from "node:path";
+
+import { parseArgv } from "./cli/args.ts";
+import { configCommand } from "./cli/config-cmd.ts";
+import { explainCommand } from "./cli/explain.ts";
+import { modelsCommand } from "./cli/models.ts";
+import { statsCommand } from "./cli/stats.ts";
+
+const USAGE = `auto-model-router - local cost/complexity-aware model router for omp, backed by OpenRouter
+
+Usage: auto-model-router <command> [options]
+
+Commands:
+  stats      Show routed spend, per-model share, and escalation rates
+  models     Show what each complexity tier would consider, and why
+  explain    Route a saved request without dispatching it, and explain the decision
+  config     Interactive wizard over the router's own config.yml
+             (--print shows the models.yml block; --write splices it into omp)
+
+Global options:
+  --config <path>   Use a specific router config file
+  --help, -h        Show help
+  --version         Show version
+
+Command options:
+  stats    --days <n>  --json
+  models   --tier <trivial|simple|moderate|hard>  --limit <n>  --json
+  explain  --file <request.json>  --json          (reads stdin when --file is absent)
+  config   --print  --write  --path <models.yml>  --config <router-config.yml>
+
+Environment:
+  OPENROUTER_API_KEY   Required for completions; the catalog is readable without it.
+  AUTO_MODEL_ROUTER_HOME      Config and database directory (default ~/.auto-model-router)
+`;
+
+async function main(): Promise<number> {
+	const args = parseArgv(process.argv.slice(2));
+
+	if (args.flags.has("version")) {
+		const pkg: unknown = await Bun.file(join(import.meta.dir, "..", "package.json")).json();
+		const value =
+			typeof pkg === "object" && pkg !== null && "version" in pkg && typeof pkg.version === "string"
+				? pkg.version
+				: "unknown";
+		console.log(value);
+		return 0;
+	}
+	if (args.command === "") {
+		// No command is a usage question rather than an error when help was asked for.
+		process.stdout.write(USAGE);
+		return args.flags.has("help") ? 0 : 1;
+	}
+	if (args.flags.has("help")) {
+		process.stdout.write(USAGE);
+		return 0;
+	}
+
+	switch (args.command) {
+		case "stats":
+			await statsCommand(args);
+			return 0;
+		case "models":
+			await modelsCommand(args);
+			return 0;
+		case "explain":
+			await explainCommand(args);
+			return 0;
+		case "config":
+			await configCommand(args);
+			return 0;
+		default:
+			process.stderr.write(`unknown command "${args.command}"\n\n${USAGE}`);
+			return 1;
+	}
+}
+
+if (import.meta.main) {
+	try {
+		const code = await main();
+		if (code !== 0) process.exit(code);
+	} catch (err) {
+		process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+		process.exit(1);
+	}
+}

package/src/router/cache-control.ts

@@ -0,0 +1,66 @@
+/**
+ * Cache-breakpoint placement (Anthropic-style `cache_control: ephemeral`;
+ * OpenRouter translates these to OpenAI/Google cache primitives, so one
+ * mechanism covers every target). Returns message indices to mark.
+ */
+
+import type { CatalogModel } from "../catalog/types.ts";
+import type { RouterConfig } from "../config/types.ts";
+import { priceAt } from "../cost/forecast.ts";
+import { estimateTokens } from "../tokens/estimate.ts";
+import type { NormMessage, NormRequest } from "../wire/types.ts";
+
+export function planCacheBreakpoints(req: NormRequest, model: CatalogModel, cfg: RouterConfig): number[] {
+	if (!cfg.cache.injectBreakpoints) return [];
+	const promptTokens = estimateTokens(req.promptBytes, model.tokenizer, null);
+	// Small prompts cannot amortize cache-write cost.
+	if (promptTokens < cfg.cache.minPromptTokens) return [];
+	// A breakpoint on a model with no published cache-read price cannot pay for itself.
+	if (priceAt(model, Math.max(1, promptTokens)).cacheRead === undefined) return [];
+
+	const messages = req.messages;
+	const picks: number[] = [];
+
+	// 1. End of the last system message: the most stable, usually largest prefix.
+	for (let i = messages.length - 1; i >= 0; i--) {
+		const role = messages[i]?.role;
+		if (role === "system" || role === "developer") {
+			picks.push(i);
+			break;
+		}
+	}
+
+	// 2. End of the last message before the volatile tail — the newest
+	//    user-authored content, or the trailing tool-result run of an agent
+	//    loop. Caches everything the model has already seen, leaving only the
+	//    fresh tail uncached.
+	const tail = messages[messages.length - 1];
+	if (tail !== undefined) {
+		let pred: (m: NormMessage) => boolean;
+		if (tail.role === "user") pred = (m) => m.role === "user";
+		else if (tail.role === "tool") pred = (m) => m.role === "tool" || (m.role === "assistant" && m.toolCalls.length > 0);
+		// An assistant tail has no fresh human content; the whole history is prefix.
+		else pred = () => false;
+		let i = messages.length - 1;
+		while (i >= 0) {
+			const m = messages[i];
+			if (m === undefined || !pred(m)) break;
+			i--;
+		}
+		if (i >= 0) picks.push(i);
+	}
+
+	// 3. Stable prefix boundary at roughly 75% of history.
+	if (messages.length > 1) picks.push(Math.floor((messages.length - 1) * 0.75));
+
+	// Dedupe preserving priority order, cap, return ascending indices.
+	const seen = new Set<number>();
+	const out: number[] = [];
+	for (const i of picks) {
+		if (i < 0 || i >= messages.length || seen.has(i)) continue;
+		seen.add(i);
+		out.push(i);
+		if (out.length >= cfg.cache.maxBreakpoints) break;
+	}
+	return out.sort((a, b) => a - b);
+}

package/src/router/candidates.ts

@@ -0,0 +1,246 @@
+/**
+ * Candidate construction: hard capability filters over the catalog, then
+ * forecast + scoring for the survivors. The `rejected` array is what
+ * `auto-model-router explain` shows, so every drop records its precise reason.
+ */
+
+import type { CatalogModel, CatalogSnapshot } from "../catalog/types.ts";
+import type { QualityAxis, RouterConfig } from "../config/types.ts";
+import { forecast, priceAt } from "../cost/forecast.ts";
+import type { Ledger } from "../cost/types.ts";
+import type { NormRequest } from "../wire/types.ts";
+import { effectiveQualityFloor, tierPlanFor } from "./tier-plan.ts";
+import type { Candidate, Features, Rejection, TaskType, Tier } from "./types.ts";
+
+export interface BuildCandidatesArgs {
+	req: NormRequest;
+	features: Features;
+	tier: Tier;
+	/** Task type; its config selects the axis, quality floor, and image filter. */
+	task: TaskType;
+	snapshot: CatalogSnapshot;
+	ledger: Ledger | null;
+	cfg: RouterConfig;
+	expectedCompletionTokens: number;
+	/** Slug whose prompt cache is warm this turn; wins score ties. */
+	warmSlug: string | null;
+	/**
+	 * Tier rescue depth when the strict config excludes every available model.
+	 * 0 = strict (price ceiling + quality floor + trust bar all enforced).
+	 * Higher levels drop constraints in order: 1 removes price ceilings, 2 also
+	 * drops the quality floor, 3 also ignores the trust bar. Never lifts the
+	 * hard capability filters (tools/images/context) or the key-scoped allowlist.
+	 */
+	relaxLevel?: number;
+	/**
+	 * Slugs this turn must not select — the models that already failed on it.
+	 * Failover re-selects with the failed slug excluded so a retry lands on a
+	 * DIFFERENT model instead of re-issuing the one that just errored.
+	 */
+	excludeSlugs?: readonly string[];
+}
+
+/** Tiny glob: `*` matches any run of characters; everything else is literal. */
+function globToRe(glob: string): RegExp {
+	const escaped = glob.replace(/[.*+?^${}()|[\]\\]/g, (ch) => (ch === "*" ? ".*" : `\\${ch}`));
+	return new RegExp(`^${escaped}$`);
+}
+
+/**
+ * Quality fallback chain: score the preferred axis first, then the general
+ * intelligence index (the most widely published), then the remaining axis.
+ * A model absent on every axis is UNSCORED — never impute a score from price.
+ */
+const AXIS_FALLBACK: Record<QualityAxis, readonly [QualityAxis, QualityAxis, QualityAxis]> = {
+	coding: ["coding", "intelligence", "agentic"],
+	agentic: ["agentic", "intelligence", "coding"],
+	intelligence: ["intelligence", "coding", "agentic"],
+};
+
+function resolveQuality(model: CatalogModel, axis: QualityAxis): { score: number; axis: QualityAxis } | null {
+	for (const a of AXIS_FALLBACK[axis]) {
+		const v = model.quality[a];
+		if (v !== undefined) return { score: v, axis: a };
+	}
+	return null;
+}
+
+/** Neutral trust prior for models our ledger has never observed. */
+const UNMEASURED_TRUST = 0.9;
+
+export function buildCandidates(args: BuildCandidatesArgs): { candidates: Candidate[]; rejected: Rejection[] } {
+	const { req, features, tier, task, snapshot, ledger, cfg, expectedCompletionTokens, warmSlug, relaxLevel = 0 } = args;
+	// A Set only when non-empty: the common path allocates nothing.
+	const excluded = args.excludeSlugs === undefined || args.excludeSlugs.length === 0 ? null : new Set(args.excludeSlugs);
+	const tierCfg = cfg.tiers[tier];
+	const taskCfg = cfg.tasks[task];
+	const filters = cfg.filters;
+	const relaxPrice = relaxLevel >= 1;
+	const relaxQuality = relaxLevel >= 2;
+	const relaxTrust = relaxLevel >= 3;
+	const allowRes = filters.allow.map(globToRe);
+	const denyRes = filters.deny.map(globToRe);
+	const needTools = req.tools.length > 0 && filters.requireToolSupport;
+	const minContext = Math.ceil(features.promptTokens * filters.contextHeadroom) + expectedCompletionTokens;
+	// Task selects the quality axis and capability filters; the tier still
+	// bounds cost.
+	const effectiveAxis = taskCfg.axis;
+	// Two floors with different meanings, and only one of them may be relaxed:
+	//  - the TIER floor is an economic envelope tuned against the full catalog,
+	//    so when a guardrail narrows availability below it, relaxing to the
+	//    best available band is right (otherwise the tier is empty forever).
+	//  - the TASK floor is a capability requirement (vision needs a model that
+	//    can actually see), so adaptive relaxation must never lower it.
+	const taskFloor = taskCfg.minQuality ?? 0;
+	const adaptiveTierFloor = cfg.adaptiveTierFloors
+		? effectiveQualityFloor(tierCfg.minQuality, tier, effectiveAxis, tierPlanFor(snapshot, cfg))
+		: tierCfg.minQuality;
+	const qualityFloor = Math.max(taskFloor, adaptiveTierFloor);
+	const taskPins = taskCfg.prefer ?? [];
+	let images = 0;
+	if (req.hasImages) for (const m of req.messages) images += m.images;
+
+	const candidates: Candidate[] = [];
+	const rejected: Rejection[] = [];
+
+	for (const model of snapshot.models) {
+		const slug = model.slug;
+
+		// Failover exclusion comes first: a model that already failed this turn
+		// is not a candidate no matter how well it scores.
+		if (excluded !== null && excluded.has(slug)) {
+			rejected.push({ slug, reason: "failed_this_turn" });
+			continue;
+		}
+
+		// Hard-coded denials, before any user configuration. These slugs can
+		// never serve an interactive turn:
+		//  - "~vendor/model-latest": floating aliases whose identity changes
+		//    underneath us, poisoning ledger trust statistics.
+		//  - ":batch": asynchronous batch endpoints, unusable for streaming.
+		//  - "stealth/": cloaked models with no stable identity.
+		//  - "openrouter/": their meta-routers do our job at unknown cost.
+		if (slug.startsWith("~") || slug.endsWith(":batch") || slug.startsWith("stealth/") || model.author === "openrouter") {
+			rejected.push({ slug, reason: "denylisted", detail: "built-in deny: floating alias, batch endpoint, stealth, or meta-router" });
+			continue;
+		}
+		// A negative price is OpenRouter's unknown/dynamic sentinel (-1), never a discount.
+		if (model.price.prompt < 0 || model.price.completion < 0) {
+			rejected.push({ slug, reason: "denylisted", detail: "dynamic pricing sentinel" });
+			continue;
+		}
+		if (allowRes.length > 0 && !allowRes.some((re) => re.test(slug))) {
+			rejected.push({ slug, reason: "not_allowlisted" });
+			continue;
+		}
+		if (denyRes.some((re) => re.test(slug))) {
+			rejected.push({ slug, reason: "denylisted", detail: "filters.deny" });
+			continue;
+		}
+		if (model.isFree && !filters.includeFree) {
+			rejected.push({ slug, reason: "free_tier_excluded" });
+			continue;
+		}
+		if (needTools && !model.supportsTools) {
+			rejected.push({ slug, reason: "no_tool_support" });
+			continue;
+		}
+		if ((req.hasImages || taskCfg.requireImage === true) && !model.inputModalities.includes("image")) {
+			rejected.push({ slug, reason: "no_image_support" });
+			continue;
+		}
+		if (model.contextLength < minContext) {
+			rejected.push({ slug, reason: "context_too_small", detail: `window ${model.contextLength} < required ${minContext}` });
+			continue;
+		}
+
+		const pinned = tierCfg.pin.includes(slug) || taskPins.includes(slug);
+		const quality = resolveQuality(model, effectiveAxis);
+		if (!pinned && !relaxQuality && qualityFloor > 0) {
+			if (quality === null) {
+				rejected.push({ slug, reason: "below_quality_floor", detail: "no published quality score" });
+				continue;
+			}
+			if (quality.score < qualityFloor) {
+				rejected.push({ slug, reason: "below_quality_floor", detail: `${quality.score} < floor ${qualityFloor}` });
+				continue;
+			}
+		}
+
+		// Price ceilings at the ACTUAL prompt size: long-context overrides can
+		// push a model over the ceiling exactly when conversations get long.
+		// Catalog prices are per-token; ceilings are per million tokens.
+		const price = priceAt(model, Math.max(1, features.promptTokens));
+		if (!relaxPrice && tierCfg.maxInputPerMtok !== undefined && price.prompt * 1e6 > tierCfg.maxInputPerMtok) {
+			rejected.push({
+				slug,
+				reason: "over_price_ceiling",
+				detail: `input $${(price.prompt * 1e6).toFixed(2)}/Mtok > ceiling $${tierCfg.maxInputPerMtok}`,
+			});
+			continue;
+		}
+		if (!relaxPrice && tierCfg.maxOutputPerMtok !== undefined && price.completion * 1e6 > tierCfg.maxOutputPerMtok) {
+			rejected.push({
+				slug,
+				reason: "over_price_ceiling",
+				detail: `output $${(price.completion * 1e6).toFixed(2)}/Mtok > ceiling $${tierCfg.maxOutputPerMtok}`,
+			});
+			continue;
+		}
+
+		const trust =
+			ledger?.trust(slug, filters.trustScopedByHarness ? req.harnessId : undefined) ?? null;
+		if (!relaxTrust && trust !== null && trust.attempts >= filters.minTrustSamples && trust.successRate < filters.minTrust) {
+			rejected.push({
+				slug,
+				reason: "untrusted",
+				detail: `success ${trust.successRate.toFixed(2)} over ${trust.attempts} attempts < ${filters.minTrust}`,
+			});
+			continue;
+		}
+
+		const fc = forecast(model, {
+			promptTokens: features.promptTokens,
+			completionTokens: expectedCompletionTokens,
+			cacheHitRate: 0,
+			images,
+		});
+		const trustScore = trust !== null && trust.attempts > 0 ? trust.successRate : UNMEASURED_TRUST;
+		const qualityScore = quality?.score ?? 0;
+		// Shared scoring: trust converts flakiness into money — a model failing
+		// 20% of the time really costs ~25% more in retries. qualityExponent 0
+		// makes this "cheapest above the floor"; the floor does the quality work.
+		const effectiveUsd = fc.expectedUsd / Math.max(trustScore, 0.5);
+		const score = Math.pow(qualityScore / 100, tierCfg.qualityExponent) / Math.max(effectiveUsd, 1e-9);
+
+		const reasons: string[] = [
+			quality === null
+				? "unscored on every quality axis"
+				: `quality ${quality.score} on ${quality.axis}${quality.axis === effectiveAxis ? "" : ` (fallback from ${effectiveAxis})`}`,
+			trust === null || trust.attempts === 0
+				? `trust unmeasured: neutral prior ${UNMEASURED_TRUST}`
+				: `trust ${trustScore.toFixed(2)} over ${trust.attempts} attempts`,
+			`expected $${fc.expectedUsd.toFixed(6)}`,
+		];
+		if (pinned) reasons.push("pinned into tier");
+		candidates.push({ model, forecast: fc, qualityScore, trustScore, score, reasons });
+	}
+
+	candidates.sort((a, b) => {
+		const d = b.score - a.score;
+		if (d !== 0) return d;
+		// When the quality floor is relaxed, unscored models all score 0 and the
+		// lexical tie-break would pick alphabetically. Prefer the cheaper model
+		// first, then the warm slug, then lexical for determinism.
+		if (relaxQuality) {
+			const cd = a.forecast.expectedUsd - b.forecast.expectedUsd;
+			if (cd !== 0) return cd;
+		}
+		// Ties break toward the model already warm in this conversation, then
+		// lexically for determinism.
+		if (a.model.slug === warmSlug) return -1;
+		if (b.model.slug === warmSlug) return 1;
+		return a.model.slug < b.model.slug ? -1 : 1;
+	});
+	return { candidates, rejected };
+}