NALU/Prompt2.md

# Prompt 2 — NALU AI: Validadores adicionais + MCP Server

> **Pré-requisito:** o projeto do Prompt 1 já está funcionando com `POST /v1/extract/name` e o validador `validate_full_name.md`.

---

## Parte A — Novos validadores + endpoints

Para cada validador abaixo:
1. Criar o arquivo `.md` em `Validators/` seguindo o mesmo formato de `validate_full_name.md`
2. Registrar o endpoint em `ExtractEndpoints.cs` (2 linhas, mesmo padrão)
3. Criar pós-processadores e enrichers necessários

### 1. `validate_cpf.md` → `POST /v1/extract/cpf`

Extrai e valida CPF (11 dígitos, algoritmo mod 11).

**Config MCP:**
- mcp_tool: nalu_extract_cpf
- mcp_description: Extrai e valida o CPF do usuário. Valida dígitos verificadores automaticamente. Se certain=true, o CPF é válido e pode ser usado. Se certain=false, use suggestion_to_agent para pedir correção.

**Regras determinísticas:**
- Aceitar: `123.456.789-09`, `12345678909`, `123 456 789 09`
- Rejeitar sequências repetidas: `111.111.111-11`, `000.000.000-00`, etc.
- Validar dígitos verificadores (mod 11)
- Rejeitar se não tiver exatamente 11 dígitos numéricos

**Prompt LLM:** extrair CPF mesmo quando informal ("meu cpf é um dois três quatro...") ou no meio de frase longa.

**Few-shot (mínimo 5):**
- CPF válido direto
- CPF no meio de frase
- CPF com dígito errado
- Resposta evasiva ("não lembro")
- CPF escrito por extenso

**Pós-processador:** `ValidateCpfDigit` — validar mod 11, formatar `XXX.XXX.XXX-XX`

**Sugestões:**
- when_null_evasive: "Preciso do seu CPF para continuar. São 11 dígitos, pode digitar?"
- when_invalid: "Esse CPF parece estar incorreto. Pode verificar e digitar novamente?"
- when_uncertain: "Só confirmando: seu CPF é {{extracted_value}}?"

---

### 2. `validate_cep.md` → `POST /v1/extract/cep`

Extrai CEP (8 dígitos) e enriquece com endereço via ViaCEP.

**Config MCP:**
- mcp_tool: nalu_extract_cep
- mcp_description: Extrai o CEP do usuário e retorna o endereço completo (logradouro, bairro, cidade, estado). Se certain=true, o endereço está confirmado. Se obtained=false, o CEP é inválido — use suggestion_to_agent.

**Regras determinísticas:**
- Aceitar: `01001-000`, `01001000`
- Rejeitar se não tiver 8 dígitos
- Rejeitar `00000-000`

**Enricher:** `ViaCepEnricher`
- Chamar `https://viacep.com.br/ws/{cep}/json/`
- Se retornar `erro: true`, marcar obtained: false
- Fallback: `https://brasilapi.com.br/api/cep/v2/{cep}`

**extracted_value quando enriquecido:**
```json
{
  "cep": "01001-000",
  "logradouro": "Praça da Sé",
  "bairro": "Sé",
  "cidade": "São Paulo",
  "estado": "SP"
}
```

**Sugestões:**
- when_invalid: "Esse CEP não parece válido. Pode verificar? Formato: XXXXX-XXX"
- when_enriched_certain: "Encontrei: {{logradouro}}, {{bairro}} — {{cidade}}/{{estado}}. Correto?"
- when_not_found: "Não encontrei esse CEP. Pode verificar e digitar novamente?"

---

### 3. `validate_phone_br.md` → `POST /v1/extract/phone`

Extrai telefone brasileiro com DDD.

**Config MCP:**
- mcp_tool: nalu_extract_phone
- mcp_description: Extrai o número de telefone brasileiro do usuário, incluindo DDD. Formata automaticamente. Se certain=true, o número é válido.

**Regras determinísticas:**
- Aceitar: `(11) 99999-9999`, `11999999999`, `+55 11 99999-9999`, `11 99999 9999`
- DDD válido: 11-99
- Celular: 9 dígitos começando com 9
- Fixo: 8 dígitos começando com 2-5

**Pós-processador:** `FormatPhone` — normalizar para `(XX) XXXXX-XXXX` ou `(XX) XXXX-XXXX`

**Sugestões:**
- when_invalid: "Não consegui identificar o telefone. Pode digitar com DDD? Ex: (11) 99999-9999"
- when_uncertain: "Seu telefone é {{extracted_value}}? Pode confirmar?"

---

### 4. `validate_email.md` → `POST /v1/extract/email`

Extrai email com correção de typos.

**Config MCP:**
- mcp_tool: nalu_extract_email
- mcp_description: Extrai o email do usuário com correção automática de typos em domínios comuns (gmail, hotmail, outlook). Se houve correção, certain=false para o agente confirmar.

**Regras determinísticas:**
- Regex de email
- Rejeitar sem @ ou sem ponto após @

