withOhm

Ohm (withOhm)

Em uma frase: withOhm é um proxy que fica entre seu aplicativo (ou Cursor) e OpenAI/Anthropic/etc. — ele reproduz requisições byte-idênticas gratuitamente em vez de pagar novamente pelo modelo, busca contexto web público sob controles de conformidade e oferece uma única fatura auditável com recibo criptográfico em vez de várias faturas opacas de provedores.

O cano medido para inferência desperdiçada e repetida: entrada compatível com OpenAI, replay de prompts via Redis, ingestão web em conformidade, locação SSO para organizações e um razão corporativo limpo. Para empresas, o mesmo cano é um governador de caos para gastos com IA (cunha canônica: docs/GEM_POSITION.md). Cursor/MCP são clientes opcionais.

Hits de replay exato que custam zero tokens upstream. Consistência entre provedores. Localidade — leituras de borda via Redis. Valor de replay e auditoria. Aponte qualquer cliente compatível com OpenAI (ou o Ohm Agent Shell) para uma única URL base. Mantenha suas chaves ou use um pool gerenciado. Alugue o encanamento; governe o caos.

Site: https://www.withohm.dev · API: https://api.withohm.dev/v1 · Workbench: /workbench · Arquitetura: docs/ARCHITECTURE.md · Visão: docs/VISION.md · Empresarial: docs/ENTERPRISE_CHAOS.md · Gem: docs/GEM_POSITION.md · Auditoria de cuidado: docs/CARE_AUDIT.md — a disciplina de manutenção da verdade aplicada a cada afirmação pública; leia antes de julgar a relação engenharia-para-tração.

Licença: MIT (veja LICENSE + NOTICE). O código-fonte é aberto; o cano hospedado withOhm permanece um serviço comercial medido. Nomes de pacotes/chaves ainda podem dizer at-utility / sk-at-* (prefixo legado AT); o produto é withOhm.

Estágio, claramente

Sem enrolação: withOhm é pré-seed e pré-tração por design, não por acidente de omissão. Tabela completa e regra de fonte: docs/STATUS.md.

Fato	Agora
Versão	0.1.2
Parceiros de design	0 do alvo de 10 times (docs/DESIGN_PARTNERS.md — "do zero")
Financiamento institucional	Nenhum; pré-incorporação (docs/distribution/INVESTOR_INTRO_TARGETS.md)
Região	Única (us-east-1); sem SLA contratual
Cobertura de testes automatizados	30 arquivos, 215+ funções de teste em tests/ (pytest -q, CI a cada push)

A disciplina de engenharia e auditoria (testes, recibos assinados, INSPECTION.md, docs/CARE_AUDIT.md) é onde o tempo pré-tração foi investido — leia os números do estágio e a disciplina juntos, não um sem o outro.

Verifique você mesmo

Prosa é barata; toda afirmação estrutural vem com o comando que a verifica.

Afirmação	Verificação
O cano está ativo (ambos os planos)	curl -s https://api.withohm.dev/health && curl -s https://api.withohm.dev/ready
Hits são reproduzidos e cobrados como hits	Envie o mesmo corpo duas vezes; a segunda resposta tem X-AT-Cache: HIT + X-AT-Billed-USD
Um hit é criptográfico, não presumido	Respostas de hit carregam X-Ohm-Receipt (JWS assinado) — verifique: python scripts/verify_receipt.py "<receipt>" (docs/RECEIPTS.md)
Chaves de assinatura são públicas	curl -s https://api.withohm.dev/.well-known/http-message-signatures-directory
Limites e recusas publicados	curl -s https://api.withohm.dev/v1/public/honesty — o que não faremos, com o endpoint que prova cada item
Contador de economia entre locatários	curl -s https://api.withohm.dev/v1/public/stats (sempre estimate_only: true)
O caminho de revisão funciona todas as noites contra produção	Histórico do workflow do caminho dourado

Contrato local do desenvolvedor (estável)

Papel	Endereço	Notas
Entrada pública do cliente	http://localhost:8081/v1	Borda Rust. Aponte os SDKs da OpenAI para cá.
Plano de controle interno	http://localhost:8080	Python FastAPI. Rust faz proxy para cá em cache miss. Não dê isso a estranhos.
Autenticação	Authorization: Bearer <ohm-api-key>	Chave de bootstrap local: sk-at-dev (veja .env).
BYOK	X-Ohm-Upstream-Key: <provider-key>	Exigido em cache miss para gpt/claude, a menos que haja chaves gerenciadas por env/enterprise.
Seleção de modelo	Campo JSON model	mock permanece local; gpt-* / o* → OpenAI; claude-* → Anthropic; gemini-* → Google; deepseek-* → DeepSeek; kimi-* / moonshot-* → Moonshot; glm-* → Z.ai; qwen* → Qwen; grok-* → xAI (todos compatíveis com OpenAI, BYOK).

from at_utility_sdk import openai_client, LOCAL_BASE_URL

client = openai_client(
    "sk-at-dev",
    base_url=LOCAL_BASE_URL,
    upstream_api_key="sk-proj-...",
)
completion = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Hello"}],
)

Início rápido (Docker Compose)

cd <repo-root>   # e.g. clone of iwasinnam2/ohm
copy .env.example .env
# Edit .env: set OPENAI_API_KEY for local env-fallback; keep OPENAI_BASE_URL=https://api.openai.com/v1
docker compose --profile rust up --build -d
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\release_smoke.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\railgun_smoke.ps1

