ADR-039 — AI gateway architecture

Architecture decision record — status: Accepted.

Source: docs/adr/ADR-039-ai-gateway.md

ADR-039: AI gateway architecture

Estado

Accepted — 2026-08-23

Contexto

ADR-019 fija HITL y “no inventar cifras”. Falta el cómo se llama al modelo. IVPrior prevé RAG, agents y vector DB. Eso no es el wedge de IVPrior V1 (clasificar un reply).

Decisión

V1 = un caso de uso: ClassifyReply.

MessageReceived → ClassifyReply use case
  → AiGateway.port.complete(structured schema)
  → ReplyClassification + confidence
  → Promise | Dispute | Task
  1. AiGateway adapter: un vendor (OpenAI u otro) detrás del puerto. Modelo y API key por env + override de Organization más adelante.
  2. Salida JSON schema (intent + optional extract + confidence). No chat libre en el panel V1.
  3. Prompts versionados en repo (prompts/classify-reply.md o equivalente). Cambio de prompt = PR.
  4. PII: no enviar password ni mailbox tokens. Cuerpo de email: mínimo; redactar CC extra si hace falta.
  5. Logging: modelVersion, tokens, latency, organizationId — no el prompt completo con PII en logs INFO.
  6. Budget: timeout + max tokens. Fallo de vendor → Task humana, no reintento infinito.
  7. Fuera de V1: RAG, embeddings, vector DB, tool-calling agents, “AR copilot chat”.

Alternativas

Copiar ADR-030 de IVPrior (RAG/agents): se descarta hasta que el dashboard pida Q&A sobre AR.

Consecuencias

  • Spike de accuracy usa fixtures de replies, no un chatbot.
  • Un segundo use case de IA (redactar follow-up) requiere amendment y plantilla humana aprobada (ADR-019 §6).