inferrail: Instructions file for Claude Code

Inferrail — Agent Context

Inferrail is an open inference control plane: an OpenAI- and Anthropic-compatible gateway that sits between an application and the model providers it calls, plus a self-hosted local receipt/cost-attribution substrate. As of v0.2.0, Inferrail also ships a second, separate product on that same substrate: AP invoice-exception recovery — for one eligible invoice-extraction exception, decide whether it gets one permitted machine retry (with its own prospective cost authorization) or the customer's established human-review path, execute it, and record the resulting cost and outcome. AP is fully isolated from the gateway and from the hosted, testnet-only Work Economics/Economic Authority capabilities (own module, own storage, no shared code path) — see docs/capabilities/ap-invoice-exception-recovery.md for its full contract. See docs/PRODUCT.md for exact current scope (the single authoritative source — do not restate scope claims here that could drift from it) and docs/ARCHITECTURE.md for how the gateway is built.

Before major feature work, read

• docs/PRODUCT.md — authoritative source for exact current scope: what works, what's explicitly not supported yet
• docs/ARCHITECTURE.md — package layout, request lifecycle, and the boundaries (provider, routing, telemetry, data-plane/control-plane) that keep the codebase easy to extend
• docs/PRINCIPLES.md — the durable engineering principles behind this project
• docs/adr/ — architecture decision records for specific structural choices

Before implementing something substantial, ask

1. Which problem does this change solve?
2. Does it match a principle in docs/PRINCIPLES.md, or does it conflict with one?
3. Is there a smaller implementation?
4. Does docs/PRODUCT.md need to change alongside the code, so scope stays accurate?
5. What test proves this works?

Engineering rules

• Exact current scope must match the code. If a feature ships or a non-goal changes, update docs/PRODUCT.md in the same change.
• No prompt/response payload persistence in telemetry by default — this is a schema-level guarantee, not a runtime flag.
• No secret or silent telemetry — nothing leaves the machine unless a sink is explicitly configured to do that, and it must be documented.
• No fabricated metrics. Values that can't be measured trustworthily (cost, time-to-first-token, etc.) stay null — never estimated or guessed.
• The OSS data plane must keep working with zero dependency on any Inferrail-operated service.
• Prefer deterministic, testable behavior — keep the core engine independent of the web framework so it can be tested without an HTTP server.
• Keep the hot request-execution path small; avoid unnecessary dependencies and speculative complexity.
• Clearly distinguish shipped features from future work — a missing capability is a documented non-goal, not a silent gap.