# Inferrail

> Inferrail's primary product is a self-hosted, OpenAI- and
> Anthropic-compatible LLM gateway that turns every request into a
> payload-free, attributable cost receipt: know what your AI work
> costs, without keeping what it said. Point your app's OpenAI client
> (or the Anthropic SDK, including Claude Code, via a genuine, separate
> `/v1/messages` passthrough — real streaming, tool use, priced via an
> independently-verified catalog, see
> [docs/adr/0014](https://github.com/domondi1/inferrail/blob/main/docs/adr/0014-anthropic-messages-passthrough.md))
> at Inferrail instead of directly at the provider, and every call
> produces a receipt with verified pricing, measured token usage, and
> whatever business attribution you attach, not the prompt or
> response itself. The receipt schema has no field for message content
> (`inferrail verify-payload-free` lists the fields and checks their
> names), and canary tests check that message bodies never reach a
> receipt. Attribution values are stored as sent.
> The provider itself still receives the real prompt, exactly as it
> would without Inferrail in the path — this is a receipt-storage
> guarantee, not a network privacy boundary. `pip install inferrail &&
> inferrail serve --quickstart` for a two-command start; `inferrail
> demo` for a zero-key, offline walkthrough of the same real receipt
> pipeline. Receipts sharing one `work_id` roll up into a single
> work-level economic view (`inferrail work <work_id>`, or
> `inferrail transaction <task-id>` for the legacy per-task rollup),
> including via an ambient `inferrail.track_task(...)` helper that tags
> nested agent calls automatically. Spend caps
> (`inferrail budget set`, or `serve --daily-budget-usd`) block a
> request with HTTP 402 before any provider is contacted once a
> configured limit would be exceeded. Apache-2.0 licensed. Self-hosted
> with zero dependency on any Inferrail-operated service.
>
> Built on that same receipt substrate, Inferrail also ships AP
> invoice-exception recovery: for one eligible invoice-extraction
> exception, it decides whether to make one permitted machine retry or
> send it to your established human-review path, executes the retry
> through a supported integration (your own adapter, or the bundled
> OpenAI reference adapter), and records the resulting cost and outcome
> — durably, idempotently, with invoice content and provider
> credentials staying in your own process. `pip install inferrail &&
> inferrail ap demo` for a zero-key, fixture-based walkthrough. Full
> contract:
> [docs/capabilities/ap-invoice-exception-recovery.md](https://github.com/domondi1/inferrail/blob/main/docs/capabilities/ap-invoice-exception-recovery.md).
> Inferrail also operates two experimental, Base-Sepolia-testnet-only
> hosted capabilities (below) that extend this same measurement toward
> capabilities a machine buyer can discover and purchase directly.

## Docs

- [AP invoice-exception recovery](https://github.com/domondi1/inferrail/blob/main/docs/capabilities/ap-invoice-exception-recovery.md): supported failure types, retry method, validation contract, human-review handoff, versioned policy config, hosted API
- [README](https://github.com/domondi1/inferrail/blob/main/README.md): quickstart, install, configuration, privacy verification
- [Product scope](https://github.com/domondi1/inferrail/blob/main/docs/PRODUCT.md): exact current scope — what works, explicit non-goals
- [Architecture](https://github.com/domondi1/inferrail/blob/main/docs/ARCHITECTURE.md): package layout, request lifecycle
- [Engineering principles](https://github.com/domondi1/inferrail/blob/main/docs/PRINCIPLES.md): the durable rules behind the design
- [Architecture decision records](https://github.com/domondi1/inferrail/tree/main/docs/adr): why specific structural choices were made

## API

- [OpenAPI 3.1 specification](https://github.com/domondi1/inferrail/blob/main/openapi.json): the full `/v1/chat/completions`, `/v1/messages`, and `/health` contract, generated from the live app
- [Config JSON Schema](https://github.com/domondi1/inferrail/blob/main/config.schema.json): generate a valid `inferrail.yaml` without guessing
- [Error codes](https://github.com/domondi1/inferrail/blob/main/ERRORS.md): every stable `INFERRAIL_E###` code with a remediation hint

## Agent tools

- [inferrail-mcp](https://github.com/domondi1/inferrail/tree/main/inferrail-mcp): MCP server (stdio) exposing `get_spend` (query attributed cost) and `get_health` (gateway reachability + last receipt) — read-only, cannot execute inference or spend provider budget

## Examples

- [AP invoice-exception recovery examples](https://github.com/domondi1/inferrail/tree/main/examples/ap_invoice_exception_recovery): fixture-based demo, real-provider (OpenAI) demo, a custom-integration example (your own extraction pipeline + review queue, threading decision → retry → recovered data or review → outcome → report end to end), and a hosted-API client example (local authorization/execution against the hosted decision API, keeping invoice content and credentials out of every hosted call)
- [Basic chat request](https://github.com/domondi1/inferrail/blob/main/examples/basic_chat_request.py)
- [Work Economics purchase](https://github.com/domondi1/inferrail/blob/main/examples/work_economics_purchase.py): a complete, standalone x402 buyer — no Inferrail account required

## Hosted services

- [Inferrail AP Exceptions](https://github.com/domondi1/inferrail/blob/main/hosted/ap_exceptions/README.md): the optional hosted counterpart to AP invoice-exception recovery — authenticated decision/persistence/reporting over HTTP, isolated per API key. Not paid/x402-gated. Never executes a retry itself. `POST /v1/sandbox` (no auth) self-issues a short-lived, isolated, synthetic-data-only sandbox key with no account needed — see the README's "Try it yourself" walkthrough.

## Paid capabilities

Both capabilities below are experimental and Base Sepolia testnet only.
Neither controls external wallets, providers, or network spending.

- [Inferrail Work Economics](https://github.com/domondi1/inferrail/blob/main/docs/capabilities/work-economics.md): given caller-declared economic events for a unit of AI work, returns a normalized cost summary and a commercial receipt. Paid via the [x402](https://www.x402.org/) protocol — any x402-capable agent can buy it with its own wallet. **Base Sepolia testnet only right now, not mainnet.** Canonical endpoint: `https://work.tryinferrail.com` — machine-readable manifest (price, schema, `pay_to` address) served unauthenticated at [`https://work.tryinferrail.com/manifest`](https://work.tryinferrail.com/manifest); human-readable overview at [tryinferrail.com/work-economics](https://tryinferrail.com/work-economics/).
- [Inferrail Economic Authority](https://github.com/domondi1/inferrail/blob/main/docs/capabilities/economic-authority.md): explores voluntary coordination of a caller-declared spending boundary between agents. The boundary is caller-declared and the ledger is cooperative; Inferrail records and coordinates it within its own service and does not control external wallets, providers, or network spending; this is not real-world spend enforcement. Operated over the [A2A protocol](https://a2a-protocol.org/) (`reserve`/`grant`/`consume`/`settle`/`status`/`revoke`), with an optional x402-gated `POST /sessions` for buying a new root capability when a given deployment has it enabled. **Base Sepolia testnet only, not mainnet.** Canonical endpoint: `https://authority.tryinferrail.com` — Agent Card served unauthenticated at [`https://authority.tryinferrail.com/.well-known/agent-card.json`](https://authority.tryinferrail.com/.well-known/agent-card.json), which declares whether this specific deployment currently has session purchase enabled.

## Optional

- [Security policy](https://github.com/domondi1/inferrail/blob/main/SECURITY.md)
- [Contributing](https://github.com/domondi1/inferrail/blob/main/CONTRIBUTING.md)
