OrcaRouter Lite

Roteador LLM self-hosted com rede de segurança gerenciada. Compatível com OpenAI. BYOK. Workspace único. Streaming. model="auto".

model="auto" absorve uma falha de provedor em tempo real — sem mudar o código. Como gravar: DEMO.md.

Idiomas

• English
• 日本語
• 中文
• 한국어
• Deutsch
• Français
• Español
• Italiano
• Русский
• Português
• Tiếng Việt
• हिन्दी

OrcaRouter Lite é a edição open source single-workspace do OrcaRouter. Rode no seu laptop, embarque no seu produto, ou use diretamente o api.orcarouter.ai hospedado para a long tail de modelos cujas chaves você não quer gerenciar.

Por que nós? LiteLLM é uma biblioteca; OpenRouter é closed-source e hospedado; Ollama é apenas local. Nós somos o servidor self-hosted com fallback gerenciado — uma frase que nenhum deles pode dizer.

Quickstart de 60 segundos

Duas formas de usar o OrcaRouter:

Caminho A — Self-hosted (BYOK)

Rode o Lite na sua própria máquina; traga suas próprias chaves de provider.

git clone https://github.com/Continuum-AI-Corp/OrcaRouter-Lite.git
cd OrcaRouter-Lite
cp .env.example .env
# adicione pelo menos uma: OPENAI_API_KEY=sk-...  (ou ORCAROUTER_API_KEY=...)

docker compose up
# logs: ✓ orcarouter-lite ready. API key: sk-orca-abc123...

URL base: http://localhost:8000/v1. Use a chave sk-orca-* impressa na inicialização.

Caminho B — Hospedado (conta necessária)

Sem clone, sem docker. Registre-se, pegue uma chave, aponte qualquer SDK OpenAI para o hospedado.

# 1. Registre-se em https://www.orcarouter.ai e copie sua chave sk-orca-*
# 2. Use https://api.orcarouter.ai/v1 como URL base

Conta necessária. O hospedado cuida de roteamento, faturamento e da long tail de providers — cobrado por token na sua conta OrcaRouter. Veja docs.orcarouter.ai/introduction.

Depois chame de qualquer SDK OpenAI

Os exemplos abaixo usam a URL base localhost do Caminho A — troque por https://api.orcarouter.ai/v1 se estiver no Caminho B.

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="sk-orca-abc123...",
)
r = client.chat.completions.create(
    model="auto",  # ou "gpt-4o-mini", "claude-3-5-sonnet-latest", ...
    messages=[{"role": "user", "content": "Hello!"}],
)
print(r.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "http://localhost:8000/v1",
  apiKey: "sk-orca-abc123...",
});

const r = await client.chat.completions.create({
  model: "auto",
  messages: [{ role: "user", content: "Hello!" }],
});
console.log(r.choices[0].message.content);

curl http://localhost:8000/v1/chat/completions \
  -H "Authorization: Bearer sk-orca-abc123..." \
  -H "Content-Type: application/json" \
  -d '{"model":"auto","messages":[{"role":"user","content":"Hello!"}]}'

Abra http://localhost:8000/ para o dashboard — providers, roteamento, analytics, chaves (apenas Caminho A).

Por quê?

model="auto" — a feature destaque

Envie model="auto" e o OrcaRouter escolhe o modelo mais barato entre os providers configurados que atende aos requisitos de capacidade da requisição (tools, vision, modo JSON). Nada de regras de roteamento manuais; nada de ginástica com rate-limits; nada de otimização de custo if x: ... no seu código.

client.chat.completions.create(
    model="auto",
    messages=[{"role": "user", "content": [
        {"type": "text", "text": "What's in this image?"},
        {"type": "image_url", "image_url": {"url": "data:..."}},
    ]}],
)
# → roteia para o modelo mais barato com VISION coberto pelas suas chaves

O modelo resolvido é exposto de volta para quem chamou via header de resposta x-orca-resolved-model, para que você possa logar/exibir o que foi realmente usado.

