# PRD: Validação de Entity Type no Reflexion Pass

> Generated via /vibeflow:discover on 2026-03-20

## Problem

O LLM da extração classifica entity types errado quando mensagens mencionam muitas entidades de tipos diferentes juntas. Caso reportado pela equipe de integração: "Rio de Janeiro" foi classificado como `person` ao invés de `place`, enquanto outras cidades na mesma mensagem ("Botafogo", "Teresópolis") foram classificadas corretamente.

O reflexion pass já roda pós-extração como revisão de qualidade, mas hoje só valida completude (entidades faltantes), duplicatas, nomes truncados e merge de aliases. Ele **não valida entity types**.

Consequência: quem filtra entities por type (ex: "liste todas as pessoas que o usuário conhece") recebe resultados errados — cidades aparecendo como pessoas.

## Target Audience

Desenvolvedores integrando o SDK arandu que consomem entities filtradas por type.

## Proposed Solution

Adicionar validação de entity type ao reflexion pass (prompt). O reflexion já roda como segunda chamada LLM revisando a extração — basta incluir uma checagem explícita de que o type de cada entity é consistente com os facts e o contexto da mensagem.

Sem código novo. Mudança de prompt apenas.

## Success Criteria

- Dado uma mensagem que menciona cidades e pessoas juntas, o reflexion corrige entities com type errado (ex: "Rio de Janeiro" de `person` para `place`).
- Validado por teste que envia extração com type errado e verifica que o reflexion corrige.

## Scope v0

1. Atualizar `REFLEXION_SYSTEM_PROMPT` em `extract.py` para incluir validação de entity type como item 6 do checklist
2. Atualizar `ENTITY_SCAN_PROMPT` (multi-pass) para reforçar a importância da classificação correta de types
3. Teste que valida a correção de type pelo reflexion pass

## Anti-scope

- Validação heurística no código Python (regras de regex/NLP) — só se o prompt não resolver
- Correção de entities já persistidas no banco — ambiente de teste, vão resetar
- Mudança no `EXTRACTION_SYSTEM_PROMPT` principal (single-pass) — o prompt já lista os types; o problema não é falta de instrução, é erro do LLM que o reflexion deve pegar
- Mudança no entity resolution — types vêm da extração, resolution só herda
- Nova chamada LLM dedicada pra validação de types — o reflexion já existe, usar ele

## Technical Context

- `REFLEXION_SYSTEM_PROMPT` está em `src/arandu/write/extract.py:73-84` — checa 5 coisas hoje, nenhuma sobre entity type
- `ENTITY_SCAN_PROMPT` está em `src/arandu/write/extract.py:89-103` — lista types válidos mas não enfatiza importância
- `ExtractedEntity` em `constants.py` usa `Literal["person", "organization", "place", "pet", "other"]` — tipos já são restritos no Pydantic
- O reflexion pass (`_reflexion_pass()`) recebe a mensagem original + output da extração e retorna output corrigido — infraestrutura já existe
- Padrão de testes: `FakeLLMProvider` com respostas canned, sem DB

## Open Questions

None.
