B2BCall-dialer/docs/AI_PIPELINE.md

# AI Pipeline (agente.md secao 104-116)

Sub-fase B da fase de IA: transforma o Provider Layer (PHASE 19, ver
`docs/AI_PROVIDERS.md`) num pipeline assíncrono de verdade — transcrição e
análise de chamadas, disparado sozinho depois que uma gravação fica
disponível.

## Onde cada peça mora

- `packages/ai/src/privacy.ts` — cascata Tenant > Queue > Campaign (secao
  122), pura, sem I/O.
- `packages/ai/src/retry.ts` — backoff exponencial + dead-letter (secao
  108), pura.
- `packages/ai/src/call-analysis-schema.ts` — schema JSON + validação
  manual do resultado de análise (secao 112-113).
- `packages/ai/src/wav-stereo-split.ts` — separa um WAV estéreo em dois
  WAV mono (canal 0 = perna onde `record_session` foi chamado/"cliente",
  canal 1 = perna bridgeada/"agente" — convenção não confirmada contra
  áudio real distinguível nesta sessão, só com tons sintéticos).
- `apps/freeswitch-events/src/ai-trigger.ts` — decide, no momento em que
  uma gravação fica `AVAILABLE`, se vira um `AIJob(TRANSCRIPTION)`.
  Chamado a partir de `recording.ts` logo depois do `Recording.create`.
- `apps/ai-worker/` — serviço novo (Docker, `tsx` direto, mesmo padrão de
  `apps/predictive-dialer`): tick a cada `AI_WORKER_TICK_INTERVAL_MS`
  (default 5s), reserva até `AI_WORKER_JOBS_PER_TICK` (default 5) jobs
  pendentes por tenant com `FOR UPDATE SKIP LOCKED`, processa
  TRANSCRIPTION/ANALYSIS, marca COMPLETED ou aplica retry/dead-letter.
- `apps/api/src/ai/ai-prompts.controller.ts` — CRUD de
  `AIPromptTemplate`/`AIPromptVersion` (secao 114-116), mesma RLS híbrida
  GLOBAL/tenant dos providers/models.

## Decisão de disparar (ou não) um job

Duas checagens independentes, as duas precisam passar (`ai-trigger.ts`):

1. **Entitlement do Plan** (`aiEnabled` + `aiTranscriptionEnabled`) — "essa
   conta contratou IA?". Não-lançante via `isFeatureEnabled` (novo em
   `packages/entitlements`), porque isto é uma decisão em background, não
   uma requisição HTTP que deveria retornar 403.
2. **Cascata de privacidade** Tenant > Queue > Campaign (secao 122) —
   "esse tenant/fila/campanha específica autorizou processar ESTA
   chamada?".

O job de ANALYSIS nunca é criado de cara — só depois que o job de
TRANSCRIPTION correspondente completa com sucesso, reconsultando a mesma
cascata (a config pode ter mudado entre os dois).

## Resolução de provider/modelo

agente.md não especifica um algoritmo de seleção quando o tenant tem
múltiplos providers/modelos com a mesma capability. Política adotada
(`apps/ai-worker/src/provider-resolution.ts`): prefere BYOK do próprio
tenant sobre o provider GLOBAL da plataforma; dentro de cada grupo, o
primeiro `AIModel` habilitado com a capability pedida, por `createdAt`.
Sem heurística de custo/qualidade ainda — revisar se precisar de algo mais
rico (ex.: fallback em cadeia, menor custo).

## Resolução de prompt template (análise)

`Campaign.analysisPromptTemplateId` sobrescreve quando setado; senão o
primeiro `AIPromptTemplate` de `purpose=ANALYSIS` com versão ativa,
preferindo um template do próprio tenant sobre o padrão GLOBAL. Se nada
for encontrado, o job de ANALYSIS falha com uma mensagem clara ("nenhum
template configurado") e segue o retry/dead-letter normal — não é um
crash, é uma configuração pendente do admin do tenant.

## Redação de dados sensíveis

O texto da transcrição sempre passa pelo `SensitiveDataRedactor` (secao
123) antes de sair pro `provider.analyze()`, **independente** do nível de
privacidade — o nível de privacidade controla SE a análise roda, nunca O
QUE é enviado quando roda. Defesa em profundidade.

## Limitação conhecida: Campaign só pode opt-in, nunca opt-out

`Campaign.aiTranscriptionEnabled`/`aiAnalysisEnabled` são dois booleanos
independentes (existiam desde a fase Campaigns, secao 63), não o mesmo
enum de 3 níveis de `Tenant`/`Queue`. Uma campanha não consegue forçar
`AI_OFF` explicitamente quando o tenant/fila já tem um nível mais
permissivo — só pode ligar mais IA, nunca desligar. Como "opt-in" é a
direção mais segura por padrão, aceitável por agora.

## O que foi testado de verdade nesta sessão

Restrição de rede desta sessão continua valendo: só o servidor git é
autorizado, nenhuma chamada real saiu pra OpenAI/Anthropic. Testado ao
vivo, contra o container `b2bcall-ai-worker` rodando de verdade (não
mocks) e Postgres real com RLS:

- Cascata de privacidade + entitlement, 3 cenários reais: tenant
  permissivo → job criado; `tenant.aiPrivacyLevel=AI_OFF` → nenhum job;
  privacidade permitindo mas `Plan.aiEnabled=false` → nenhum job (o
  entitlement bloqueia mesmo quando a privacidade libera).
- `splitStereoWav` com um buffer sintético: valores extremos
  (±32767/-32768), zero, negativo, todos de-interleaved corretamente;
  header malformado lança como esperado.
- `retry.ts`/`privacy.ts`/`call-analysis-schema.ts`: backoff exponencial
  com teto, dead-letter no limite exato, cascata de privacidade nos 3
  níveis, validação aceitando/rejeitando resultado de análise conforme
  schema.
- Pipeline completo ponta a ponta: WAV estéreo sintético real gravado no
  object storage local, `Recording` real `AVAILABLE`, `AIJob` real
  reservado via `FOR UPDATE SKIP LOCKED` pelo worker rodando em Docker,
  download+split+resolução de provider bem-sucedidos, chamada de rede
  real tentada contra uma porta loopback fechada (`http://127.0.0.1:1` —
  nunca sai da máquina), falha real (`fetch failed`), retry com backoff
  de 30s, dead-letter exatamente na 2ª tentativa configurada.
- `processAnalysisJob` com uma transcrição semeada manualmente: resolveu
  template, resolveu provider, redigiu o texto, tentou a chamada real,
  falhou da mesma forma esperada.

**Nunca exercitado**: a chamada de rede de verdade contra a API da OpenAI
ou Anthropic (mesma restrição desde o Provider Layer); o encadeamento
automático TRANSCRIPTION→ANALYSIS após uma transcrição *bem-sucedida* (só
dá pra testar a criação do job de ANALYSIS a partir de uma transcrição
semeada manualmente, já que nenhuma transcrição real chega a completar sem
rede); a convenção de canal 0/1 contra áudio real distinguível (só tons
sintéticos).