cidadao-ai-data

name: cidadao-ai-data description: Use ao integrar com fontes de dados governamentais brasileiras — Portal da Transparência, dados abertos federais, APIs do governo. Carrega routes federais (federal_apis, transparency, dados_gov), padrões de coverage, e padrões de hunting via agente Oxossi. Ative ao mexer em src/api/v1/dados_gov, src/api/routes/federal_apis, transparency.py, ou ao adicionar nova fonte de dados.

Cidadão.AI — Fontes de Dados

Plataforma de transparência depende de dados governamentais abertos. Aqui estão as integrações ativas e o padrão para adicionar novas.

Fontes ativas

Portal da Transparência

• Homepage: https://portaldatransparencia.gov.br
• API: https://api.portaldatransparencia.gov.br/
• Auth: chave de API (env var)
• Routes:
  • src/api/routes/transparency.py — endpoints de leitura
  • src/api/routes/transparency_coverage.py — métricas de cobertura
• Domínios cobertos: licitações, contratos, despesas, convênios, viagens, servidores

Dados.gov.br (Portal Brasileiro de Dados Abertos)

• Homepage: https://dados.gov.br
• API: CKAN
• Route versionada: src/api/v1/dados_gov.py
• Conteúdo: catálogos de datasets de todos os órgãos federais

APIs federais diversas

• Route: src/api/routes/federal_apis.py
• Inclui: Receita Federal, IBGE (geográfico), Banco Central (taxas/séries), e outros conforme demanda

Agente responsável por hunting

Oxóssi (src/agents/oxossi.py) é o "caçador de dados" — encarregado de descobrir/coletar/normalizar dados de fontes externas. Ao adicionar fonte nova, considerar se a coleta passa por Oxóssi (preferível) ou por route direta (apenas para queries sob demanda).

Padrão para adicionar fonte nova

1. Cliente: criar src/services/<fonte>_client.py com:
   • Class herda de base async client
   • Pool de conexões
   • Retry / circuit breaker via infrastructure/resilience.py
   • Rate limiting (respeitar limites do gov)
2. Schemas: src/schemas/<fonte>.py com Pydantic models das respostas
3. Service: lógica de transformação/agregação em src/services/
4. Route: endpoint exposto em src/api/routes/<fonte>.py ou agrupado em federal_apis.py
5. Cache: Redis via services/cache_service.py — TTL alinhado com cadência de atualização da fonte
6. Métrica de coverage: registrar em transparency_coverage.py se for fonte de transparência
7. Teste: tests/integration/test_<fonte>_client.py com mock de respostas

Padrões de cache

• Datasets estáticos (catálogo): TTL longo (24h+)
• Dados de licitação/contrato (mudam diariamente): TTL 6-12h
• Dados de cotação/IBGE série: TTL conforme cadência da fonte
• Cache key inclui versão do schema para invalidar quando o schema mudar

Coverage

• transparency_coverage.py mantém score de cobertura (% de órgãos federais com dados ingeridos)
• Métrica exposta em monitoring.py / Grafana
• Alvo: cobrir todos os ministérios + autarquias-chave

ML pipeline para dados ingeridos

• src/ml/ tem pipelines com scikit-learn, Prophet (séries temporais), UMAP + HDBSCAN (clustering)
• Disparados via src/api/routes/ml_pipeline.py
• Outputs alimentam Anita (analista) e Ceuci (predictive)

Anti-patterns

• ❌ Chamar API governamental direto da route — sempre via service client
• ❌ Cliente sem retry / circuit breaker — APIs do gov têm instabilidade conhecida
• ❌ Cache TTL estático sem considerar cadência da fonte
• ❌ Adicionar fonte sem cobertura em transparency_coverage
• ❌ Hardcodar chave de API no código — sempre env var
• ❌ Schema Pydantic permissivo demais (Any, Dict) — tipar com precisão
• ❌ Coletar dados sem passar pelo Oxóssi quando for ingestão batch

Referências externas

• Lei de Acesso à Informação (LAI): Lei 12.527/2011
• Marco da Inteligência Artificial: PL 2338/2023 (em tramitação)
• LGPD: Lei 13.709/2018 — atenção quando dados pessoais aparecerem