# 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, 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

- [Inferrail Hosted](https://inferrail-cost-gateway.onrender.com/hosted/llms.txt): the per-run budget gateway as a hosted service, shared by every agent and machine in a workspace; workspace creation, headers, errors and retries, pricing (250 runs/month free, experimental), and buying credits in USDC over x402
- [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, run with `inferrail mcp` or `uvx inferrail mcp`; registry name `io.github.domondi1/inferrail`) 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
- [Agent economy: one job, one budget](https://github.com/domondi1/inferrail/tree/main/examples/agent_economy): experimental, self-hosted. One job budget covers model calls and x402 purchases; sub-agents get bounded shares; a purchase that doesn't fit is refused before it's signed; the payer key stays out of the agent. Runs locally with a simulated chain (`python examples/agent_economy/demo.py`); no mainnet. TypeScript: [`withJobBudgets`](https://github.com/domondi1/inferrail/tree/main/examples/agent_economy/typescript) puts an existing `@x402/core` / `@x402/fetch` client under per-job and per-sub-agent budgets. Agent instructions: [SKILL.md](https://github.com/domondi1/inferrail/blob/main/examples/agent_economy/SKILL.md)

## 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 Job-Safe Web Search: a prepared x402 v2 exact-payment search endpoint with durable request identity, job budgets, cache reuse, and economic receipts. Not deployed or accepting payment. The only tested code path is intended for Base Sepolia. Base mainnet remains disabled pending explicit approval and written supplier rights. See docs/capabilities/job-safe-search.md.

- [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)
