SporeLabs Drop-in NOW

Status: Active launch contract (2026-08-11). Canonical product truth: SPORELABS_SPECIFICATION.md wins on any product conflict. This file is the implementation contract for the drop-in path: what customers experience, what the backend must support, and the merge gates before users send real traffic. Supersedes SPORELABS_DROPIN_COMPAT_SPEC.md (surface fidelity alone).

0. Promise (non-negotiable)

Point the app at SporeLabs. It keeps working like a frontier API. The bill falls only when we have proven a cheaper equal on their traffic.

Customers will forgive higher inference cost early. They will not forgive a silent quality drop. When unsure, do not cut over.

Phasing: §0 is the end state; §9 splits what is required to start production (OpenAI + Kimi + eval) from hardening (Anthropic surface, atomic settle lock, full verifier).

1. Golden path (customer does not think)

1. Paste one line (base_url + key) into their coding agent — OpenAI or Anthropic SDK.
2. Fund the prepaid wallet.
3. Omit model (or send auto) → Kimi K3 via OpenRouter until a cheaper equal earns live for that work. Name a model → that model, every time.
4. App behavior matches a direct frontier call (stream, tools, JSON, errors).
5. Portal / MCP show completed work in past tense when we move spend (“We proved X equals Opus on your traffic. −$N/mo.”).
6. They never operate a router, name projects, or pick a key mode. We infer jobs from traffic. Higher early cost is expected and honest.

Copy (use verbatim)

Omit / auto (recommended):

Starts on Kimi K3. We only move traffic when a cheaper model matches on your traffic.

Named model:

We’ll use this model for this call. We’ll still measure cheaper options on the same work and show you what we’d change — we won’t switch this request.

2. What “works like OpenRouter NOW” means

OpenRouter-like usage hook, not OpenRouter clone as the product:

Differentiation remains: we do the optimization work on their traffic and prove it. Upstream OpenRouter is plumbing for fidelity and the Kimi quality floor.

3. Request support matrix

3.1 OpenAI surface — POST /v1/chat/completions, GET /v1/models

3.2 Anthropic surface — POST /v1/messages, GET /v1/models

GET /v1/models is shared by path. Mount Anthropic router before OpenAI so its header-dispatching handler owns the route (x-api-key → Anthropic shape, Bearer → OpenAI shape). Regression test required.

3.3 Acceptance (fail-closed)

Every row above maps to automated tests and to scripts/verify_dropin.py. A change ships only with a recorded green verifier run against the deployed surface (§8).

4. Upstream and billing

4.1 Upstream router (thin)