Hospedado como upstream (Lite + hospedado)

Já está rodando o Lite? Defina ORCAROUTER_API_KEY com seu sk-orca-* de www.orcarouter.ai, e o hospedado vira mais um provider na cadeia de roteamento — cobrindo modelos que suas chaves locais não têm:

# .env
ORCAROUTER_API_KEY=sk-orca-hosted-abc...

Casos de uso:

• Teste-antes-de-comprar — sem precisar de chaves de provider locais
• Logging local — o hospedado cuida do roteamento, o Lite armazena linhas de RequestLog para o dashboard
• Failover — providers locais falham, o hospedado é a rede de segurança

Streaming

Formato SSE compatível com OpenAI, com framing padrão data: ... \n\n e um sentinel terminal [DONE] — drop-in para qualquer SDK que já faz streaming a partir da OpenAI.

for chunk in client.chat.completions.create(
    model="auto",
    messages=[{"role": "user", "content": "Tell me a story"}],
    stream=True,
):
    print(chunk.choices[0].delta.content or "", end="", flush=True)

Endpoints de protocolo nativos (Anthropic + Gemini)

O Lite fala três protocolos de entrada sobre um único pipeline de roteamento. Clientes que só falam os wire formats da Anthropic ou do Gemini se conectam diretamente — sem necessidade de SDK OpenAI:

# Claude Code, apontado para o Lite (sem o sufixo /v1 na URL base)
export ANTHROPIC_BASE_URL=http://localhost:8000
export ANTHROPIC_API_KEY=sk-orca-...
claude

# SDK google-genai, apontado para o Lite
from google import genai
from google.genai.types import HttpOptions
client = genai.Client(api_key="sk-orca-...",
                      http_options=HttpOptions(base_url="http://localhost:8000"))
client.models.generate_content(model="auto", contents="Hello!")

As requisições são traduzidas na borda para o mesmo pipeline interno, então model="auto", o cache de prompt cross-provider (compartilhado entre protocolos), as estratégias de roteamento e o dashboard de analytics funcionam de forma idêntica. Guias: integrations/claude-code.md, integrations/gemini-sdk.md.

Catálogo de modelos

Mais de 100 modelos de chat são carregados na inicialização a partir do banco de preços mantido pela comunidade do LiteLLM — sem lista de modelos para manter manualmente. Cada entrada expõe:

• id (ex.: gpt-4o, claude-3-5-sonnet-latest)
• provider (mapeado para suas chaves configuradas)
• Flags de capacidade: supports_tools, supports_vision, supports_json_mode
• Custo por token de entrada/saída (alimenta o widget de economia + model="auto")

GET /v1/models retorna o catálogo no formato OpenAI.

Deploy em outro lugar

Plataforma	One-click
Railway
Fly.io	fly launch --dockerfile Dockerfile
Render	Conecte o repo, root dir = .
Docker puro	docker run -p 8000:8000 -e OPENAI_API_KEY=... ghcr.io/... (imagem em breve)

O que vem na caixa

• POST /v1/chat/completions — proxy + streaming + model="auto" + cache de prompt cross-provider
• POST /v1/messages — ingress da Anthropic Messages API (Claude Code / SDKs Anthropic se conectam diretamente; + /count_tokens)
• POST /v1beta/models/{model}:generateContent — ingress da Gemini API (o SDK google-genai se conecta diretamente; + :streamGenerateContent, GET /v1beta/models)
• GET /v1/models — catálogo de modelos descobrível (100+ modelos de litellm.model_cost)
• GET/PUT/DELETE /v1/providers/{provider} — define / lista / revoga chaves de provider criptografadas
• GET/PUT /v1/routing — muda a estratégia (balanced / cheapest / fastest / quality)
• GET /v1/analytics/{recent,spend,latency,savings,unreachable} — analytics locais, nenhuma telemetria sai da caixa
• GET /v1/hosted — status do fallback hospedado (alimenta o card "Get $5 free credit" do dashboard)
• GET/POST/DELETE /v1/keys/... — lista / rotaciona / revoga chaves API
• Dashboard single-page em /
• SQLite por padrão; Postgres opt-in via DATABASE_URL; Redis opcional

