Skip to content

v0.3.0 — Cross-source CNPJ resolver

Choose a tag to compare

View all tags
@robertoecf robertoecf released this 28 Apr 23:10
· 97 commits to main since this release
v0.3.0
78224ec

Sprint 5 — Cross-source CNPJ resolver via embedded registry

Um catálogo SQLite FTS5 (~50k entidades) embarcado direto no wheel. Uma única chamada MATCH resolve qualquer formato de identificador brasileiro:

from findata.registry import lookup

await lookup("33000167000101")         # CNPJ raw
await lookup("33.000.167/0001-01")     # CNPJ com máscara
await lookup("PETR4")                  # ticker B3
await lookup("9512")                   # cod_cvm
await lookup("petrobras")              # nome (fuzzy via BM25)

O Entity.rank (BM25) discrimina match exato (~ -10) de match difuso (~ -2), útil pra agentes / consumers decidirem confiança.

Highlights
Entidades indexadas ~50.000 (CVM companies + funds + SUSEP, com tickers B3)
Tamanho do wheel 4.2 MB compactado (28 MB descompactado)
Build time ~5 segundos contra BCB/CVM/SUSEP/B3 ao vivo
Tests 117 → 168 (+51 novos)
REST routes 73 → 75 (+2: /registry/lookup, /registry/meta)
MCP tools Auto-expostos via fastapi-mcp

Sprint 5.5 (paralelo)

  • BCB SGS catalog expandido de 17 → 71 séries nomeadas: inflação detalhada (livres / monitorados / serviços / bens / núcleos), agregados monetários (M1–M4), crédito (saldo SFN, inadimplência, spread), setor externo (balança, conta corrente, IDP, reservas), setor público (DBGG, primário, juros nominais), confiança (ICC FGV, ICEI CNI), e mais.
  • ANBIMA IMA história: get_ima_history(family, start, end) — fetch via formulário "Série Histórica", validado contra 14 anos de dados.

CLI

findata registry lookup 33000167000101    # CNPJ raw
findata registry lookup PETR4             # ticker B3
findata registry lookup "porto seguro"    # nome
findata registry meta                     # build sha + counts

REST

curl 'http://localhost:8000/registry/lookup?q=33000167000101'
curl 'http://localhost:8000/registry/lookup?q=PETR4&limit=5'
curl 'http://localhost:8000/registry/meta'

Arquitetura

  • 1 tabela FTS5 (entities com searchable + payload UNINDEXED). Simplicidade brutal — minimalista vs. as 5 tabelas que esbocei na primeira iteração.
  • (spaced) OR (joined) na normalização da query — CNPJ com ou sem máscara resolvem o mesmo, multi-word names também.
  • Wheel-embedded SQLite atualizada semanalmente via CI cron (.github/workflows/rebuild-registry.yml), abre PR se conteúdo mudou (human-in-the-loop, nunca auto-merge).

Limitações conhecidas (v1)

  • B3 ticker enrichment via match exato de nome falha quando B3 escreve nome_ativo colado ("ITAUUNIBANCO") e CVM separa ("ITAU UNIBANCO"). v2: fuzzy match.
  • CVM funds dataset dominado por CANCELADA (46.566 de 46.810); upstream parece ser legacy. Filtro disponível via extra.situacao no payload.
  • Mesma legal entity pode aparecer com múltiplos cod_cvm, gerando duplicatas. v2: dedupe on CNPJ at build time.

Quickstart

pip install findata-br==0.3.0
findata registry lookup 33000167000101

🤖 Generated with Claude Code

Assets 2
Loading