B2BCall-dialer/docs/AI_PROVIDERS.md

# IA — Provider Layer

Agente.md secao 95-103. Primeira peça do módulo de IA: a abstração de
provider (nunca hardcoda OpenAI no domínio), os adapters OpenAI/Anthropic,
capabilities, e o cadastro de providers/modelos (global + BYOK). O
pipeline que de fato aciona isso depois de uma chamada terminar
(transcrição, análise, jobs assíncronos, prompts, scorecards, usage
metering — secao 104-124) é a próxima fase, ver TODO.md.

## Schema completo do módulo de IA, código parcial

O schema desta migration (`ai_module`) já cobre TODAS as tabelas das
secções 95-124 (`ai_providers`, `ai_models`, `ai_prompt_templates`/
`ai_prompt_versions`, `ai_jobs`, `call_transcriptions`/
`call_transcript_segments`, `call_ai_analyses`, `quality_scorecards`/
`quality_scorecard_items`/`quality_evaluations`, `ai_usage_records`) de
uma vez — mais barato revisar o desenho relacional inteiro (FKs entre
Call/CallAttempt/Campaign) numa única passada do que fatiar em várias
migrations pequenas que se emendam. O **código** que usa essas tabelas é
que vem em fases separadas — esta fase só implementa Provider/Model.

## `packages/ai` — `AIProvider` (secao 96)

```typescript
interface AIProvider {
  getCapabilities(): Promise<AICapabilityName[]>;
  validateCredentials(): Promise<boolean>;
  transcribe?(params): Promise<TranscribeResult>;
  analyze?(params): Promise<AnalyzeResult>;
  summarize?(text): Promise<string>;
  structuredGenerate?(prompt, schema): Promise<Record<string, unknown>>;
}
```

Nenhum código fora de `packages/ai` conhece o formato de request/response
de uma API de IA específica.

### `OpenAIProvider`/`AnthropicProvider` (secao 97-98)

Usam `fetch` nativo direto contra a "OpenAI API"/"Anthropic API" (secao
98: nomenclatura da API, nunca "ChatGPT" — o domínio não fica amarrado ao
nome do produto de consumidor) — sem SDK oficial, pra manter o request/
response inteiramente visível no nosso próprio código (relevante já que
potencialmente manda dados de cliente pra fora, secao 122-123).

- `transcribe` (só OpenAI — Anthropic não tem endpoint de áudio, secao
  102: "nem todo provider terá todas as capacidades"): `POST /audio/
  transcriptions`, `response_format=verbose_json` pra pegar segmentos com
  timestamp.
- `analyze`/`structuredGenerate`: OpenAI via `response_format:
  json_schema` (Structured Outputs); Anthropic via "tool use" forçado
  (`tool_choice` apontando pra uma tool única cujo `input_schema` é o JSON
  Schema pedido) — a técnica documentada da própria Anthropic pra output
  estruturado confiável antes de terem suporte nativo equivalente ao da
  OpenAI.

**Nunca exercitados nesta sessão** — a autorização de rede desta sessão
cobre só o servidor git do repositório (restrição definida desde o
primeiro pedido do usuário), então nenhuma chamada real saiu daqui.
Implementados seguindo o contrato documentado de cada API o mais fiel
possível; revisar contra as APIs reais antes de confiar em produção —
mesmo padrão de honestidade já usado pra `S3ObjectStorageProvider` (fase
Recording) e o caminho PSTN real (fase Predictive Dialer).

### `SensitiveDataRedactor` (secao 123)

Mascara CPF/CNPJ/telefone/cartão/email em texto livre antes de mandar pra
um provider, quando a política de privacidade exigir. Testado com casos
reais (CPF/CNPJ formatados, telefone com parênteses, email, número de
cartão) — todos os 5 tipos corretamente mascarados, frase sem dado
sensível passa intacta.

**Achado real testando**: um `\b` logo antes de um `\(?` opcional (regex
de telefone) falha em casar quando o caractere anterior também não é de
palavra (ex.: espaço seguido de `(`) — `\b` exige uma transição
palavra/não-palavra dos dois lados, e nem "espaço" nem "(" são caracteres
de palavra. Isso deixava o `(` de fora do match, vazando um parêntese
solto no texto redigido (nenhum dado sensível vazava de verdade, só um
caractere de formatação). Corrigido trocando o `\b` inicial por
`(?<!\w)`, que não tem esse problema.

## `ai_providers`/`ai_models` — global vs. BYOK (secao 99-101)

`scope=GLOBAL` (cadastrado pelo platform admin, `tenant_id` null) é
visível de **qualquer** tenant; `scope=TENANT` (BYOK — "Bring Your Own
Key") só do próprio dono. RLS híbrida (a mesma técnica já usada pra
`tenant_memberships` na descoberta de tenant durante login):

