ai-critic 0.2.0

Fast AI evaluator for scikit-learn models

ai-critic

Automated Risk Auditor for Machine Learning Models

🚀 O que é ai-critic?

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

Em vez de apenas relatar métricas, ai-critic responde a uma pergunta crítica:

“Este modelo pode ser implantado com segurança?”

Ele faz isso analisando:

• Integridade dos Dados: (vazamento de dados, desequilíbrio, valores NaNs)
• Estrutura do Modelo: (risco de overfitting, complexidade)
• Comportamento de Validação: (pontuações suspeitamente perfeitas)
• Robustez: (sensibilidade a ruído)

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

1. Executiva: (tomadores de decisão)
2. Técnica: (engenheiros de ML)
3. Detalhes: (auditores e depuração)

🎯 Por que ai-critic existe: Filosofia Central

A maioria das ferramentas de ML:

• assume que métricas = verdade
• confia cegamente na validação cruzada
• expõe números brutos sem interpretação

ai-critic é cético por design.

Ele trata:

• pontuações perfeitas como sinais, não como sucesso
• métricas de robustez como dependentes do contexto
• a implantação como uma decisão de risco, não um limite de métrica

A filosofia central é: Métricas não falham modelos — o contexto falha.

ai-critic aplica heurísticas de raciocínio humano à avaliação de machine learning:

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

🛠️ Instalação

Você pode instalar ai-critic usando pip:

pip install ai-critic

Requisitos:

• Python ≥ 3.8
• scikit-learn

💡 Início Rápido

Audite seu modelo treinado em poucas linhas de código:

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) # O modelo precisa estar treinado

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

# O padrão é a visualização 'all' (todas as camadas)
print(report)

🧩 Saída Multi-Camadas

ai-critic nunca despeja tudo de uma vez. Ele estrutura os resultados em camadas de decisão claras.

🔹 Visão Executiva (view="executive")

Projetada para CTOs, gerentes e stakeholders. Zero jargão de ML.

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."
}

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

Projetada para engenheiros de ML. É acionável, diagnóstica e focada no que precisa ser corrigido.

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."
  ]
}

🔹 Visão Detalhada (view="details")

Projetada para auditoria, depuração e conformidade.

critic.evaluate(view="details")

Inclui:

• Métricas brutas
• Correlações
• Pontuações de robustez
• Avisos estruturais
• Rastreabilidade completa

🔹 Visão Combinada (view="all")

Retorna todas as três camadas em um único dicionário.

critic.evaluate(view="all")

Retorna:

{
  "executive": {...},
  "technical": {...},
  "details": {...}
}

⚙️ API Principal

AICritic

Parâmetro	Descrição
model	Modelo scikit-learn treinado.
X	Matriz de recursos (features).
y	Vetor alvo (target).

Uso: AICritic(model, X, y)

evaluate()

Parâmetro	Descrição
view	A camada de saída desejada: "executive", "technical", "details", ou "all" (padrão).

Uso: evaluate(view="all")

🧠 O que ai-critic Detecta

Categoria	Riscos Detectados
🔍 Riscos de Dados	Vazamento de alvo via correlação, NaNs, Desequilíbrio de classe.
🧱 Riscos Estruturais	Árvores excessivamente complexas, Altas proporções de recurso/amostra, Configuration smells.
📈 Riscos de Validação	Pontuações de CV suspeitamente perfeitas, Variância irrealista.
🧪 Riscos de Robustez	Sensibilidade a ruído, Robustez enganosa quando a linha de base está inflada.

🧪 Exemplo: Detecção de Vazamento de Dados

import numpy as np
# ... (código de importação e modelo)

# Vazamento artificial: adicionando o alvo como um recurso
X_leaky = np.hstack([X, y.reshape(-1, 1)])

critic = AICritic(model, X_leaky, y)
executive_report = critic.evaluate(view="executive")

print(executive_report)

Resultado (Executive View):

❌ Não Confiável
Forte evidência de vazamento de dados inflando o desempenho do modelo.

🛡️ Melhores Práticas

• Execute ai-critic antes da implantação.
• Nunca confie cegamente em pontuações de CV perfeitas.
• Use a Visão Executiva no seu pipeline de CI/CD como um gate de modelo.
• Use a Visão Técnica durante a iteração do modelo.
• Use a Visão Detalhada para auditorias e conformidade.

🧭 Casos de Uso Típicos

• Auditorias de modelo pré-implantação.
• Governança e conformidade de ML.
• Gates de modelo em CI/CD.
• Ensino de ceticismo em ML.
• Explicação de risco de ML para stakeholders não técnicos.

📄 Licença

Distribuído sob a Licença MIT.

🧠 Nota Final

ai-critic não é uma ferramenta de benchmark. É uma ferramenta de decisão.

Se um modelo falhar aqui, isso não significa que ele é ruim — significa que ele não deve ser confiável ainda.