Inferrail

Saiba quanto custa o trabalho da sua IA.
Sem guardar o que ela disse.

O Inferrail é um gateway que você mesmo executa e que rastreia o uso de tokens e o custo estimado de LLM por cliente, fluxo de trabalho ou tarefa para seus endpoints compatíveis com OpenAI e Anthropic.

Experimente localmente · Como funciona · Privacidade · Integrações · MCP · Status · Documentação

Código aberto sob Apache-2.0. Prévia para desenvolvedores: os recursos abaixo estão implementados e testados, mas os sinalizadores de CLI, o formato de configuração e os campos de recibo podem mudar antes da versão 1.0.

Limite de privacidade

Para cada solicitação compatível, o gateway grava um recibo em um arquivo local. Este é um recibo real da demonstração offline abaixo.

Exemplo de recibo: dados sintéticos de demonstração, abreviados.

{
  "receipt_id": "ir_4090e812f2ba4d3680e7",
  "route": "default",
  "provider": "demo",
  "model": "demo-small",
  "status": "success",
  "prompt_tokens": 812,
  "completion_tokens": 143,
  "pricing": {
    "input_usd_per_million": "0.20",
    "output_usd_per_million": "0.80",
    "source": "DEMO — a made-up round number, not a real provider price",
    "verified_date": "2026-09-26"
  },
  "estimated_cost_usd": "0.000277",
  "attributes": {"customer": "acme", "workflow": "contract-review", "work_id": "work-contract-1"}
}

Omitidos aqui: request_id, timestamp, total_latency_ms, retry_count. Lista completa de campos: receipts/schema.py.

O que acontece com sua chave e seu conteúdo (autohospedado):

• Seu processo de gateway lê a chave do provedor do próprio ambiente e envia solicitações ao provedor que você configurar.
• Ele processa prompts e respostas em memória para encaminhá-los. O provedor ainda recebe o conteúdo da sua solicitação, sob suas próprias políticas.
• Os recibos registram uso, evidência de custo, status, tempo e a atribuição que você fornecer. O caminho do recibo não copia os corpos das mensagens.
• As tags de atribuição são armazenadas exatamente como enviadas. Use identificadores e mantenha segredos e conteúdo de mensagens fora delas.
• Eventos locais de telemetria são metadados operacionais. O beacon de uso opcional é separado e não envia nada, a menos que você configure um endpoint de coletor (detalhes).
• O teste hospedado é um limite diferente: se você adicionar uma chave real lá, o processo hospedado mantém essa chave e lida com seu tráfego.

Verifique você mesmo: manipuladores de solicitação · mecanismos de execução (OpenAI, Anthropic) · adaptadores de provedor (OpenAI, Anthropic) · construtor de recibos · destinos (JSONL, SQLite) · testes canários (OpenAI, streaming e telemetria, Anthropic).

inferrail verify-payload-free imprime o esquema de recibo ao vivo e verifica que nenhum campo é nomeado por conteúdo de mensagem. É uma verificação de esquema, não uma auditoria de segurança: não pode inspecionar valores armazenados, logs ou seu provedor.

Experimente offline

Requer Python 3.11+. A instalação baixa o pacote e suas dependências; depois disso, a demonstração é executada offline.

python -m pip install inferrail
inferrail demo
inferrail report --by customer --receipts ./inferrail-demo-receipts.jsonl

A demonstração não precisa de chave de API, não faz chamadas de rede e não gera cobranças do provedor. Ela envia seis solicitações roteirizadas pelo mecanismo real com um provedor falso e preços inventados rotulados como DEMO, e então grava ./inferrail-demo-receipts.jsonl no seu diretório atual.

python3 -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
python -m pip install inferrail

_{Execução real de inferrail demo 0.4.3 com rede bloqueada. Dados sintéticos, não cobrança do provedor. Imagem estática · saída capturada · como foi feita}

No relatório, acme mostra uma solicitação com custo desconhecido: o modelo de prévia da demonstração não tem preço registrado, então seu recibo tem "pricing": null e "estimated_cost_usd": null. A coluna COST (USD) soma apenas os custos conhecidos. Não é uma conta completa quando a contagem de desconhecidos é maior que zero.

Envie uma solicitação real

Isso usa sua própria conta do provedor, que cobra você normalmente. Execute o gateway em um terminal, com a chave definida nesse terminal, porque o gateway é o processo que chama o provedor:

export OPENAI_API_KEY=...        # and/or ANTHROPIC_API_KEY=...
inferrail serve --quickstart

Depois aponte seu cliente para ele a partir de outro terminal ou do seu aplicativo:

from openai import OpenAI

client = OpenAI(base_url="http://127.0.0.1:8000/v1", api_key="not-needed")
client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Say hello in five words."}],
    extra_headers={"X-Inferrail-Attribute-Customer": "acme"},
)

import anthropic

# No /v1 here: the Anthropic SDK adds /v1/messages itself.
client = anthropic.Anthropic(base_url="http://127.0.0.1:8000", api_key="not-needed")
client.messages.create(
    model="claude-haiku-4-5-20251001",
    max_tokens=256,
    messages=[{"role": "user", "content": "Say hello in five words."}],
)

