openaudit-entity-catalog (CLI)

CLI em Python para construir, validar e publicar o Catálogo Canônico de Entidades do OpenAudit Brasil.

Este repositório é responsável por compilar um catálogo pesquisável (ex.: políticos) a partir de fontes oficiais, gerando artefatos versionados consumíveis pelo openaudit-search-api (Node.js), com foco em:

modularidade (plug-and-play)
auditabilidade (proveniência + hashes + versões)
performance (processamento eficiente com formatos colunares/SQLite)
segurança (minimização e ausência de PII sensível no MVP)

Importante: este projeto não executa cruzamento de fontes, não calcula indicadores e não produz conclusões.
Ele apenas mantém o registro canônico de entidades e o índice local para busca rápida e desambiguação humana.

Índice

Objetivo
O que este repositório é (e não é)
Artefatos gerados
Arquitetura (alto nível)
Fluxo de build
CLI: comandos
Modelo de dados
- Schema SQLite
- catalog_meta.json
Regras de qualidade (QA)
Política de privacidade e minimização
Guia de implementação para desenvolvedores
Estrutura do repositório
Setup e execução local
Publicação de releases
Integração com openaudit-search-api
Boas práticas e regras de contribuição
Licença

Objetivo

Construir um catálogo canônico e auditável de entidades pesquisáveis, gerando:

SQLite com FTS5 (full-text search) para consumo rápido no openaudit-search-api
Snapshot tabular (Parquet/JSONL opcional) para auditoria/reprocessamento
Metadados (catalog_meta.json) com:
- versão do catálogo
- fonte(s) utilizadas
- timestamp da coleta/build
- hashes e contagens
- versão do schema e do pipeline

O que este repositório é (e não é)

✅ É

Um CLI builder (ferramenta de build) do catálogo
Um pipeline determinístico de:
- ingestão (fontes de catálogo)
- normalização (nome/aliases/contexto)
- dedupe conservador (quando aplicável)
- QA (validações)
- export (SQLite + meta + hashes)

❌ Não é

Um serviço HTTP
Um motor de indicadores/anomalias
Um "sistema de investigação”
Um lugar para guardar ou exportar dados sensíveis (ex.: CPF) no MVP

Artefatos gerados

Cada build produz um diretório de release como:


dist/
2026-02-28/
catalog.sqlite
catalog_meta.json
entities.parquet           # opcional (recomendado para auditoria)
qa_report.json
checksums.sha256

`catalog.sqlite` (obrigatório)

Banco SQLite read-only para o runtime de busca
Contém tabela entities + índice FTS5 para busca por nome/aliases
Ideal para performance e simplicidade operacional

`catalog_meta.json` (obrigatório)

Registro de proveniência, versões e hashes (ver seção própria)

`entities.parquet` (opcional, recomendado)

Snapshot tabular do catálogo final (auditoria e reprocessamento)
Permite auditoria externa sem depender do SQLite

Arquitetura (alto nível)

Pipeline do catálogo:

Source (fonte oficial) → ingestão
Normalize → padronização de nomes, UF, cargo etc.
Canonicalize → gerar entity_id canônico + normalized_name
Dedupe (conservador) → apenas quando houver chave determinística confiável
QA → checks mínimos (integridade/duplicidade/domínio)
Export → SQLite (FTS5) + meta + hashes (+ Parquet opcional)

Contrato com o search-api:

o search-api não "adivinha” campos: ele lê catalog.sqlite e catalog_meta.json
o catálogo é versionado e auditável (ex.: headers X-Catalog-Version)

Fluxo de build

Defina CATALOG_VERSION (ex.: 2026-02-28)
Execute build para gerar staging e catálogo final
Execute validate para gerar qa_report.json
Execute export para gerar SQLite/FTS5 e metadados
Publique artefatos (GitHub Release)

CLI: comandos

Nome do binário sugerido: openaudit-catalog

`build`

Constrói o catálogo a partir de uma ou mais fontes.

Exemplo:

openaudit-catalog build \
  --source tse_candidates \
  --catalog-version 2026-02-28 \
  --out ./dist/2026-02-28

`validate`

Roda checks de qualidade e gera qa_report.json.

openaudit-catalog validate \
  --path ./dist/2026-02-28

`export`

Gera SQLite + FTS5 (e opcionalmente Parquet).