Cache de prompt cross-provider

Requisições determinísticas (temperature=0 ou seed fixada) são servidas do cache em repetições — funciona em todos os providers, não só Anthropic. O backend é Redis se REDIS_URL estiver definido, caso contrário um LRU in-process. Cache hits voltam instantaneamente com x-orca-cache: HIT e custam $0.

$ curl ... -d '{"model":"auto","messages":[...], "temperature": 0}' -i
HTTP/1.1 200 OK
x-orca-cache: MISS
x-orca-resolved-model: gpt-4o-mini

$ curl ...  # mesmo payload de novo
HTTP/1.1 200 OK
x-orca-cache: HIT          ← servido do cache, sem chamada upstream

Widget de economias

GET /v1/analytics/savings?baseline=gpt-4o&days=7 reporta quanto seu tráfego teria custado em sempre-GPT-4 versus o que custou de fato. O dashboard mostra como um tile.

Integrações

Configurações drop-in para Claude Code, Gemini SDK, Continue.dev, Aider, Cursor, LangChain, LlamaIndex, Vercel AI SDK e qualquer ferramenta que fale o protocolo OpenAI Chat Completions — além dos wire formats nativos da Anthropic e do Gemini. Veja integrations/.

O que deliberadamente não tem

Esta é a edição single-workspace. Por design, sem:

• multi-tenancy, RBAC, SSO
• faturamento, wallets, pontos, programa de parceiros
• console admin, logs de auditoria, trust & safety
• deploy multi-pod / Kubernetes
• e-mail / Slack / webhooks para alertas

Para isso, veja o produto hospedado ou a (futura) edição Teams.

Testes

Construído test-first. Cada comportamento entregue aqui teve antes um teste falhando.

pip install -e ".[dev]"
PYTHONPATH=. pytest -v
# 403 passed

As linhas de slice mostram os testes adicionados quando cada slice foi entregue; o total é a suíte completa atual.

Arquitetura

app/
├── main.py             FastAPI factory + lifespan + SPA mount
├── config.py           Settings (~15 fields)
├── deps.py             DI helpers
├── seed.py             First-run bootstrap
├── auto_routing.py     model="auto" capability + cost scoring
├── router_cache.py     Single-workspace router
├── prompt_cache.py     Cross-provider exact-match cache (Redis or in-memory LRU)
├── schemas.py          OpenAI-compatible request schema
├── middleware/auth.py  sk-orca-* validation
└── routes/
    ├── chat.py         /v1/chat/completions  (blocking + streaming)
    ├── models.py       /v1/models
    ├── providers.py    BYOK CRUD
    ├── routing.py      strategy config
    ├── analytics.py    recent / spend / latency / savings / unreachable
    ├── keys.py         list / rotate / revoke API keys
    ├── hosted.py       /v1/hosted — hosted-fallback status for the dashboard
    └── health.py

packages/
├── litellm_adapter/    Router wrapper + 100+ model catalog
├── auth/               hashing + AES-256-GCM
└── db/                 models + engine + session

Roadmap

• Chat completions compatíveis com OpenAI
• Streaming (SSE)
• Roteamento model="auto" mais-barato-capaz
• Hospedado-como-upstream
• BYOK criptografado em repouso
• Dashboard de analytics local
• CI (GitHub Actions)
• Caching de prompt cross-provider
• Integrações Continue.dev / Aider / LangChain / Cursor / Vercel AI SDK
• Benchmark público + reivindicação de economia
• Proxy de embeddings + image-gen

Veja DEMO.md para o demo de failover.

Licença

MIT. Veja LICENSE.