README.md

---
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**

[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![PyTorch](https://img.shields.io/badge/PyTorch-2.0+-red.svg)](https://pytorch.org/)
[![Transformers](https://img.shields.io/badge/🤗-Transformers-yellow.svg)](https://huggingface.co/transformers/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

## 🎯 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

```bash
# 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

```python
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

```bash
# 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

```bash
# Executar todos os testes
pytest tests/

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

### Treinamento de Modelos

```bash
# 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

```bash
# 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](https://github.com/anderson-ufrj/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

```python
# 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](https://github.com/anderson-ufrj/cidadao.ai-backend)
- 🎨 **Frontend**: [cidadao.ai-frontend](https://github.com/anderson-ufrj/cidadao.ai-frontend)
- 📚 **Documentação**: [cidadao.ai-docs](https://github.com/anderson-ufrj/cidadao.ai-docs)
- 🤗 **HuggingFace**: [cidadao-ai organization](https://huggingface.co/cidadao-ai)

## 📈 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](https://github.com/anderson-ufrj)

---

<div align="center">
<h3>🧠 Democratizando Análise de Transparência com IA Avançada 🧠</h3>
<p><em>Modelos • MLOps • Explicável • Brasileira</em></p>
</div>