Gateway de IA

A Brandvelia expõe IA através de um gateway OpenRouter interno em packages/ai. O app nunca chama o OpenRouter (ou qualquer provedor) diretamente — toda funcionalidade de IA passa por este gateway, que trata seleção de provedor, isolamento de credenciais e tracking de custo.

---

Componentes

┌───────────────┐     GET/POST      ┌───────────────────┐     POST      ┌───────────────┐
│  App Next.js  │ ───────────────> │  packages/ai       │ ────────────> │ OpenRouter    │
│ (api routes)  │   auth + models   │  (gateway)        │  key + chat   │  (provedor)    │
└───────────────┘                  └───────────────────┘                └───────────────┘
        │                                                                            │
        └──────────────► getAiProvider() / logAiRun() ───────────────────────────────┘

• getAiProvider() — resolve a configuração ativa do provedor a partir das env vars do servidor.
• getActiveAiModel() — resolve o id do modelo ativo em bv_ai_models.
• provider.complete() — envia a requisição de chat e retorna conteúdo + usage.
• logAiRun() — persiste a execução em bv_ai_runs com precificação e latência.

---

Modelo de segurança

• Somente servidor. O gateway lê a chave do OpenRouter de um secret de servidor; nenhuma chave chega ao client.
• Isolamento de provedor. Credenciais são isoladas por provedor, e um linker $AI_LINKER rastreia cada requisição até a funcionalidade de origem.
• Isolamento por funcionalidade. O gateway isola quais funcionalidades podem chamar quais provedores.

---

Request / response

provider.complete({ model, system, messages, temperature, maxTokens, jsonSchema }) retorna:

interface Result {
  content: string;        // texto / JSON
  model: string;
  usage: {
    promptTokens: number;
    completionTokens: number;
    totalTokens: number;
  };
  latencyMs?: number;
}

---

Contabilidade de custo

Cada linha de modelo em bv_ai_models carrega precificação por milhão (input_price_per_m, output_price_per_m). O gateway registra contagens de tokens de entrada/saída e o custo resultante por execução — base para as linhas de custo de IA na página de finanças.

---

Tarefas disponíveis

Tarefa	Endpoint	Propósito
copilot	POST /api/ai/copilot	Assistente de Q&A sobre dados do negócio.
creative_generation	POST /api/ai/creative	Copy de resposta direta compliant.
opportunity_score	Adaptador ClickBank	Scoring de produtos de marketplace.

Toda afirmação factual gerada por IA deve passar pelo validador de claims do Motor de Decisão: FACT sem evidence ID válido do workspace é rejeitado.