justiceai 0.4.0

Fairness analysis for ML in production with LGPD/BACEN compliance, drift detection, and monitoring

⚖️ justiceai

Fairness em ML para Produção: A primeira biblioteca Python focada em monitoramento de fairness em produção, com compliance LGPD/BACEN nativo e relatórios standalone.

---

🎯 O Problema

Ferramentas como Fairlearn e AIF360 são excelentes para pesquisa, mas param no notebook. Você precisa de fairness em produção, com:

• ✅ Monitoramento contínuo de viés
• ✅ Compliance automático (LGPD Art. 20, BACEN Res. 4.658)
• ✅ Relatórios prontos para stakeholders não-técnicos
• ✅ Zero vendor lock-in (funciona com sklearn, XGBoost, PyTorch, TensorFlow)

justiceai resolve isso.

---

🚀 Quick Start

from justiceai import audit
from sklearn.datasets import load_breast_cancer
from sklearn.ensemble import RandomForestClassifier
import pandas as pd

# Carregar dados
data = load_breast_cancer()
df = pd.DataFrame(data.data, columns=data.feature_names)
df['target'] = data.target
df['gender'] = np.random.choice(['M', 'F'], size=len(df))  # Atributo protegido

# Treinar modelo
model = RandomForestClassifier()
model.fit(df.drop(['target', 'gender'], axis=1), df['target'])

# Avaliar fairness em 1 linha
report = audit(
    model=model,
    data=df,
    target='target',
    protected_attrs=['gender']
)

# Visualizar
report.show()  # Abre HTML interativo no navegador
report.save_html('fairness_report.html')  # Salva para compartilhar

Output: Relatório HTML standalone com Plotly interativo, pronto para apresentar ao board.

🇧🇷 Compliance LGPD/BACEN

from justiceai import audit
from justiceai.compliance import LGPDComplianceReporter, BACENComplianceReporter

# Executar auditoria de fairness
report = audit(model, X, y, sensitive_attrs)

# Gerar relatório LGPD (Art. 20)
lgpd_reporter = LGPDComplianceReporter(report)
lgpd_reporter.save_html('lgpd_compliance.html')

# Gerar relatório BACEN (Res. 4.658)
bacen_reporter = BACENComplianceReporter(report)
compliance_data = bacen_reporter.generate_report()
print(f"Risco do Modelo: {compliance_data['risco_modelo']['nivel_risco']}")

📈 Monitoring em Produção

from justiceai.monitoring import (
    FairnessDriftDetector,
    FairnessAlerting,
    ConsoleAlertChannel
)

# Estabelecer baseline
baseline_metrics = {'statistical_parity': 0.95, 'equal_opportunity': 0.92}

# Configurar detector
detector = FairnessDriftDetector(baseline_metrics, threshold=0.10)

# Configurar alertas
alerting = FairnessAlerting()
alerting.add_channel('console', ConsoleAlertChannel())

# Monitorar novos dados
new_metrics = {'statistical_parity': 0.75, 'equal_opportunity': 0.90}
drift_result = detector.detect(new_metrics)

if drift_result.has_drift:
    print(f"⚠️ Drift detectado: {list(drift_result.drifted_metrics.keys())}")
    alerting.send_drift_alert(drift_result, detector)

---

📦 Instalação

Via pip (em breve)

pip install justiceai

Para Desenvolvimento

# Clone o repositório
git clone https://github.com/guhaase/justiceai.git
cd justiceai

# Instale com Poetry
poetry install

# Ative o ambiente
poetry shell

# Rode os testes
pytest

---

✨ Features

🔬 15+ Métricas de Fairness

Pre-Training (independentes de modelo)

• Class Balance: Distribuição balanceada entre grupos
• Concept Balance: Taxa de positivos balanceada
• KL/JS Divergence: Similaridade de distribuições

Post-Training (baseadas em predições)

• Statistical Parity: Taxa de predições positivas igual
• Disparate Impact: Compliance com regra EEOC 80%
• Equal Opportunity: TPR igual entre grupos
• Equalized Odds: TPR e FPR iguais
• + 8 métricas adicionais

📊 Relatórios Standalone

• HTML Interativo: Plotly charts, funciona offline
• PDF Profissional: Pronto para auditoria (em breve)
• Markdown: Versionável em Git (em breve)

🇧🇷 Compliance Brasil

• LGPD Art. 20: Template pronto para direito à explicação
• BACEN Res. 4.658: Análise de risco de modelo
• Português nativo: Relatórios e erros em PT-BR