openaudit-catalog export \
  --path ./dist/2026-02-28 \
  --format sqlite,parquet

`checksum`

Gera checksums.sha256 dos artefatos.

openaudit-catalog checksum \
  --path ./dist/2026-02-28

`inspect`

Mostra estatísticas rápidas do catálogo (contagens e versões).

openaudit-catalog inspect \
  --path ./dist/2026-02-28

Observação: os comandos e flags acima definem o contrato esperado do projeto. Se você ainda não implementou, mantenha o README como especificação e implemente conforme descrito.

Modelo de dados

Schema SQLite

Tabela: `entities`

Campos mínimos (MVP):

entity_id (TEXT, PRIMARY KEY) ID canônico estável (ex.: tse:SQ_CANDIDATO:123)
entity_type (TEXT) person (MVP), expansão futura: org
display_name (TEXT) Nome para exibição
normalized_name (TEXT) Nome normalizado para matching e filtros
aliases_json (TEXT) JSON array de aliases (opcional)
context_uf (TEXT) UF (quando disponível)
context_role (TEXT) Cargo/posição (quando disponível)
context_year (INTEGER) Ano (quando aplicável)
source_primary (TEXT) Fonte principal do registro
source_ref (TEXT) ID original na fonte (se existir)
updated_at (TEXT) Timestamp ISO8601

Índices recomendados:

INDEX entities_context_uf
INDEX entities_context_role
INDEX entities_context_year

FTS5: `entities_fts`

indexa display_name, normalized_name e aliases concatenados
mantém referência para entity_id

Exemplo (conceitual):

entities_fts(entity_id, text)
text = display_name + " " + normalized_name + " " + aliases

Importante: o catálogo deve ser consumível em read-only.

`catalog_meta.json`

Arquivo obrigatório com metadados e proveniência.

Exemplo:

{
  "name": "openaudit-entity-catalog",
  "catalog_version": "2026-02-28",
  "snapshot_id": "cat:2026-02-28T03:00:00Z",
  "schema_version": "1.0.0",
  "build_version": "0.1.0",
  "collected_at": "2026-02-28T03:00:00Z",
  "sources": [
    {
      "name": "TSE",
      "dataset": "candidaturas",
      "source_url": "https://dadosabertos.tse.jus.br/",
      "collected_at": "2026-02-28T02:40:00Z",
      "hash": "sha256:..."
    }
  ],
  "artifacts": [
    { "file": "catalog.sqlite", "hash": "sha256:...", "rows": 123456 },
    { "file": "entities.parquet", "hash": "sha256:...", "rows": 123456 }
  ],
  "qa": {
    "report_file": "qa_report.json",
    "passed": true,
    "checks_failed": 0
  }
}

Regras de qualidade (QA)

O catálogo é "infra de identidade”. Se ele estiver errado, todo o resto erra.

Checks mínimos obrigatórios no MVP:

entity_id não nulo e único
display_name não nulo
normalized_name não nulo
validade de context_uf quando presente (2 letras)
contagem mínima de registros (para detectar build quebrado)
duplicatas suspeitas (mesmo nome + UF + cargo + ano) devem gerar alerta (não bloqueio automático)

A saída deve gerar:

qa_report.json (com severidade e detalhes)
status final passed / failed (build falha se checks críticos falharem)

Política de privacidade e minimização

Não incluir CPF no catálogo do MVP.
Não incluir endereços, telefones, e-mails, dados familiares.
Manter somente o necessário para:
- busca textual
- contexto mínimo de desambiguação

Fixtures e testes devem usar dados sintéticos (não pessoas reais).

Guia de implementação para desenvolvedores

Como adicionar uma nova fonte

Criar um módulo em sources/<nome_da_fonte>/
Implementar:
- fetch() → obtém os dados (respeitando termos de uso)
- parse() → transforma para um dataframe normalizado (colunas padrão)
- map_to_entities() → gera registros no schema canônico
Documentar a fonte em docs/sources/<fonte>.md:
- URL oficial
- termos/licença
- campos usados
- riscos (schema instável, atraso, etc.)
Adicionar testes:
- fixtures sintéticas
- validações de colunas obrigatórias
- regressão básica de contagem

Regra: nenhuma fonte entra sem documentação e QA mínimo.

Como adicionar um novo campo ao catálogo

