# ClientFlow v4928.1.5.0 — BLIF Knowledge Reply Assistant

## Objetivo

Adicionar o caminho realista para respostas comerciais melhores sem fine-tuning: conhecimento BLIF estruturado, recuperação por tópico, geração LLM opcional via OpenRouter e validação comercial antes do envio.

A versão mantém o operador no controlo: o sistema gera um rascunho editável e só envia para Chatwoot quando o operador confirma.

## O que mudou

- Base de conhecimento BLIF estruturada em `app/business_knowledge/blif_knowledge.json`.
- Recuperação determinística de tópicos por palavras-chave em `app/business_knowledge_service.py`.
- Novos modelos de esclarecimento sem anexo, incluindo instalação, IVA, entrega/pagamento, RFID, balanceador, histórico local, condomínio/MOBI.E e funcionalidades técnicas.
- Seleção automática de template de conhecimento quando a última mensagem do cliente corresponde a um tópico BLIF.
- Geração LLM opcional via OpenRouter em `app/llm_reply_generator.py`.
- Validador comercial em `app/reply_safety_validator.py` para bloquear riscos como “BLIF faz instalação” ou “instalação incluída” sem prova documental.
- UI da tarefa mostra o conhecimento usado, tipo de resposta e estado do LLM.

## Fluxo

```text
Tarefa / oportunidade
→ mensagem do cliente
→ recuperar conhecimento BLIF relevante
→ escolher template seguro sem anexo quando aplicável
→ opcionalmente pedir ao LLM para adaptar a redação
→ validar resposta
→ operador edita/confirma
→ ClientFlow envia no Chatwoot e regista timeline/communication
```

## Exemplo — Varisom

Mensagem do cliente:

```text
Presumo que o valor é sem instalação, pode por favor confirmar?
```

Antes:

```text
SEND_QUOTE → exige orçamento/anexo → bloqueia por falta de documento
```

Agora:

```text
Tópico detetado: instalação / âmbito do preço
Template: CLARIFY_INSTALLATION_SCOPE
Anexo: não necessário
Resposta: confirmar que o valor é do equipamento, sem instalação incluída, e indicar eletricista qualificado + suporte remoto
```

## Variáveis de ambiente

```env
CLIENTFLOW_REPLY_LLM_ENABLED=false
CLIENTFLOW_REPLY_LLM_MODEL=
CLIENTFLOW_REPLY_LLM_TEMPERATURE=0.2
CLIENTFLOW_REPLY_LLM_MAX_TOKENS=700
CLIENTFLOW_REPLY_LLM_TIMEOUT_SECONDS=20
CLIENTFLOW_REPLY_LLM_MAX_CONTEXT_CHARS=5000
OPENROUTER_API_KEY=...
OPENROUTER_MODEL=qwen/qwen3-30b-a3b
```

Com `CLIENTFLOW_REPLY_LLM_ENABLED=false`, o sistema continua a gerar rascunhos úteis com templates e conhecimento BLIF, sem chamada externa.

## Segurança comercial

O LLM, quando ativado, só adapta o texto. Não escolhe documentos, não decide preços finais, não confirma stock e não envia automaticamente.

O backend valida:

- documentos selecionados pertencem à oportunidade;
- mensagens com instalação incluída são bloqueadas se não houver prova;
- mensagens que sugerem instalação direta pela BLIF são bloqueadas;
- preços desconhecidos geram aviso;
- prazos devem ficar associados a confirmação de pagamento;
- valores com IVA sem documento geram aviso.

## Limites conhecidos

- A recuperação de conhecimento é por palavras-chave, não vector search. É suficiente para esta fase e transparente para validação.
- Não há fine-tuning.
- Preços e regras devem ser revistos/versionados quando mudarem.
- Stock, descontos e condições especiais continuam fora do LLM.

## Próximo passo recomendado

Criar um `Agent Builder TUI` apenas para administração/teste do conhecimento:

```text
- importar/editar conhecimento BLIF
- testar perguntas reais
- aprovar/rejeitar respostas
- versionar regras
- preparar exemplos para avaliação futura
```
