# ClientFlow v4928.1.5.4 — LLM-first Reply Assistant

## Decisão arquitetural

A abordagem anterior estava a crescer como uma árvore de regras e exceções.  Esta versão muda o centro de decisão:

```text
Antes:
mensagem → regras/intents → template

Agora com LLM ativo:
mensagem limpa → guardrails objetivos → contexto + conhecimento BLIF → LLM → validação → operador
```

As regras deixam de tentar interpretar todos os casos comerciais.  Passam a servir apenas para proteger situações objetivas onde a resposta ao cliente deve ser evitada ou controlada.

## Fluxo

```text
Task/Oportunidade
  ↓
MessageCleaner
  ↓
Guardrails objetivos
  ↓
BusinessKnowledgeRetriever
  ↓
OpenRouter LLM
  ↓
ReplySafetyValidator
  ↓
Rascunho editável na UI
```

## Guardrails objetivos

Apenas estes casos preemptam o LLM:

- `BOUNCE_EMAIL`
- `AUTO_REPLY`
- `UNSUBSCRIBE_REQUEST`
- `ADDRESS_UPDATE`

Tudo o resto deve ser interpretado pelo LLM quando `CLIENTFLOW_REPLY_LLM_ENABLED=true`.

## LLM como interpretador

O LLM recebe:

- mensagem limpa do cliente;
- dados do cliente;
- estado/action da tarefa;
- documentos selecionados;
- conhecimento BLIF recuperado;
- catálogo de produtos/acessórios;
- instruções de segurança.

E deve devolver JSON estruturado com:

```json
{
  "intent": "technical_datasheet_request",
  "reply_type": "answer_with_links_or_attachment",
  "requires_attachment": true,
  "confidence": 0.86,
  "customer_need": "Cliente pediu fichas técnicas dos carregadores.",
  "recommended_next_action": "Selecionar/anexar ficha técnica antes de enviar.",
  "message_body": "Olá...",
  "knowledge_used": ["technical_features"],
  "warnings": []
}
```

## Fallback

Se LLM estiver desligado:

- o sistema usa o gate determinístico existente;
- evita fallback agressivo para lista de equipamentos;
- prefere revisão manual quando incerto.

Se LLM estiver ligado mas falhar numa resposta `LLM_BUSINESS_REPLY`:

- a sugestão fica bloqueada;
- a tarefa deve ser revista manualmente;
- nenhuma resposta genérica é considerada segura.

## Uso do assistente ChatGPT existente

Um GPT personalizado do ChatGPT não é chamado diretamente pelo backend.  O caminho correto é migrar o conhecimento/instruções desse GPT para a base interna do Clientflow:

```text
Custom GPT / Assistente de e-mails
  ↓
exportar instruções + ficheiros + exemplos aprovados
  ↓
app/business_knowledge/
  ↓
OpenRouter/API no backend
```

Assim o conhecimento fica versionado, auditável e combinado com oportunidade, documentos e validações reais.