Execução nativa em nuvem / agente (sem Docker): veja AGENTS.md.

O teste de fumaça de release verifica integridade, miss/hit de mock, miss/hit da OpenAI (quando uma chave está presente), cabeçalho do plano Rust e contadores de uso. O teste de fumaça do Railgun verifica cabeçalhos BYOK, seat_plus_meters e o formato do endpoint de checkout.

Cursor / MCP

MCP stdio local mais um MCP remoto sem estado sobre HTTP com streaming (núcleo sem estado MCP 2026-07-28). Base pública: https://api.withohm.dev/v1. Parceiros: docs/LAUNCH_GTM.md · https://www.withohm.dev/design-partners

pip install withohm-mcp
# monorepo dev alternative: pip install -e ".[mcp]"
# stdio (Cursor local attach): set OHM_API_KEY (required). Optional: OHM_UPSTREAM_KEY, OHM_BASE_URL
# Plugin: .cursor-plugin/ + mcp.json — see docs/CURSOR.md

# Remote (stateless streamable HTTP at /mcp, default port 8091):
#   OHM_MCP_TRANSPORT=http ohm-mcp     (or: ohm-mcp-http)
# Auth is per-request: clients send `Authorization: Bearer sk-at-*`
# (falls back to OHM_API_KEY env). Host allowlist: OHM_MCP_ALLOWED_HOSTS.

Honestidade sobre streaming e failover

• Não-streaming de conclusões de chat: a borda Rust pode tentar novamente o upstream Python (URL primária e depois de fallback) antes de retornar um corpo. As gravações de cache ocorrem após uma resposta completa bem-sucedida.
• Streaming de conclusões de chat: failover pré-primeiro-byte é implementado. O plano Python abre proativamente o stream upstream, tenta novamente uma vez se ele falhar antes do primeiro byte e retorna um erro HTTP honesto (não um stream de erro com status 200) se ambas as tentativas falharem; a borda Rust recorre em erros de conexão ou 5xx antes do primeiro byte e encaminha o stream de tokens pedaço por pedaço (sem buffer na borda). A troca de provedor no meio do stream após o primeiro byte sem reconexão do cliente não é suportada — planeje reconexão ou não-stream para caminhos críticos.

Regras de ambiente

• Segredos ativos pertencem apenas a .env (ignorado pelo git).
• .env.example nunca deve conter um segredo ativo da OpenAI ou Stripe.
• Após alterar .env, recrie os contêineres: docker compose up -d --force-recreate gateway.
• OPENAI_BASE_URL deve ser https://api.openai.com/v1, nunca o host do site platform.openai.com.

Limites legais (obrigatório)

A ingestão web é somente pública e limitada por finalidade sob as normas do GDPR/CMA do Reino Unido e CFAA/CCPA dos EUA. Todo o repositório deve permanecer dentro desse framework—veja docs/LEGAL.md.

Quando fetch_web_context for verdadeiro, os clientes devem enviar:

• web_purpose — um de public_web_retrieval, business_catalog, public_company_info, job_listings
• web_compliance_ack: true — confirme somente público, sem coleta de leads / dossiês / acesso restrito
• terms_ack / dpa_ack: true — vincule os modelos de docs/legal/
• opcional cache_control: "no_store" — pule a gravação no Redis para prompts confidenciais

Inspecione a política ativa: GET /v1/compliance/policy. Modelos: Termos, DPA, checklist de upstream em docs/legal/.

Arquitetura

Camada	Papel
gateway-rs (:8081)	Borda pública: cache de protocolo de serialização Redis, proxy, cabeçalho de plano
Gateway Python (:8080)	API compatível com OpenAI, provedores, limites de taxa, medição, locação, portões de conformidade
Worker de ingestão (:8090)	Meta-busca + busca de página pública → markdown/JSON redigido para fetch_web_context
src/at_utility/compliance/	Matriz de finalidade, portão de URL, robots.txt, redação de PII
src/ohm_mcp/	Anexo MCP do Cursor (ohm_fetch_web, ohm_usage, ohm_chat)
Líder / réplica Redis	Cache + RL; GET na réplica/leitor, SET no líder — docs/REDIS_MESH.md
infra/	Terraform + Kubernetes: EKS de região única (mesh mantido atrás de flags)
site/	Marketing + docs + autoatendimento /billing

Locação e cobrança

A chave de bootstrap sk-at-dev funciona localmente. Autoatendimento: POST /v1/billing/checkout (site /billing). Operações: emitir com chave de administrador (AT_ADMIN_API_KEYS):

curl.exe -s -X POST http://localhost:8080/v1/admin/tenants `
  -H "Authorization: Bearer sk-at-dev" `
  -H "Content-Type: application/json" `
  -d "{\"plan\":\"payg\",\"label\":\"design-partner-1\",\"terms_ack\":true,\"dpa_ack\":true}"

Locatários suspensos (POST /v1/admin/tenants/{id}/status com {"status":"suspended"}, ou webhook de cancelamento do Stripe) recebem HTTP 403.

A medição grava chaves de razão diárias duráveis e sincroniza os medidores de cobrança do Stripe quando stripe_customer_id está definido (ohm_web_fetch, ohm_cache_hit, ohm_cache_miss).

Razões: O cliente paga os provedores (BYOK). O cliente paga assento Ohm + medidores. Opcional: pip install -e ".[billing]".

Testes

pip install -e ".[dev,billing]"
pytest -q