# Inferrail

> Inferrail's primary product, as of v0.2.0, is 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 ships, unchanged, the original open-source,
> self-hosted, OpenAI-compatible gateway that measures the cost of every
> LLM request and attributes it to the customer, workflow, or task that
> drove it — without persisting the prompt or response in its local
> receipt/telemetry records. Point your app's OpenAI client at Inferrail
> instead of directly at your provider, and every call produces a
> payload-free economic receipt: verified pricing, measured token usage,
> and whatever business attribution you attach. Receipts sharing one
> attribution tag can be rolled up into a single task-level transaction
> (`inferrail transaction <task-id>`), including via an ambient
> `inferrail.track_task(...)` helper that tags nested agent calls
> automatically. Apache-2.0 licensed. Self-hosted with zero dependency on
> any Inferrail-operated service. 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` 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.

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