O api_key do cliente é um espaço reservado; o gateway o ignora, a menos que você defina INFERRAIL_GATEWAY_TOKEN. Então execute inferrail report --by customer no diretório do gateway. O gateway escuta apenas em 127.0.0.1 por padrão. Defina INFERRAIL_GATEWAY_TOKEN antes de expô-lo em qualquer outro lugar (SECURITY.md).

Como funciona

Cada solicitação é roteada por model para um provedor configurado (roteamento), executada com novas tentativas e medida. O custo é calculado apenas quando o provedor relata uso e um preço verificado está registrado; caso contrário, permanece null, nunca um $0 adivinhado (calculadora). Arquitetura: docs/ARCHITECTURE.md. Fonte do diagrama: scripts/render_flow_svg.py.

Integrações

Suportados hoje: POST /v1/chat/completions (compatível com OpenAI, com streaming e chamadas de ferramentas), POST /v1/messages (compatível com Anthropic, com streaming e uso de ferramentas) e GET /health. Qualquer cliente ou framework que permita definir uma URL base e envie esses formatos pode usar o gateway. Atribuição, agrupamento de trabalho, exemplos de frameworks e configuração de MCP estão em docs/integrations.md.

Agentes de voz. O Inferrail não tem suporte nativo a voz. Uma pilha de voz pode rotear seu estágio de LLM de texto pelo Inferrail se esse estágio aceitar uma URL base personalizada compatível com OpenAI ou Anthropic e enviar um formato de solicitação compatível. Apenas os tokens e o custo desse estágio são registrados. Áudio, fala para texto, texto para fala, a API Realtime e o custo total da chamada não são cobertos, e nenhum framework de voz foi testado por este projeto (detalhes).

MCP

O Inferrail inclui um servidor MCP com duas ferramentas somente leitura, para que um agente possa perguntar quanto custou o trabalho de IA. As ferramentas leem seu arquivo local de recibos. Elas não executam inferência, gastam orçamento do provedor, alteram configuração ou gravam qualquer arquivo. Os recibos do Inferrail armazenam metadados de uso e custo sem persistir corpos de prompts ou respostas, então as ferramentas não têm nenhum para retornar. (O gateway em si ainda lida com prompts e respostas em memória enquanto os encaminha ao provedor; veja Limite de privacidade.)

Não há ferramentas separadas de cliente, fluxo de trabalho ou trabalho. get_spend agrupa por quaisquer tags que suas solicitações carreguem, então agrupar por customer, workflow ou work_id (uma unidade de trabalho marcado, como um trabalho) apenas cobre solicitações que foram enviadas com essa tag (atribuição).

O servidor fala stdio e é iniciado pelo seu cliente MCP:

uvx inferrail mcp        # or: pip install inferrail && inferrail mcp

Configuração do cliente (Claude Desktop, Cursor e outros clientes que usam mcpServers; o VS Code usa a mesma entrada sob servers):

{
  "mcpServers": {
    "inferrail": {
      "command": "uvx",
      "args": ["inferrail", "mcp"],
      "env": {
        "INFERRAIL_RECEIPTS_PATH": "/absolute/path/to/inferrail-receipts.jsonl"
      }
    }
  }
}

Claude Code: claude mcp add inferrail -e INFERRAIL_RECEIPTS_PATH=/absolute/path/to/inferrail-receipts.jsonl -- uvx inferrail mcp

Defina INFERRAIL_RECEIPTS_PATH para o seu arquivo de recibos. Os clientes iniciam o servidor a partir do próprio diretório de trabalho, então o padrão ./inferrail-receipts.jsonl raramente é o lugar certo. Para serve --app-mode, aponte-o para receipts.db no diretório de dados do Inferrail (~/.local/share/inferrail no Linux, ~/Library/Application Support/inferrail no macOS, %APPDATA%\inferrail no Windows).

Então pergunte, por exemplo: "Quanto custou o trabalho marcado como contract_review_42?" Se suas solicitações carregaram work_id=contract_review_42, o agente chama get_spend com by: "work_id" e lê esse grupo. Contrato completo da ferramenta: inferrail-mcp/README.md.

Status

O Inferrail não contabiliza todos os gastos em uma conta de provedor, apenas as solicitações compatíveis que passam por um gateway em execução. Escopo completo e não objetivos: docs/PRODUCT.md.

Documentação

• docs/integrations.md: clientes, atribuição, rastreamento de trabalho, voz, MCP
• docs/self-hosting.md: instalação, configuração, armazenamento, orçamentos, painel
• docs/PRODUCT.md: escopo atual exato
• docs/ARCHITECTURE.md e docs/adr/: como e por que foi construído assim
• docs/privacy/usage-ping.md: o beacon de uso
• openapi.json, config.schema.json, llms.txt: referências legíveis por máquina

Feedback, segurança, licença

• Perguntas e bugs: GitHub issues.
• Vulnerabilidades de segurança ou privacidade: reporte em particular, conforme descrito em SECURITY.md.
• Contribuição: CONTRIBUTING.md. pytest não precisa de chave de API ou rede.
• Licença: Apache-2.0.