Customer traffic never sees Modal URLs. Accounts app (Lambda / same-origin /api/*) is the only customer door. Modal stays GPUs only.

4.2 Auto incumbent (frozen)

Platform default for omitted / auto requests is this incumbent — not starter.

4.3 Pass-through metering (no markup)

• Debit the wallet in millicents for our real spend.
• Prefer OpenRouter-reported cost on the response / final stream usage when present.
• If cost is missing: fail-closed estimate from tokens × a maintained OpenRouter price table for that model id — never skip the debit.
• Owned-adapter traffic continues to use catalog class rates (products.yaml S/M/L) until those adapters also have pass-through cost signals.
• *_cents fields remain display mirrors; never debit them directly.
• No SporeLabs markup on OpenRouter pass-through until an explicit human decision (canonical §15.1).

4.4 Empty wallet (SDK mapping)

402 is not used on drop-in SDK paths (stock OpenAI SDKs mishandle it). The only legitimate refusal for metered inference is an empty (or hard-capped) wallet.

4.5 OpenRouter spend float and caps

Pass-through means we pay OpenRouter and debit the wallet after. A funded account can fire Opus traffic faster than wallet debits + 429s can stop it, so launch-day hardening is not optional:

This is the one place “ship now” needs more machinery, not less: a customer who empties a funded wallet mid-day on Opus traffic must be stopped at the OpenRouter boundary, not only at the wallet.

5. Routing: request model only (no key mode, no projects)

5.1 Keys are auth, not policy

API keys authenticate and debit the wallet. They do not carry routing_mode or pinned_model. There is no Project entity. Wallet, patterns, eval cases, and intelligence.py stay account-scoped (one bill, one traffic brain).

Jobs and sub-work are inferred from traffic (extract_features / shape_hash / patterns). The customer does not name a project, task, or mode when they call.

5.2 Resolving model on a request

1. Authenticate the key (wallet, not routing prefs).
2. Extract features from the request (shape only).
3. If model is auto/omitted → resolve_route for that shape; fallback is the Kimi incumbent.
4. If model is an explicit id → serve it; still extract features and enqueue the loop.
5. Response model reports what actually ran.

Every call — auto or named — goes through features, audit, patterns, and eval. Named-model traffic teaches us the jobs; it does not opt out of the loop.

5.3 Auto vs named and the loop

Do not invent a key-level pin. A customer who wants Opus forever sends anthropic/claude-opus-4.6 (or the Anthropic-surface equivalent) on the request. A customer who wants us to pick omits model.

6. Prove-gate (quality floor)

Incumbent answers define “good.” For auto/omitted traffic that is Kimi K3 (or the current live model after a proven cutover). For named-model traffic, compare challengers against that model’s answers on the same inferred jobs — suggestions only.

6.1 Live reroute bar (NOW — stricter than early soft thresholds)

Platform-funded eval calls (billed=False for loop inference) stay as today: the customer is not charged for us proving a change.

6.2 Shadow before live

Request path never serves a shadow challenger. MODE_SHADOW records intent; only MODE_LIVE after eval_engine.run_comparison clears §6.1. One move in flight per account (intelligence.py).

6.3 Rudimentary NOW vs later

NOW: Kimi floor, OpenRouter fidelity, high-gate reroute to a small challenger catalog (cheaper OpenRouter models + owned adapters), suggestions when the request named a model, existing specialize machinery without blocking launch on train UX polish.

Later: richer challenger search, better specialization UX, optional markup, broader /v1/models listing if product asks.

7. Pipeline architecture (simple + correct)

7.1 One function

New module: platform/server/dropin_pipeline.py.

Order of operations (both surfaces call this — two envelopes, one guts):

1. Authenticate key (get_by_token).
2. request_id = uuid.
3. extract_features (shape only — never store content).
4. Resolve serve target (§5 + resolve_route).
5. Soft funds preflight (can_spend / ensure_funds_for_spend) using an estimate.
6. Upstream complete or stream (OpenRouter or owned origin).
7. Atomic settle (§7.2).
8. loop_queue.touch.
9. Return envelope-specific response (OpenAI or Anthropic).

openai_api.py / anthropic_api.py translate shapes only. Tests assert both call the same pipeline entrypoint (not merely shared _debit).

intelligence.py remains the only offline decider. The pipeline does not invent routing policy.

7.2 Atomic settle

Single settle path for stream and non-stream:

try:
    run upstream (stream or not)
finally:
    settle_once(request_id)  # debit + audit; idempotent

This closes fail-open revenue leaks from streaming disconnects.

The audit row remains shape-only. Separately, successful calls may enter a bounded owner-scoped eval reservoir (40 prompt/reply pairs per pattern, 30-day TTL, deletable with account audit data). That sample is the minimum production trace needed to replay held-out cases, prove a cheaper equal, and train only that account's specialist. Materialized eval cases and run results carry the same TTL and are deleted with the reservoir; this is not an unbounded request log.

7.3 Diagram

Client (OpenAI or Anthropic SDK)
        │
        ▼
accounts_app (same-origin /api)
        │
        ▼
dropin_pipeline ──► OpenRouter (frontier) ──┐
        │                                    ├──► atomic settle (millicents)
        └──────────► Modal origin (owned) ───┘
        │
        ├──► call_event_store + loop_queue
        ▼
envelope (openai_compat | anthropic_compat)

8. Verifier and merge gate

8.1 scripts/verify_dropin.py

Fail-closed SDK smoke against a base URL + key:

1. OpenAI non-stream completion
2. OpenAI stream (≥2 content chunks; first-byte meaningfully early)
3. OpenAI tools + tool_choice
4. OpenAI JSON mode
5. Anthropic /v1/messages non-stream
6. Anthropic SSE grammar order
7. Anthropic tool_use round-trip
8. Empty / bad key error parity
9. Portal wallet display: after a completion, GET /api/account returns a wallet balance that fell by exactly the pass-through debit (no markup). Compare in millicents precision.
10. Portal /v1/models list matches the minimal list served by the pipeline (auto, Kimi incumbent, owned adapters). No stale models, no full OpenRouter index leak.
11. Agent auto-mode: omit model → serves the Kimi incumbent (response model field = incumbent).
12. Agent named-mode: send a named model → response model field matches exactly (never swapped).
13. Agent /v1/models includes auto + Kimi + owned (mirrors the portal list — verifies a single pipeline serves both surfaces).

Exit 1 on any failure. Per-check PASS/FAIL table.

8.2 Merge / ship gate

A drop-in change is not done until:

1. Unit/pipeline tests green (including settle-on-disconnect, /v1/models dispatch, shared pipeline entrypoint).
2. verify_dropin.py exit 0 against local stack and deployed surface.
3. Canonical + this doc agree (no 402-vs-429 contradiction, Kimi default, pass-through).
4. Portal/agent smoke: portal wallet reflects the exact pass-through debit after a completion (read account via GET /api/account, compare before/after wallet_balance_millicents); agent auto → Kimi, named → honored, models list = pipeline list.

No “verified by inspection.”

8.3 Launch-phase gate

Real traffic is gated on the Launch surface (§9.1) only; the Anthropic surface and the full verifier are hardening, landed as fast-follow.

9. Launch phasing

Each phase is independently shippable. Do not sequence Anthropic before real OpenAI traffic — collecting the first 20 eval cases is time-bound and only OpenAI traffic starts the clock.

9.1 Launch (production with real users)

Ship this and only this first. Everything required to route real requests and begin evaluations:

Launch settle may be best-effort debit + audit, not the idempotent Dynamo lock. The lock (§7.2) lands in Hardening. A missed/disconnected debit at launch is a platform loss, not a customer double-charge; that is an acceptable launch risk and strictly better than blocking traffic.

9.2 Hardening (fast-follow, parallel-safe)

10. Out of scope / later

• SporeLabs markup on pass-through
• Mega public catalog as homepage
• Project objects above keys
• Per-key routing_mode / pinned_model
• DIY train-tier shopping
• Weakening the prove-gate for faster savings
• Parallel intelligence deciders
• Exposing Modal or OpenRouter credentials to the browser

11. Implementation map

One shared platform/server/dropin_pipeline.py; OpenAI/Anthropic envelopes translate shapes only; Anthropic router mounts before OpenAI; settle = millicents debit + call_event_store + settle lock; verifier = scripts/verify_dropin.py. Full file map lives in the repo's AGENTS.md (Quick orientation).

12. Success criteria (“users can start NOW”)

12.1 Launch (production)

• [ ] OpenAI SDK → omit model → Kimi-quality completions with real streaming
• [ ] Named model on the request is honored; that call is never silently swapped
• [ ] Wallet falls by exact upstream spend (no markup)
• [ ] OpenRouter-side spend cap in place (§4.5) before real traffic
• [ ] Every call feeds loop_queue; cases begin accumulating toward the §6.1 gate
• [ ] Empty wallet → OpenAI 429 (no 402 on SDK paths)

12.2 Hardening (fast-follow)

• [ ] Anthropic /v1/messages works (stream, tools, grammar order) over the shared pipeline
• [ ] No live cheaper route on auto traffic without clearing §6.1 on their cases
• [ ] Disconnect / stream errors never skip debit; retries never double-debit
• [ ] verify_dropin.py green on deployed surface

Last updated: 2026-08-12.