ai-critic 4.0.0

Comprehensive ML model evaluation: performance, robustness, fairness, calibration, explainability, data quality and complexity in one report.

ai-critic

Avaliação completa de modelos ML — muito além da acurácia.

pip install ai-critic

---

Por que usar?

Acurácia isolada mente. Um modelo pode ter 99 % de acurácia e ainda assim:

• estar vazando o alvo (data leakage),
• colapsar sob ruído mínimo nos dados de produção,
• ser injusto com algum grupo demográfico,
• ter probabilidades completamente mal calibradas,
• depender de uma única feature que é um proxy do target.

ai-critic quantifica 7 dimensões independentes e entrega um relatório unificado, acionável e JSON-pronto — em uma linha.

---

Início rápido

import ai_critic
from ai_critic.reporters import print_report

# modelo já treinado (sklearn-compatible)
report = ai_critic.audit(model, X, y)
print_report(report)

Saída:

══════════════════════════════════════════════════════════════
  MODEL AUDIT REPORT
  Problem type : multiclass_classification
  Overall score: 0.944  ✅ PASS
══════════════════════════════════════════════════════════════
  Dimension               Score  Verdict     Summary
──────────────────────────────────────────────────────────────
  explainability          0.713  ✅ pass      Gini concentration 0.53 | ...
  calibration             0.935  ✅ pass      Mean ECE: 0.022
  performance             0.954  ✅ pass      Accuracy 0.960 | F1-macro 0.960 | MCC 0.940
  robustness              0.980  ✅ pass      Noise drop 0.027 | Dropout drop 0.031
  data_quality            1.000  ✅ pass      Missing 0.0% | Duplicates 0.7%
  complexity              1.000  ✅ pass      Feature/sample ratio: 0.03
  fairness                1.000  ✅ pass      Max gap: 0.000
══════════════════════════════════════════════════════════════

---

Funciona com pandas DataFrames

Passe um DataFrame diretamente — os nomes das colunas aparecem no relatório:

import pandas as pd
import ai_critic

df = pd.read_csv("dados.csv")
X = df.drop("target", axis=1)
y = df["target"]

report = ai_critic.audit(model, X, y)

---

Fairness com features sensíveis nomeadas

report = ai_critic.audit(
    model, X, y,
    sensitive_features=["genero", "faixa_etaria", "regiao"]
)

O relatório mostrará o gap de performance por grupo usando os nomes reais das colunas.

---

Relatório HTML

from ai_critic.reporters import save_html_report

report = ai_critic.audit(model, X, y)
save_html_report(report, "audit_report.html")
# → abre no browser, dark theme, sem dependências externas

---

Gate de CI/CD

Bloqueia deploy de modelos abaixo do limiar:

report = ai_critic.audit(model, X, y)
ai_critic.gate(report, min_score=0.75)  # levanta RuntimeError se falhar

---

CLI

# Audita um modelo pickled contra um CSV
ai-critic score model.pkl dados.csv --target target_col

# Com relatório HTML + gate de CI
ai-critic score model.pkl dados.csv \
  --target target_col \
  --sensitive genero,regiao \
  --report audit.html \
  --gate 0.75

# Saída JSON completa
ai-critic score model.pkl dados.csv --target y --json

---

Relatório como dict / JSON

import json
d = report.to_dict()
print(json.dumps(d, indent=2))

---

Pesos customizados

report = ai_critic.audit(
    model, X, y,
    weights={"robustness": 2.0, "fairness": 1.5}
)

---

Execução paralela

report = ai_critic.audit(model, X, y, parallel=True)

---

Evaluadores customizados

from ai_critic.core.base import BaseEvaluator
from ai_critic.core.types import DimensionResult, ProblemType, Verdict

class MyEvaluator(BaseEvaluator):
    name = "my_check"
    weight = 1.0
    depends_on = []  # ou ["performance"] se precisar do resultado anterior

    def evaluate(self, model, X, y, problem_type, context=None):
        score = 0.95  # sua lógica aqui
        return DimensionResult(
            name=self.name,
            score=score,
            verdict=self._score_to_verdict(score),
            summary="Tudo certo.",
        )

report = ai_critic.audit(model, X, y, evaluators=[..., MyEvaluator()])

---

As 7 dimensões

Dimensão	O que mede
performance	Accuracy, F1-macro, MCC, R², RMSE — métricas reais, não apenas acurácia
robustness	Degradação sob ruído gaussiano (4 intensidades), dropout de features, injeção de outliers
explainability	Importância por permutação, índice de Gini de concentração, detecção de features dominantes
calibration	ECE, MCE, Brier Score — as probabilidades do modelo são confiáveis?
data_quality	Missing values, duplicatas, features constantes, outliers, leakage por correlação, imbalance
fairness	Disparidade de performance entre grupos categóricos, Disparate Impact Ratio, nomes de colunas
complexity	Profundidade de árvores, ratio features/amostras, latência de inferência

---

Score e veredito

Cada dimensão retorna um score de 0.0 a 1.0 e um veredito:

Score	Veredito
≥ 0.75	✅ pass
0.50 – 0.75	⚠️ warning
< 0.50	❌ fail

O overall score é a média ponderada pelos weight de cada evaluador.

---

Compatibilidade

Funciona com qualquer estimador sklearn-compatible, incluindo:

• scikit-learn (RandomForest, SVM, LogisticRegression, etc.)
• XGBoost (XGBClassifier, XGBRegressor)
• LightGBM (LGBMClassifier, LGBMRegressor)
• CatBoost (CatBoostClassifier, CatBoostRegressor)
• Qualquer objeto com .predict() e opcionalmente .predict_proba()

---

Integração com MLflow

import mlflow
import ai_critic

with mlflow.start_run():
    report = ai_critic.audit(model, X_test, y_test)
    mlflow.log_metric("audit_overall_score", report.overall_score)
    for name, dim in report.dimensions.items():
        mlflow.log_metric(f"audit_{name}", dim.score)

---

Licença

MIT

---

Changelog

Ver CHANGELOG.md.