# ADR-0008 — Orquestração de IA via ports & adapters

**Status:** Accepted  
**Data:** 2026-07-14  
**Decisores:** Arquitetura de Software

---

## Contexto

IA é diferencial (UC-008), mas provedores, preços e modelos mudam rapidamente. Acoplar LangChain/SDK de um vendor ao domínio cria lock-in e dificulta auditoria de prompts.

## Decisão

O módulo `ai` define ports (`CompletionProvider`, `EmbeddingProvider`, `PromptRepository`). Adapters isolam vendors. Prompts versionados. Domínio de Cases/Risk **não** importa SDKs de LLM. Frameworks de orquestração, se usados, ficam **apenas** em adapters.

## Alternativas consideradas

| Opção | Prós | Contras | Por que não |
|--------|------|---------|-------------|
| LangChain no domínio | Velocidade demo | Acoplamento, abstrações opacas | Risco longevidade |
| Um único vendor SDK nas use cases | Simples | Lock-in | Inaceitável |
| Sem IA no MVP | Menos risco | Perde diferencial | Visão do produto exige v1 controlada |

## Consequências

### Positivas
- Troca de provider e multi-model routing.
- Auditoria de template/modelo.
- Testes com fake providers.

### Negativas / riscos
- Mais código de cola inicial.
- Necessidade de eval harness próprio.

### Follow-ups
- [ ] Definir schema de `prompt_template` versionado.
- [ ] Golden set mínimo de avaliações antes do GA da feature.

## Referências

- [Tecnologias](../arquitetura/02-tecnologias.md)
- [Clean / DDD](../arquitetura/05-clean-solid-ddd.md)