**Pós-processador:** `CorrectEmailTypos`
- `gmail.com.br` → `gmail.com`
- `gamil.com`, `gmaill.com`, `gnail.com` → `gmail.com`
- `hotmal.com`, `hotmial.com` → `hotmail.com`
- `outlok.com` → `outlook.com`
- `yaho.com` → `yahoo.com`

Se corrigiu: certain=false, guardar original para a sugestão.

**Sugestões:**
- when_corrected: "Seu email é {{extracted_value}}? (notamos um possível erro em '{{original}}')"
- when_invalid: "Não parece um email válido. Pode digitar novamente?"

---

### 5. `validate_yes_no.md` → `POST /v1/extract/yes-no`

Detecta sim/não.

**Config MCP:**
- mcp_tool: nalu_extract_yes_no
- mcp_description: Detecta se o usuário respondeu sim ou não. Retorna true (sim), false (não), ou null (ambíguo). Ideal para confirmações. Se ambíguo, use suggestion_to_agent para re-perguntar.

**Regras determinísticas:**
- Sim: sim, s, ss, yes, si, pode, claro, com certeza, bora, vamos, isso, exato, beleza, blz, ok, tá, aham, uhum, positivo, aceito, quero, concordo, fechado, feito, show, top, massa, dale
- Não: não, nao, n, no, nope, nada, nunca, jamais, nem, negativo, recuso, discordo, não quero, de jeito nenhum

Quando ambíguo → LLM interpreta com contexto.

**extracted_value:** `true`, `false`, ou `null`

**Sugestões:**
- when_ambiguous: "Desculpa, não entendi. Pode responder sim ou não?"

---

## Parte B — MCP Server

Adicionar MCP ao mesmo projeto ASP.NET Core, expondo cada validador como uma tool.

### Transporte
**Streamable HTTP** no endpoint `/mcp`.

### Tools registradas

Cada validador gera uma tool MCP automaticamente, usando os campos `mcp_tool` e `mcp_description` do seu arquivo `.md`:

```
nalu_extract_name     — parâmetros: agent_input, user_input, agent_context?, language?
nalu_extract_cpf      — parâmetros: agent_input, user_input, agent_context?, language?
nalu_extract_cep      — parâmetros: agent_input, user_input, agent_context?, language?
nalu_extract_phone    — parâmetros: agent_input, user_input, agent_context?, language?
nalu_extract_email    — parâmetros: agent_input, user_input, agent_context?, language?
nalu_extract_yes_no   — parâmetros: agent_input, user_input, agent_context?, language?
```

Todos compartilham os mesmos parâmetros de entrada e o mesmo formato de resposta. Internamente, cada tool chama `ExtractionPipeline.ExecuteAsync(validator_id, request)`.

### Registro dinâmico de tools

O MCP server deve gerar a lista de tools **automaticamente** a partir dos arquivos `.md` na pasta `Validators/`. Quando um novo `.md` é adicionado com as configs `mcp_tool` e `mcp_description`, ele aparece automaticamente em `tools/list`.

### Instrução para o agente consumidor

Incluir no `mcp_description` de cada tool:
> Se `certain: true`, aceite o `extracted_value` e prossiga para o próximo passo.
> Se `certain: false` e `suggestion_to_agent` não é null, use a sugestão como próxima mensagem ao usuário.
> Se `obtained: false`, use a sugestão para re-pedir o dado ao usuário.

### Auth
- API key via `Authorization: Bearer {key}` no header HTTP
- Mesma validação de auth e rate limit do REST

### Implementação

Verificar se existe pacote NuGet `ModelContextProtocol` maduro para C#. Se sim, usá-lo. Se não, implementar manualmente:
- Endpoint POST `/mcp` (Streamable HTTP)
- Responder a `initialize`, `tools/list`, `tools/call`
- JSON-RPC 2.0
- Content-Type: `application/json`

### Arquivo de setup para devs

Criar `mcp-config.json` na raiz para facilitar conexão:

```json
{
  "mcpServers": {
    "nalu": {
      "url": "http://localhost:5000/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

### Testes MCP

- Teste que simula `tools/list` e verifica que todas as tools estão listadas
- Teste que chama `tools/call` no `nalu_extract_name` e verifica a resposta
- Teste que verifica que um novo `.md` adicionado aparece em `tools/list`

---

## Resumo de arquivos a criar/modificar

### Criar:
- `Validators/validate_cpf.md`
- `Validators/validate_cep.md`
- `Validators/validate_phone_br.md`
- `Validators/validate_email.md`
- `Validators/validate_yes_no.md`
- `PostProcessors/ValidateCpfDigit.cs`
- `PostProcessors/FormatPhone.cs`
- `PostProcessors/CorrectEmailTypos.cs`
- `Enrichers/ViaCepEnricher.cs`
- `Mcp/NaluMcpServer.cs` (ou equivalente)
- `mcp-config.json`
- Testes para os novos validadores e MCP

### Modificar:
- `ExtractEndpoints.cs` — adicionar 5 novos endpoints
- `PostProcessorRegistry.cs` — registrar novos processadores
- `EnrichmentService.cs` — registrar ViaCepEnricher
- `Program.cs` — registrar MCP server e novos serviços