🔌 BYOK Proxy & Multi-modelo

O que é

O endpoint canônico do daemon para usar BYOK (Bring Your Own Key):

POST /api/proxy/stream
Content-Type: application/json

{
  "baseUrl": "https://api.anthropic.com",
  "apiKey": "sk-ant-...",
  "model": "claude-opus-4-7",
  "messages": [{"role": "user", "content": "..."}]
}

→ Server-Sent Events (SSE) pass-through

Por que aprender

Esse endpoint é o que permite trocar de motor sem mudar UI. UI fala 1 protocolo (com daemon); daemon traduz pra 11+ providers diferentes. Saber a anatomia = saber adicionar provider novo, debugar request, e configurar headers customizados.

Conceitos-chave

• SSE pass-through: daemon não bufferiza; streaming token-by-token
• baseUrl override: qualquer endpoint OpenAI-compatible
• Headers customizáveis: Auth, x-api-key, anthropic-version
• Request transformation: Anthropic ≠ OpenAI ≠ Ollama (daemon adapta)

O que é

Server-Side Request Forgery (SSRF) — atacante manda baseUrl: http://127.0.0.1:6379 e o daemon faz request pro Redis local. Bloqueio mecânico:

• 127.0.0.0/8 (loopback) — bloqueado por default
• 169.254.0.0/16 (link-local AWS metadata) — bloqueado
• 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16 (RFC1918) — bloqueado
• Exception: localhost:11434 (Ollama) — explicitamente permitido

Por que aprender

SSRF é um vetor real: daemon tem privilégio de rede no host. Se UI puder controlar baseUrl sem guarda, qualquer site malicioso pode varrer rede interna. Guard mecânico = único modo de proteger.

Conceitos-chave

• Allowlist Ollama: exception explícita para localhost:11434
• DNS rebinding: resolve, valida IP, então connect
• Override: usuário pode whitelist endpoints custom em config
• Zero by default: qualquer não-explícito é bloqueado

O que é

Quase todos providers (exceto Anthropic) implementam o formato OpenAI: POST /v1/chat/completions com { model, messages, stream, tools }. Daemon usa esse formato como "lingua franca". Trocar provider = trocar baseUrl. Mesmos messages funcionam.

Por que aprender

Saber que OpenAI é o padrão = não se preocupar com format de cada provider. Adicionar provider novo = adicionar 1 entrada em KNOWN_PROVIDERS, sem código. Padronização = manutenção zero.

Conceitos-chave

• /v1/chat/completions: endpoint padrão
• SSE event format: data: { ... } linha por linha
• Anthropic exception: /v1/messages, formato próprio
• Adapter no daemon: traduz Anthropic ↔ OpenAI quando necessário

O que é

Em apps/web/src/state/config.ts, uma tabela com presets:

export const KNOWN_PROVIDERS = {
  anthropic: { baseUrl: 'https://api.anthropic.com', headers: {...}, models: [...] },
  openai:    { baseUrl: 'https://api.openai.com/v1' },
  groq:      { baseUrl: 'https://api.groq.com/openai/v1' },
  deepseek:  { baseUrl: 'https://api.deepseek.com' },
  mimo:      { baseUrl: 'https://api.xiaomi.com/...', toolChoice: 'none' },
  openrouter:{ baseUrl: 'https://openrouter.ai/api/v1' },
  ollama:    { baseUrl: 'http://localhost:11434/v1' },
}

Por que aprender

Saber a tabela = saber qual provider escolher. Cada um tem trade-off: Groq = velocidade extrema (Llama, Mixtral). OpenRouter = catálogo amplo (qualquer modelo). DeepSeek = barato, modelo decente. Ollama = local, free, lento.

Conceitos-chave

• Preset table: baseUrl + headers + lista de modelos
• Add new: nova entrada em KNOWN_PROVIDERS, deploy
• Custom override: user pode usar baseUrl arbitrário
• Per-provider quirks: MiMo precisa tool_choice: 'none'

O que é

Ollama roda modelos locais via http://localhost:11434/v1. Para geração HTML/CSS/JS, modelos generalistas (llama3, mistral) são piores que coding-specialized (qwen2.5-coder, deepseek-coder, codestral). Recomendação: qwen2.5-coder:32b em GPU de 24GB+; qwen2.5-coder:7b em laptop sem GPU.

Por que aprender

"Vou rodar local" sem saber qual modelo = decepção. Llama 3 70B tem fama, mas em HTML é pior que qwen 7B. Coding-specialized vence generalist em 95% das tarefas de design HTML.

Conceitos-chave

• qwen2.5-coder:32b: sweet spot qualidade-velocidade (RTX 4090)
• qwen2.5-coder:7b: laptop CPU/MBP (M1/M2/M3)
• deepseek-coder-v2: alternativa
• codestral: Mistral coding, bom em raciocínio CSS
• Evitar: llama3, mistral, gemma para HTML — generalistas

O que é

MiMo (Xiaomi) implementa OpenAI-compatible, mas tem comportamento errático com tools: às vezes retorna tool_call vazio, às vezes ignora schema. Solução: forçar tool_choice: 'none' nesse provider — modelo gera só texto livre, OD parseia <artifact> do output, sem tools.

Por que aprender

É um padrão de adaptação para providers "quase compatíveis". Em vez de evitar MiMo, OD acomoda quirk. Mesmo padrão se aplica a outros providers de baixo custo que tenham bug em tool calling.

Conceitos-chave

• tool_choice: 'none': força modelo a gerar texto, sem tool
• Per-provider quirks: declarados em KNOWN_PROVIDERS
• Trade-off: sem tool = sem TodoWrite explícito (texto narra)
• Aplicável a: Qwen-API, alguns OpenRouter providers

O que é

2 caminhos pra falar com modelo:

Regra: CLI quando disponível; proxy quando não.

Por que aprender

CLI tem features que API não tem (TodoWrite live, file system tools, MCP servers). Para fluxos avançados, CLI é estritamente superior. BYOK proxy é o fallback. Saber escolher = não perder potência.

Conceitos-chave

• CLI vantagens: TodoWrite, file tools, MCP, skills nativas
• CLI desvantagens: só funciona com modelo da CLI
• BYOK vantagens: qualquer modelo (Ollama free, GPT-5, etc.)
• BYOK desvantagens: sem TodoWrite, sem skills nativas
• Hybrid: CLI default + BYOK fallback de provider