🔌 Framework-Agnostic

Funciona com:

• ✅ scikit-learn
• ✅ XGBoost
• ✅ LightGBM
• ⏳ PyTorch (em breve)
• ⏳ TensorFlow (em breve)
• ⏳ ONNX (em breve)

📈 Monitoring em Produção

• Drift Detection: Detecta degradação de fairness ao longo do tempo (threshold, PSI, KS test)
• Alerting: Slack/Email/Webhook quando métricas violam thresholds
• Continuous Monitoring: Histórico, tendências e alertas automáticos

---

📚 Documentação

Status: ✅ Completa

• Installation Guide - Setup and installation
• Quick Start - Your first fairness audit in 5 minutes
• Basic Concepts - Understanding fairness metrics
• API Reference - Complete API documentation
• Tutorials - 3 Jupyter notebooks with hands-on examples
• FAQ - 40+ common questions answered
• Contributing - Guidelines for contributors

---

🔬 Comparação com Concorrentes

Feature	Fairlearn	AIF360	justiceai
Métricas	8	70+	15+ (curadas)
MLOps/Produção	❌	❌	✅
Compliance BR	❌	❌	✅
Reports Standalone	❌	⚠️	✅ (HTML Plotly)
Framework-Agnostic	⚠️	⚠️	✅
API 1-liner	❌	❌	✅
Monitoring	❌	❌	✅ (em breve)

---

🗺️ Roadmap

✅ v0.1.0 (Sprint 1-3) - COMPLETO

• Setup projeto (Poetry, CI/CD)
• 15+ métricas de fairness
• Reports HTML com Plotly
• API audit() simples
• FairnessEvaluator API
• Model adapters (sklearn + factory)
• Documentação completa (MkDocs)
• 3 tutoriais Jupyter
• 192 testes, 90%+ coverage
• FAQ com 40+ questões

🏗️ v0.2.0 (Sprint 4) - Compliance

• Suporte XGBoost, LightGBM
• Templates LGPD/BACEN
• Monitoring e drift detection
• Threshold optimization
• Reports PDF

🔮 v0.3.0 (Sprint 5) - Release Público

• Publicado no PyPI
• GitHub Pages documentation
• Português nativo completo
• Suporte PyTorch/TensorFlow

🌟 v1.0+ (Futuro)

• Mitigação automática de viés
• IA-powered insights (LLM)
• Integração MLflow/W&B
• SaaS offering (?)

---

🤝 Contribuindo

Contribuições são muito bem-vindas! Veja CONTRIBUTING.md para guidelines.

Como Contribuir

1. Fork o repositório
2. Clone seu fork: git clone https://github.com/SEU-USUARIO/justiceai.git
3. Crie uma branch: git checkout -b feature/minha-feature
4. Faça mudanças e commit: git commit -m "feat: adiciona minha feature"
5. Push: git push origin feature/minha-feature
6. Abra um Pull Request

Code Quality

Antes de abrir PR, rode:

# Formatar código
make format

# Linting
make lint

# Type checking
make type-check

# Testes
make test

# Tudo de uma vez
make quality

---

📊 Status do Projeto

Fase Atual: Sprint 3 Completo - v0.1.0 Ready!

Métrica	Status	Target
Coverage	✅ 90.03%	90%
Testes	✅ 192 passing	150+
Docs	✅ 20 pages	100%
Tutorials	✅ 3 notebooks	3

Sprints Completos: 3/5 (60%)

• ✅ Sprint 1: Core Metrics
• ✅ Sprint 2: HTML Reports
• ✅ Sprint 3: API + Documentation
• 🔄 Sprint 4: Compliance (próximo)
• ⏳ Sprint 5: Release Público

---

📄 Licença

Este projeto está licenciado sob a MIT License.

MIT License

Copyright (c) 2026 Gustavo Haase

Permission is hereby granted, free of charge, to any person obtaining a copy...

---

👥 Autores

Gustavo Haase

• Email: [e-mail]
• GitHub: @guhaase

---

🙏 Agradecimentos

• DeepBridge: Base de código que inspirou este projeto
• Fairlearn/AIF360: Referências de métricas
• Comunidade Python: Ferramentas incríveis (Poetry, Pytest, Black, etc.)

---

📞 Suporte

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: [e-mail]

---

🌟 Star History

---

Feito com ❤️ para tornar ML mais justo e responsável

_{⚖️ justiceai - Fairness em ML para Produção}