Normalização/canonicalização de entidades (NER) — facets, filtros e páginas de entidade

[nitaibezerra]

Contexto

As entidades nomeadas (NER) extraídas via LLM são armazenadas em news_features.features.entities como texto bruto e indexadas no Typesense (entities, entity_org|per|loc|misc) — ver #174 (Fase 0). São consumidas pelo graphql-api (entitySuggestions, filtro ArticleFilter.entities) e pelo portal (filtro na /busca, páginas /entidades/[slug], chips na tela da notícia).

Problema: sem canonicalização, a mesma entidade aparece como facets distintos. Exemplo real observado em produção:

• Finep (40)
• Financiadora de Estudos e Projetos (Finep) (14)
• Financiadora de Estudos e Projetos (FINEP) (4)

Isso fragmenta contagens, polui o typeahead, duplica páginas de entidade e enfraquece o filtro/navegação cruzada.

Objetivo

Canonicalizar entidades para que variações (acrônimos, com/sem razão social, caixa, acentos, pontuação) colapsem numa entidade canônica única — melhorando facets, filtro, typeahead e páginas /entidades.

Abordagens a avaliar

• Mapa de aliases + matching determinístico (acrônimo↔nome; normalização de caixa/acento/pontuação), versionado e reprocessável sobre os news_features existentes (sem re-rodar o LLM).
• Cross-ref com a tabela agencies (158 órgãos com nomes canônicos) para canonicalizar instituições (ORG) governamentais.
• (Complementar) melhorar a extração no enrichment (data-science/news_enrichment) com entity linking / nome canônico no prompt.
• Definir o ponto de aplicação: novo campo entities_canonical na feature layer e/ou normalização em extract_entity_fields/indexing do Typesense.

Critérios de aceite

• Variações conhecidas (ex.: Finep) colapsam numa entidade canônica nos facets/entitySuggestions.
• Pipeline reprocessável (backfill dos ~19,5k artigos com entidades) sem re-rodar LLM.
• Filtro entities, typeahead e /entidades/[slug] passam a usar o valor canônico.
• Métrica antes/depois: redução do nº de facets distintos para entidades-âncora.

Referências

• Fase 0 (indexação de entidades): feat: indexa entidades e view_count no Typesense #174
• Consumo: graphql-api entitySuggestions / ArticleFilter.entities; portal /entidades/[slug] + filtro na /busca.
• v1 atual = match por texto bruto (decisão consciente; este issue é o fast-follow planejado).

[nitaibezerra]

Atualização — escopo ampliado implementado e mergeado (2026-06-10)

A issue foi ampliada de "normalização" para uma evolução completa do identificador de entidades: além da canonicalização, agora extrai Eventos e Políticas públicas (antes perdidos no depósito MISC), com linked data (Wikidata QID) como chave de dedup (orientado a futuro Neo4j) e uma lente semântica que marca entidades inline no texto.

Arquitetura

Separação menção ↔ canônico. Menções em news_features ganham forma_canonica/salience/canonical_id; canônicos viram nós em entity_registry (id = QID Wikidata quando linkado, senão dgb_<slug>); entity_alias = resolver determinístico (reprocessável-sem-LLM). Canonicalização LLM-first: gazetteer (159 órgãos semeados de agencies) → Opus 4.8 → Wikidata → gates de confiança + escalada contextual p/ PER/homônimos (guard Saúde BR vs estrangeira).

PRs (todos mergeados)

• data-platform#179 — fundação (migrações 015–020), Typesense, offsets da lente
• Evolução do extrator NER + pipeline de canonicalização (Fases 2–3 de data-platform#178) data-science#26 (issue irmã Evolução do extrator NER + canonicalização de entidades (Fases 2–3 de data-platform#178) data-science#27) — extrator NER + canonicalização
• Canonicalização de entidades + lente semântica (Fases 4–5 de data-platform#178) graphql-api#18 — entity(id), canonicalId, entityCanonical, contentAnnotations
• Entidades canônicas, grupos Eventos/Políticas e lente semântica (data-platform#178) portal#265 (→ development) — chips Eventos/Políticas, páginas de entidade canônicas, SemanticLens

~1.7k testes no total; revisão adversarial em cada onda (bug crítico de offsets NFD + colisão de alias corrigidos).

Gates restantes

1. CI deploys (em curso pós-merge); migrações via db-migrate.yaml + schema Typesense via typesense-schema-update.yaml (disparados).
2. NER_MODEL_ID=Sonnet 4.6 e CANON_MODEL_ID=Opus 4.8 via Terraform (infra) — TODO com placeholder seguro no código.
3. Reprocessamento de ~1 mês (job resumível) → validar → backfill gradual.