ai-critic 0.2.2

Fast AI evaluator for scikit-learn models

ai-critic: Automated Risk Auditor for Machine Learning Models

O ai-critic é um auditor de risco automatizado baseado em heurísticas para modelos de Machine Learning. Ele avalia modelos treinados antes da implantação e traduz riscos técnicos complexos em decisões claras e centradas no ser humano.

Diferente das ferramentas tradicionais que focam apenas em métricas de desempenho, o ai-critic adota uma postura cética por design, respondendo à pergunta fundamental: “Este modelo pode ser implantado com segurança?”

---

🚀 O que é o ai-critic?

O ai-critic avalia modelos treinados antes da implantação, analisando quatro áreas principais de risco:

• Integridade dos Dados: (data leakage, desequilíbrio, NaNs).
• Estrutura do Modelo: (risco de overfitting, complexidade, configurações suspeitas).
• Comportamento de Validação: (pontuações suspeitamente perfeitas de cross-validation).
• Robustez: (sensibilidade a ruído e estabilidade do modelo).

Os resultados são organizados em três camadas semânticas para diferentes stakeholders:

• Executiva: Decisões para stakeholders e gerentes.
• Técnica: Diagnósticos para engenheiros de ML.
• Detalhada: Saída completa de métricas e análises técnicas, incluindo gráficos opcionais.

---

🎯 Por que o ai-critic Existe: Filosofia Central

A maioria das ferramentas de ML tradicionais assume que métricas são a verdade absoluta, confia cegamente na validação cruzada e entrega números brutos sem interpretação.

O ai-critic é cético por design. Ele trata:

• Pontuações perfeitas como sinais de alerta, não necessariamente sucesso.
• Métricas de robustez como dependentes do contexto.
• Implantação como uma decisão de gestão de risco, não apenas uma meta técnica.

A filosofia central é: Métricas não falham modelos — o contexto falha. O ai-critic aplica heurísticas de raciocínio humano:

• “Isso é bom demais para ser verdade?”
• “Isso pode estar vazando o alvo (target)?”
• “A robustez importa se a linha de base estiver errada?”

---

🛠️ Instalação

Instale o ai-critic via pip:

pip install ai-critic

Requisitos:

• Python ≥ 3.8
• scikit-learn
• matplotlib, seaborn, numpy, pandas (para visualizações opcionais)

---

💡 Início Rápido

Audite seu modelo treinado em apenas algumas linhas:

from sklearn.datasets import load_breast_cancer
from sklearn.ensemble import RandomForestClassifier
from ai_critic import AICritic

# 1. Carregar dados e treinar um modelo (exemplo)
X, y = load_breast_cancer(return_X_y=True)
model = RandomForestClassifier(max_depth=20, random_state=42)
model.fit(X, y)

# 2. Inicializar e avaliar com ai-critic
critic = AICritic(model, X, y)

# Realização de avaliação completa (padrão view="all")
report = critic.evaluate(plot=True)
print(report)

---

🧩 Saída Multi-Camadas

O ai-critic estrutura os resultados em camadas de decisão claras através do parâmetro view.

🔹 Visualização Executiva (view="executive")

Projetado para stakeholders e gestores. Sem jargão técnico.

critic.evaluate(view="executive")

Exemplo de Saída:

{
  "verdict": "❌ Não Confiável",
  "risk_level": "high",
  "deploy_recommended": false,
  "main_reason": "Forte evidência de vazamento de dados inflando o desempenho do modelo."
}

🔹 Visualização Técnica (view="technical")

Projetado para engenheiros de ML. Focado em diagnósticos e ações corretivas.

critic.evaluate(view="technical")

Exemplo de Saída:

{
  "key_risks": [
    "Vazamento de dados suspeito devido à correlação quase perfeita entre recurso e alvo.",
    "Pontuação de validação cruzada perfeita detectada (estatisticamente improvável).",
    "A profundidade da árvore pode ser muito alta para o tamanho do conjunto de dados."
  ],
  "model_health": {
    "data_leakage": true,
    "suspicious_cv": true,
    "structural_risk": true,
    "robustness_verdict": "misleading"
  },
  "recommendations": [
    "Auditar e remover recursos com vazamento.",
    "Reduzir a complexidade do modelo.",
    "Executar novamente a validação após a mitigação do vazamento."
  ]
}

🔹 Visualização Detalhada (view="details")

Projetado para auditoria, depuração e conformidade. Agrega todos os outputs dos módulos internos.

details = critic.evaluate(view="details")
print(details["data"]["class_balance"])
print(details["robustness"]["performance_drop"])

🔹 Visualização Combinada (view="all")

Retorna todas as três camadas em um único dicionário, facilitando a integração com pipelines de CI/CD.

---

📊 Visualizações e Gráficos

Ao definir plot=True no método evaluate(), o ai-critic gera automaticamente:

• Heatmap de Correlação: Identificação visual de vazamento de dados.
• Learning Curve: Diagnóstico de overfitting e necessidade de mais dados.
• Gráfico de Robustez: Visualização da queda de performance sob ruído.

---

⚙️ API Principal e Modularização

AICritic(model, X, y)

• model: Modelo scikit-learn treinado.
• X: Matriz de recursos.
• y: Vetor alvo.

evaluate(view="all", plot=False)

• view: Camada de saída ("executive", "technical", "details", "all" ou lista customizada).
• plot: True para gerar gráficos automáticos.

Uso Modular (Avançado)

Cada módulo retorna um dicionário padronizado consistente:

from ai_critic.evaluators import data, config, performance, robustness

data_report = data.evaluate(X, y, plot=True)
config_report = config.evaluate(model, n_samples=data_report["n_samples"], n_features=data_report["n_features"])

---

🧠 O que o ai-critic Detecta

Categoria	Riscos Detectados
🔍 Dados	Vazamento de alvo via correlação, NaNs, desequilíbrio de classes.
🧱 Estrutura	Árvores excessivamente complexas, altas taxas de recurso/amostra, configurações suspeitas.
📈 Validação	Pontuações de CV suspeitosamente perfeitas, variância irreal.
🧪 Robustez	Sensibilidade a ruído, robustez enganosa (stable, fragile, misleading).

---

🛡️ Melhores Práticas

• CI/CD: Use a Visualização Executiva como um portão de qualidade automatizado.
• Debugging: Use a Visualização Técnica durante a iteração do modelo.
• Compliance: Utilize a Visualização Detalhada para rastreabilidade e auditoria.
• Ceticismo: Nunca confie cegamente em pontuações de CV perfeitas.

---

🧭 Casos de Uso Típicos

• Auditorias de modelo pré-implantação.
• Governança e conformidade de ML.
• Portões de modelo em pipelines CI/CD.
• Explicação de riscos para stakeholders não técnicos.

---

📄 Licença

Distribuído sob a MIT License.

---

🧠 Nota Final

O ai-critic não é uma ferramenta de benchmarking. É uma ferramenta de decisão. Se um modelo falhar aqui, não significa que seja ruim — significa que não deve ser confiável ainda.