README.md

metadata

title: Cidadão.AI Models
emoji: 🤖
colorFrom: blue
colorTo: green
sdk: docker
app_port: 8001
pinned: false
license: mit
tags:
  - transparency
  - government
  - brazil
  - anomaly-detection
  - fastapi

🤖 Cidadão.AI Models

Modelos especializados de Machine Learning para análise de transparência pública brasileira

🎯 Visão Geral

Cidadão.AI Models é o repositório especializado em modelos de machine learning para o ecossistema Cidadão.AI. Contém modelos customizados, pipeline de treinamento MLOps e infraestrutura de inferência para análise avançada de dados de transparência pública.

🚀 Capacidades Principais

• 🔍 Detecção de Anomalias - Identificação automática de padrões suspeitos em contratos públicos
• 📊 Análise de Padrões - Reconhecimento de correlações e tendências em dados governamentais
• 🌊 Análise Espectral - Detecção de padrões temporais e sazonais via FFT
• 🤖 Modelos Customizados - Arquiteturas especializadas para transparência brasileira
• 🔄 Pipeline MLOps - Treinamento, versionamento e deploy automatizados

🏗️ Arquitetura

src/
├── models/                     # Modelos de ML especializados
│   ├── anomaly_detection/      # Detecção de anomalias
│   ├── pattern_analysis/       # Análise de padrões
│   ├── spectral_analysis/      # Análise espectral
│   └── core/                   # Classes base e utilitários
├── training/                   # Pipeline de treinamento
│   ├── pipelines/              # Pipelines de treinamento
│   ├── configs/                # Configurações de modelos
│   └── utils/                  # Utilitários de treinamento
├── inference/                  # Servidor de inferência
│   ├── api_server.py           # FastAPI server
│   ├── batch_processor.py      # Processamento em lote
│   └── streaming.py            # Inferência em tempo real
└── deployment/                 # Ferramentas de deploy
    ├── huggingface/            # Integração HuggingFace Hub
    ├── docker/                 # Containerização
    └── monitoring/             # Monitoramento de modelos

🚀 Quick Start

Instalação

# Clone o repositório
git clone https://github.com/anderson-ufrj/cidadao.ai-models
cd cidadao.ai-models

# Instale as dependências
pip install -r requirements.txt

# Instale o pacote em modo desenvolvimento
pip install -e .

Uso Básico

from cidadao_models.models.anomaly_detection import AnomalyDetector
from cidadao_models.models.pattern_analysis import PatternAnalyzer

# Inicializar modelos
anomaly_detector = AnomalyDetector()
pattern_analyzer = PatternAnalyzer()

# Analisar contratos para anomalias
contracts = [...]  # Lista de contratos
anomalies = anomaly_detector.analyze(contracts)

# Analisar padrões temporais
patterns = pattern_analyzer.analyze_temporal_patterns(data)

Servidor de Inferência

# Iniciar servidor API
uvicorn src.inference.api_server:app --host 0.0.0.0 --port 8001

# Testar endpoint
curl -X POST "http://localhost:8001/v1/detect-anomalies" \
     -H "Content-Type: application/json" \
     -d '{"contracts": [...]}'

🧠 Modelos Disponíveis

🔍 Detector de Anomalias

• Algoritmos: Isolation Forest, One-Class SVM, Local Outlier Factor
• Especialização: Contratos públicos brasileiros
• Métricas: Precisão >90% para anomalias críticas

📊 Analisador de Padrões

• Capacidades: Time series, correlações, clustering
• Técnicas: Prophet, FFT, decomposição sazonal
• Output: Padrões temporais e insights explicáveis

🌊 Analisador Espectral

• Método: Transformada rápida de Fourier (FFT)
• Detecção: Padrões periódicos suspeitos
• Aplicação: Irregularidades sazonais em gastos

🛠️ Desenvolvimento

Estrutura de Testes

# Executar todos os testes
pytest tests/

# Testes específicos
pytest tests/unit/models/
pytest tests/integration/
pytest tests/e2e/

Treinamento de Modelos

# Treinar modelo de detecção de corrupção
python src/training/pipelines/train_corruption_detector.py --config configs/corruption_bert.yaml

# Avaliar performance
python src/training/evaluate.py --model corruption_detector --test_data data/test.json

Deploy HuggingFace

# Upload para HuggingFace Hub
python src/deployment/huggingface/upload.py --model_path models/anomaly_detector --repo_name cidadao-ai/anomaly-detector

🔄 Integração com Backend

Este repositório se integra com o cidadao.ai-backend através de:

• API REST: Servidor de inferência FastAPI
• Package Integration: Importação direta como dependência
• Fallback Local: Processamento local se API indisponível

# No backend
from src.tools.models_client import ModelsClient

client = ModelsClient("http://models-api:8001")
results = await client.detect_anomalies(contracts)

📊 MLOps Pipeline

Treinamento Automatizado

• ⚡ CI/CD: Pipeline automatizado GitHub Actions
• 📈 Experiment Tracking: MLflow + Weights & Biases
• 🔄 Model Versioning: HuggingFace Hub integration
• 📊 Performance Monitoring: Drift detection + alerting

Deployment

• 🐳 Containerização: Docker para produção
• 🤗 HuggingFace Spaces: Demo models deployment
• 🚀 Kubernetes: Orquestração escalável
• 📡 Monitoring: Prometheus metrics + Grafana dashboards

🔗 Links Relacionados

• 🏛️ Backend: cidadao.ai-backend
• 🎨 Frontend: cidadao.ai-frontend
• 📚 Documentação: cidadao.ai-docs
• 🤗 HuggingFace: cidadao-ai organization

📈 Status do Projeto

• ✅ Estrutura Base: Completa
• 🔄 Migração ML: Em andamento
• ⏳ API Server: Planejado
• ⏳ HF Integration: Próximo

👨‍💻 Contribuição

1. Fork o projeto
2. Crie uma branch para sua feature (git checkout -b feature/AmazingFeature)
3. Commit suas mudanças (git commit -m 'feat: add amazing feature')
4. Push para a branch (git push origin feature/AmazingFeature)
5. Abra um Pull Request

📄 Licença

Distribuído sob a licença MIT. Veja LICENSE para mais informações.

👨‍💻 Autor

Anderson Henrique da Silva
📧 [email protected] | 💻 GitHub

---

🧠 Democratizando Análise de Transparência com IA Avançada 🧠

Modelos • MLOps • Explicável • Brasileira