# Firstpass

> Firstpass routes every LLM request to the cheapest model that *provably* passes your quality gate — it runs a real check (tests, typecheck, schema, or a fresh-context judge) on the actual output and escalates one ladder rung only on failure, serving the first output that passes. Every decision is a tamper-evident audit trace. Proof over prediction; built agent-first for agent fleets.

Firstpass is **agent-first by construction**: its primary user is an agent. Adoption is a one-env-var `base_url` swap on an OpenAI/Anthropic-wire-compatible proxy; offboarding is unsetting it. Every surface is machine-first — declarative config, structured JSON traces with a re-derivable hash chain, typed verdicts, structured errors, an HTTP feedback API, a `GET /v1/capabilities` discovery endpoint, and an optional MCP server.

What is genuinely new (the cascade mechanism itself is prior art in the model-cascade literature): (1) tamper-evident audit of every routing decision + gate verdict, with a durable never-drop receipts mode, (2) an outcome-feedback API that calibrates the serve threshold from real downstream results — split-conformal or Learn-then-Test (`firstpass calibrate --method ltt`), tracked live under drift by adaptive conformal, (3) zero-retrain model onboarding (add a rung to the ladder; predictive routers all need retraining), (4) predict-to-start/verify-to-serve — a start-rung bandit (deterministic UCB1, or discounted Thompson sampling that logs a real propensity per decision) picks where the ladder starts while the gate still decides what ships (prediction errors cost latency, never correctness), plus a speculative-deferral band that prefetches the next rung only when the outcome is genuinely uncertain, (5) a self-consistency gate (k-sample agreement) for measured confidence on the actual output, with per-gate fail-open/fail-closed abstain policy and gate cost on every receipt, and (6) offline policy replay (`firstpass ope`) — rehearse a candidate ladder or start-rung against logged traffic with IPS/SNIPS/DR estimates and bootstrap CIs before enforcing it. Both wire dialects are inbound endpoints (`/v1/messages`, `/v1/chat/completions`); `firstpass savings` / `firstpass evals` (and MCP tools get_savings/get_evals) report measured value from the deployment's own receipts.

## Docs
- [README](README.md): product pitch, the receipt (audit trace), proof-vs-prediction comparison, install, roadmap.
- [SPEC](SPEC.md): founding spec v0.1 — the source of truth. Positioning (§0), prior art & novelty (§0.1), agent-first tenet (§0.2), architecture (§7), gate framework (§8), trace/feature schema (§9), distribution, milestones (§16).
- [AGENTS.md](AGENTS.md): agent/contributor onboarding — repo layout, build/test/lint gates, the invariants that must not regress.

## Contract (crates/firstpass-core)
- Trace schema (SPEC §9.1): structured JSON audit record; serde field names are the wire/audit contract.
- Feature vector (SPEC §9.2): deterministic, versioned (`features@vN`); privacy-preserving (salted repo fingerprint, no raw prompts).
- Hash chain: append-only, re-derivable by an external auditor from the stored records alone.
- Config (SPEC §8.4): declarative routing — routes, ladders, gates, budgets, escalation.

## Distribution
- Single static binary, no runtime dependencies. Install in seconds: `curl | sh` (recommended), `pip install firstpass` / `uvx --from firstpass firstpass-proxy`, `brew install dshakes/tap/firstpass-proxy`, `docker run ghcr.io/dshakes/firstpass`, or `cargo install --git` (needs a Rust toolchain). npm and crates.io publishing are wired but not yet live. Upgrade in place with `firstpass-proxy-update`.
- Multi-provider: Anthropic, OpenAI, Google, and any OpenAI-compatible endpoint (hosted aggregators or local models).
- BYOK (bring your own keys); zero token markup; no lock-in at the data plane.