caveman-setup

Você está conectando este repositório ao gateway Caveman. Caveman é um proxy de LLM que preserva bytes: no modo de registro, ele mede o que seu aplicativo envia e quanto custa, e não altera mais nada. Seu trabalho é uma integração mínima e verificada — não uma refatoração.

O prompt que o enviou aqui fornece quatro valores. Consulte-os como:

• GATEWAY — a URL base do gateway (ex.: https://gateway.caveman.so ou http://127.0.0.1:8787)
• CAVE_API_KEY — o segredo de autenticação do gateway (trate como qualquer chave de API: apenas variável de ambiente, nunca commitada, nunca impressa por completo)
• PROVIDER_KEYS — stored (as chaves dos provedores ficam criptografadas no Caveman Cloud) ou byok (este aplicativo envia sua própria chave de provedor por requisição)
• DASHBOARD — a URL base do painel (ex.: https://app.caveman.so)

Se algum valor estiver faltando, pare e peça por ele. Não adivinhe uma URL nem crie uma chave.

Regras (não negociáveis)

1. Integração coerente. Conecte cada ponto de chamada a LLM ativo através de configurações existentes e pontos de integração responsáveis. Toque em cada camada que a correção exigir. Sem refatorações ou reformatações aleatórias; adicione uma abstração apenas quando ela clarificar a responsabilidade ou reduzir o custo de ciclo de vida.
2. Segredos ficam em variáveis de ambiente. CAVE_API_KEY vai para o arquivo de ambiente que o repositório já usa (.env, .env.local, …). Se esse arquivo não estiver no .gitignore, adicione-o e informe. Nunca codifique a chave no código-fonte.
3. Relate apenas o que você observou. O relatório final informa o status HTTP e os números de uso da resposta de verificação real — nunca sucesso assumido. Se a verificação falhar, relate o modelo de falha correspondente.
4. Apenas modo de registro. Você está adicionando medição. Você não habilita nenhuma otimização e não alega nenhuma economia — economias verificadas são $0 até que um otimizador seja explicitamente ativado e passe em seu portão de avaliação.
5. Chaves de provedor não são da sua conta. Com PROVIDER_KEYS: stored você nunca vê uma. Com byok, a chave de provedor existente do aplicativo permanece exatamente onde já está.

Passo 1 — Encontre todos os pontos de chamada a LLMs ativos

Leia os arquivos de dependência (package.json, requirements.txt, pyproject.toml, go.mod, lockfiles) e pesquise no código-fonte por clientes de LLM:

• Importações de SDK: openai, @anthropic-ai/sdk, anthropic, ai + @ai-sdk/* (Vercel), langchain*, litellm, google-genai / @google/genai, crewai, pydantic_ai, openai-agents / agents
• HTTP bruto para api.openai.com, api.anthropic.com, generativelanguage.googleapis.com
• Variáveis de ambiente de URL base existentes: OPENAI_BASE_URL, OPENAI_API_BASE, ANTHROPIC_BASE_URL, GEMINI_BASE_URL, GOOGLE_GEMINI_BASE_URL

Liste o que encontrou (arquivo:linha por ponto de chamada) antes de alterar qualquer coisa. Se você encontrar nenhum ponto de chamada a LLM, pare e relate o modelo "nada a conectar" no final deste arquivo — não invente uma integração.

Passo 2 — Escolha o slug do aplicativo

Um slug nomeia este aplicativo no caminho do gateway: GATEWAY/w/<app>. Derive-o do nome do pacote/módulo (ex.: support-bot, acme-api). Gramática: letras minúsculas [a-z0-9] primeiro, depois [a-z0-9._-], máximo de 64 caracteres. Os gastos de todo este aplicativo são agrupados sob esse slug no painel.

Passo 3 — Conecte cada ponto de chamada

O padrão é sempre o mesmo: URL base → o gateway com /w/<app>, mais um cabeçalho de autenticação. A autenticação do gateway é x-cave-api-key: CAVE_API_KEY (Authorization: Bearer CAVE_API_KEY também funciona onde um cabeçalho é complicado). Com PROVIDER_KEYS: byok, envie também x-cave-upstream-key: <a chave de provedor que o aplicativo já usa>.

Dois fatos que tornam a conexão segura (ambos são aplicados pelo gateway, não esperanças): o gateway reconstrói os cabeçalhos de autenticação upstream do zero, então o valor Authorization/x-api-key de um cliente nunca é encaminhado ao provedor; e com stored, a autenticação upstream vem da conexão criptografada no lado do servidor. Portanto, no modo stored, onde um SDK insiste em um parâmetro api-key, defina-o como a chave do Cave — ela autentica o gateway e não vai além.

Formas exatas (use a que corresponde a cada ponto de chamada — estas são as receitas publicadas do produto, não sugestões):

SDK OpenAI (TS) — Chat Completions e Responses ambos roteiam através de:

const client = new OpenAI({
  baseURL: `${process.env.CAVE_GATEWAY_URL}/w/<app>/openai/v1`,
  apiKey: process.env.OPENAI_API_KEY,           // byok: inalterado · stored: use CAVE_API_KEY
  defaultHeaders: {
    "x-cave-api-key": process.env.CAVE_API_KEY!,
    // apenas byok:
    "x-cave-upstream-key": process.env.OPENAI_API_KEY!,
  },
});

SDK OpenAI (Python) — mesma forma: base_url=f"{gw}/w/<app>/openai/v1", default_headers={"x-cave-api-key": ..., "x-cave-upstream-key": ...}.

SDK Anthropic (TS/Python) — o SDK anexa /v1/messages por conta própria. O cabeçalho x-cave-api-key é obrigatório aqui em ambos os modos (o parâmetro de chave próprio deste SDK viaja em x-api-key, que não é um cabeçalho de autenticação do gateway):

client = anthropic.Anthropic(
    base_url=f"{os.environ['CAVE_GATEWAY_URL']}/w/<app>",
    api_key=os.environ["ANTHROPIC_API_KEY"],      # byok: inalterado · stored: use CAVE_API_KEY
    default_headers={
        "x-cave-api-key": os.environ["CAVE_API_KEY"],
        # apenas byok:
        "x-cave-upstream-key": os.environ["ANTHROPIC_API_KEY"],
    },
)

SDK Vercel AI — createOpenAICompatible({ baseURL: ${gw}/w//openai/v1, headers: { "x-cave-api-key": ... } }); modelos Anthropic através de createAnthropic({ baseURL: ${gw}/w//v1, headers: { ... } }).

LangChain / LangGraph — ChatOpenAI(base_url=f"{gw}/w/<app>/openai/v1", default_headers={...}); ChatAnthropic(base_url=f"{gw}/w/<app>", default_headers={...}). LangGraph herda qualquer modelo que você passar.

LiteLLM — por chamada api_base=f"{gw}/w/<app>/openai/v1" + extra_headers={...}, ou em toda a frota no config.yaml do proxy LiteLLM.

HTTP bruto / qualquer outra coisa — troque o host, mantenha o caminho nativo do provedor: GATEWAY/w/<app>/v1/chat/completions (protocolo OpenAI) ou GATEWAY/w/<app>/v1/messages (protocolo Anthropic), adicione o(s) cabeçalho(s).

Concretamente, com o slug support-bot e o gateway hospedado, uma URL base do SDK OpenAI lê https://gateway.caveman.so/w/support-bot/openai/v1. E no modo stored, remova completamente todas as linhas x-cave-upstream-key — é apenas para byok.

Para frameworks não listados (google-genai, crewai, pydantic-ai, openai-agents), busque a página correspondente em <docs origin>/docs/integrations/ — mesma origem de onde esta skill veio — e siga-a.

Adicione ao arquivo de ambiente do repositório (e referencie do código — sem literais):

CAVE_GATEWAY_URL=<GATEWAY>
CAVE_API_KEY=<CAVE_API_KEY>

Passo 4 — Verifique com uma requisição real

O usuário colou o prompt de configuração para autorizar exatamente isto: uma pequena requisição de verificação. Envie-a agora — não pare para pedir permissão. Uma integração que termina não verificada porque você hesitou é um resultado pior do que uma pequena requisição; finalizar a verificação e o relatório de forma autônoma é o propósito desta skill.

Envie uma requisição mínima através da conexão que você acabou de construir — o caminho mais barato do próprio aplicativo, se ele tiver um script para isso, caso contrário, curl no caminho correspondente ao protocolo que você acabou de conectar com o modelo do próprio aplicativo e um limite pequeno (max_tokens ≤ 32):

# Conexão de protocolo OpenAI:
curl -sS "$CAVE_GATEWAY_URL/w/<app>/v1/chat/completions" \
  -H "x-cave-api-key: $CAVE_API_KEY" \
  -H "content-type: application/json" \
  -d '{"model":"<modelo que o repositório já usa>","max_tokens":16,"messages":[{"role":"user","content":"ping"}]}'

# Conexão de protocolo Anthropic:
curl -sS "$CAVE_GATEWAY_URL/w/<app>/v1/messages" \
  -H "x-cave-api-key: $CAVE_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"<modelo que o repositório já usa>","max_tokens":16,"messages":[{"role":"user","content":"ping"}]}'

(byok: adicione -H "x-cave-upstream-key: $PROVIDER_KEY".) Esta é uma requisição real e cobrável ao provedor — esse é o ponto: tráfego real, medição real.

Leia a resposta. Sucesso = HTTP 200 com um bloco usage. Qualquer outra coisa = o modelo de falha correspondente abaixo.

Passo 5 — Relate

Termine exatamente com esta forma, com valores preenchidos a partir do que você realmente fez e viu:

## Caveman está ativo neste repositório

Conectado: <n> ponto(s) de chamada em <n> arquivo(s)
  - <arquivo> — <uma linha descrevendo o que mudou>
Slug do aplicativo: <app> — gastos deste aplicativo agrupados sob ele
Verificado: HTTP 200 · modelo <modelo> · <entrada> tokens de entrada / <saída> tokens de saída (uma requisição real)
Modo: registro — apenas medido. Nenhum byte visível ao modelo foi alterado, nenhuma otimização habilitada. Economias verificadas são $0 até que você ative um otimizador e ele passe em seu portão de avaliação. Essa honestidade é o produto.

Veja os gastos: <DASHBOARD>/traces — sua requisição é a primeira linha, precificada a partir do catálogo público. <DASHBOARD>/getting-started muda para "Primeira requisição recebida."

Quer dividir gastos por fluxo de trabalho (ex.: resposta-suporte vs resumo-noturno), não apenas por aplicativo? Diga "descobrir fluxos de trabalho" — vou buscar <docs origin>/docs/discover-workflows.md e rotular cada ponto de chamada pelo trabalho que ele faz.

Modelos de falha (use textualmente, preenchidos — nunca suavize)

• Nada a conectar: "Não encontrei pontos de chamada a LLM neste repositório (pesquisei SDKs, HTTP bruto de provedores, variáveis de ambiente de URL base). Se este repositório executa um agente de codificação em vez de enviar código de LLM, use caveman wrap <agente> — veja /getting-started."
• Gateway inacessível: "A requisição de verificação não conseguiu alcançar GATEWAY (). A conexão está no lugar, mas não verificada — nada será medido até que o gateway esteja acessível. Verifique a URL e a rede, depois reexecute o curl de verificação acima."
• 401 cave_invalid_api_key: "O gateway rejeitou CAVE_API_KEY. Crie uma nova chave em /getting-started e atualize o arquivo de ambiente; a conexão em si não foi alterada."
• 404 cave_route_not_found: "O gateway não encontrou nenhuma rota — geralmente um slug /w/ malformado (minúsculas [a-z0-9] primeiro, depois [a-z0-9._-], máx. 64) ou um caminho que não corresponde ao protocolo do SDK. Corrija a URL e verifique novamente."
• Erro do provedor (4xx/5xx através do gateway): reporte o status + o corpo textualmente; o gateway está acessível e a autenticação passou, a chamada upstream falhou — geralmente um problema de chave de provedor ou nome de modelo no próprio aplicativo.

Nunca reporte sucesso em nenhum destes. Uma integração não verificada é reportada como não verificada.