Atualizar schema (SQLite + parquet)
Atualizar schema_version
Atualizar export (FTS pode precisar incluir novo campo)
Atualizar search-api (se o novo campo for retornado em context)
Adicionar testes de regressão

Como adicionar uma nova regra de QA

Criar check em qa/checks/*.py
Definir severidade:
- critical → falha build
- warning → alerta (não falha)
Incluir no validate e no qa_report.json

Estrutura do repositório

Sugestão:

.
├─ openaudit_catalog/
│  ├─ cli.py                  # entrypoint da CLI (Typer/Click)
│  ├─ config.py               # configs e defaults
│  ├─ sources/                # fontes de catálogo
│  │  └─ tse_candidates/
│  │     ├─ fetch.py
│  │     ├─ parse.py
│  │     └─ mapping.py
│  ├─ transform/
│  │  ├─ normalize.py         # normalização de nomes, uf, etc.
│  │  └─ dedupe.py            # dedupe conservador
│  ├─ qa/
│  │  ├─ runner.py
│  │  └─ checks/
│  ├─ export/
│  │  ├─ sqlite_fts.py
│  │  ├─ parquet.py
│  │  └─ meta.py
│  └─ utils/
│     ├─ hashing.py
│     └─ time.py
├─ docs/
│  ├─ schema.md
│  └─ sources/
├─ dist/                      # outputs locais (não commitar)
├─ tests/
│  └─ fixtures/
├─ pyproject.toml
└─ README.md

Setup e execução local

Pré-requisitos

Python 3.11+
(recomendado) uv ou poetry
SQLite com FTS5 (padrão em builds modernos)

Instalação (exemplo com `uv`)

uv venv
source .venv/bin/activate
uv pip install -e .

Rodar build + validate + export

openaudit-catalog build --source tse_candidates --catalog-version 2026-02-28 --out ./dist/2026-02-28
openaudit-catalog validate --path ./dist/2026-02-28
openaudit-catalog export --path ./dist/2026-02-28 --format sqlite,parquet
openaudit-catalog checksum --path ./dist/2026-02-28

Publicação de releases

Recomendação:

Publicar dist/<version>/ como GitHub Release (assets).
O search-api deve baixar/instalar o catálogo por versão (ou montar via volume).

Artefatos mínimos para release:

catalog.sqlite
catalog_meta.json
checksums.sha256

Integração com openaudit-search-api

O openaudit-search-api (Node) deve receber por configuração:

CATALOG_DB_PATH=/path/catalog.sqlite
CATALOG_META_PATH=/path/catalog_meta.json

A API deve:

ler catalog_version e expor X-Catalog-Version
usar SQLite em modo read-only
usar FTS5 para busca por q
retornar confidence + explanation

Boas práticas e regras de contribuição

Não adicionar dados pessoais em exemplos, docs ou fixtures.
Toda fonte nova deve incluir:
- documentação
- QA mínimo
- meta + hashes
Toda mudança de schema exige bump de versão e teste de regressão.
Sem "enriquecimento" não rastreável.

Licença

Consulte LICENSE na organização:

LICENSE

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
README.md		README.md

Folders and files

Latest commit

History

Repository files navigation

openaudit-entity-catalog (CLI)

Índice

Objetivo

O que este repositório é (e não é)

✅ É

❌ Não é

Artefatos gerados

catalog.sqlite (obrigatório)

catalog_meta.json (obrigatório)

entities.parquet (opcional, recomendado)

Arquitetura (alto nível)

Fluxo de build

CLI: comandos

build

validate

export

checksum

inspect

Modelo de dados

Schema SQLite

Tabela: entities

FTS5: entities_fts

catalog_meta.json

Regras de qualidade (QA)

Política de privacidade e minimização

Guia de implementação para desenvolvedores

Como adicionar uma nova fonte

Como adicionar um novo campo ao catálogo

Como adicionar uma nova regra de QA

Estrutura do repositório

Setup e execução local

Pré-requisitos

Instalação (exemplo com uv)

Rodar build + validate + export

Publicação de releases

Integração com openaudit-search-api

Boas práticas e regras de contribuição

Licença

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

`catalog.sqlite` (obrigatório)

`catalog_meta.json` (obrigatório)

`entities.parquet` (opcional, recomendado)

`build`

`validate`

`export`

`checksum`

`inspect`

Tabela: `entities`

FTS5: `entities_fts`

`catalog_meta.json`

Instalação (exemplo com `uv`)

Packages