```sql
USING (tenant_id = current_tenant_id() OR tenant_id IS NULL)
```

Quem pode **escrever** num provider `GLOBAL` é decidido na camada de
serviço (`isPlatformUser`, já existia desde a fase RBAC), não pela RLS —
RLS aqui só garante que o BYOK de um tenant nunca vaza pro outro.

`encryptedApiKey` (AES-256-GCM, mesmo padrão de `sipPasswordEnc`/
`passwordEnc`) nunca é reexposta — toda resposta troca por
`apiKeyPreview` (últimos 8 caracteres cifrados, só o suficiente pra
reconhecer qual key é).

`AIModel.tenantId` é copiado do provider dono na criação (evita subquery
de RLS cruzando tabelas, mesmo padrão de `CampaignStats`/`CallLeg`/etc.).

## Achados reais testando esta fase

- **Delete de provider bloqueado por FK**: `AIProvidersController.remove`
  fazia hard delete (`tx.aIProvider.delete`), mas `AIModel.providerId` é
  `ON DELETE RESTRICT` — apagar um provider com pelo menos um modelo
  cadastrado (mesmo um modelo já "apagado" via soft delete, que só marca
  `enabled=false`) falhava com violação de FK. Inconsistente com o resto
  do sistema (Extension/Trunk/Queue/Campaign/Disposition/PauseReason —
  todos soft delete). Corrigido: `remove` agora também faz
  `enabled=false`, nunca hard delete — necessário de qualquer forma pra
  preservar `provider_id` válido no histórico de
  `CallTranscription`/`CallAIAnalysis` depois que um provider é
  desativado.
- **`GET /ai/providers` não filtrava desabilitados**: consequência direta
  do achado acima — sem o filtro `enabled: true`, um provider "apagado"
  continuava aparecendo na lista. Corrigido junto.

## Verificado ponta a ponta

```
Tenant A (não platform admin) tenta criar provider GLOBAL -> 403
Tenant A cria provider TENANT (BYOK, Anthropic) -> sucesso,
  encryptedApiKey nunca aparece na resposta (só apiKeyPreview)
providerType não suportado ("google") -> 403 com mensagem clara

Platform admin cria provider GLOBAL (OpenAI) -> sucesso, tenantId null

Tenant A lista -> ve' o proprio BYOK + o GLOBAL (2 providers)
Tenant B lista -> ve' SO' o GLOBAL (1 provider) — BYOK do Tenant A nunca
  vaza, confirmando a RLS hibrida
Tenant B tenta apagar o BYOK do Tenant A (por id direto) -> 404 (RLS
  esconde a linha antes mesmo do controller decidir)
Tenant B tenta apagar o provider GLOBAL -> 403 (nao e' platform admin)

Tenant A cria um AIModel sob o provider GLOBAL -> tenantId herdado como
  null, aparece na lista de AMBOS os tenants (modelo de provider global e'
  global tambem)

Apos a correcao do soft delete: apagar modelo -> 204, apagar o provider
  GLOBAL que tinha esse modelo -> 204 (antes falhava com FK), lista fica
  vazia pros dois tenants
```

typecheck do workspace inteiro limpo.

## O que falta

- Pipeline assíncrono pós-CALL_ENDED (secao 106-108: `ai_jobs`, retry com
  backoff exponencial, dead-letter) — schema pronto, worker não
  implementado ainda.
- Transcrição de verdade (secao 109-111: `call_transcriptions`/
  `call_transcript_segments`, mapeamento de speaker via canal estéreo) —
  schema pronto, nada chama `provider.transcribe()` ainda.
- Análise da chamada (secao 112-113), prompts por tenant/campanha (secao
  114-116), scorecards/QA automático (secao 117-118) — schema pronto,
  nada implementado.
- Privacidade em cascata Campaign > Queue > Tenant (secao 122) —
  `Tenant.aiPrivacyLevel`/`Queue.aiPrivacyLevel` existem no schema, função
  de resolução ainda não escrita (só faz sentido junto com o pipeline).
- Usage metering (secao 124) — `AIUsageRecord` existe, nada grava nele
  ainda (só faz sentido junto com transcrição/análise reais).
- `ParseUUIDPipe`/validação de UUID em `@Param("id")` — um id malformado
  na URL retorna 500 (erro genérico do Prisma) em vez de 400. Mesmo padrão
  em TODOS os controllers deste projeto, não é regressão desta fase —
  registrado aqui porque foi onde apareceu durante o teste, mas o fix (se
  vier a acontecer) é um retrofit em todo o `apps/api`, fora do escopo
  desta fase.