Integrar spaCy para Extração de Entidades (NER)

[hermezus]

🧠 Contexto

A identificação de entidades sensíveis (nomes, cidades, datas, documentos, etc.) atualmente depende de regex e heurísticas em JavaScript, o que resulta em:

• Alto custo de manutenção
• Baixa compreensão semântica
• Falsos positivos em texto livre
• Dificuldade de evolução e treinamento

A proposta é integrar spaCy (Python) como motor de NLP/NER, mantendo o Node.js como camada de orquestração, com flexibilidade para execução local (STDIO) ou via HTTP (microserviço).

---

🎯 Objetivo

Introduzir um pipeline de NER baseado em spaCy, desacoplado da aplicação principal, com arquitetura flexível para:

• Execução local (Node → Python)
• Evolução futura para microserviço HTTP (FastAPI)
• Treinamento e extensão de entidades customizadas

---

🛠️ Escopo Técnico

• Implementar extração de entidades usando spaCy (pt_core_news_sm):

  • Pessoas (PERSON)
  • Localizações (LOC / GPE)
  • Datas (DATE)
  • Horários (TIME)

• Manter regras de regex para:

  • CPF / CNPJ
  • Emails
  • Telefones

• Criar camada de integração Node.js → spaCy com duas possibilidades:

  • 🔹 Execução local via STDIN/STDOUT
  • 🔹 Execução via HTTP (FastAPI) (feature flag / modo opcional)

• Padronizar retorno em JSON único

• Dockerizar solução (com opção de container único ou separado)

---

🧩 Arquitetura Proposta

[ Node.js ]
    |
    |  (opção A) STDIN / STDOUT
    |  (opção B) HTTP (FastAPI)
    v
[ spaCy (Python) ]

A escolha do modo de execução deve ser configurável e não impactar o contrato de saída.

---

🚀 Melhorias Esperadas

• Redução significativa de falsos positivos

• Melhor identificação de entidades compostas

• Pipeline único e extensível de NLP

• Código mais limpo e sustentável

• Base pronta para:

  • LGPD masking
  • Treinamento customizado
  • Escala horizontal via microserviço
  • Cache e batch processing

---

📦 Entregáveis

• Script Python de extração (ner.py)
• Integração Node.js (STDIO)
• Estrutura de API HTTP (FastAPI)
• docker-compose.yml funcional
• Documentação de uso e configuração
• Exemplo de entrada/saída

---

⚠️ Fora do Escopo (inicial)

• Treinamento customizado de modelo
• Auto-scale / load balancer
• Persistência de dados
• Monitoramento (Prometheus, etc.)

---

🧪 Critérios de Aceite

• Texto livre retorna entidades corretas em JSON

• Nenhuma regressão nas regras atuais de regex

• Execução possível via:

  • STDIO ou
  • HTTP

• Ambiente sobe via docker compose up

• Contrato de saída único e estável

---

🔮 Evoluções Futuras (não bloqueantes)

• FastAPI como padrão
• Treinamento incremental spaCy
• Cache
• Mascaramento automático de dados sensíveis
• Métricas de precisão

---