Metadata-Version: 2.4
Name: ai-critic
Version: 4.0.0
Summary: Comprehensive ML model evaluation: performance, robustness, fairness, calibration, explainability, data quality and complexity in one report.
License: MIT
Project-URL: Homepage, https://github.com/YOUR_USER/ai-critic
Project-URL: Documentation, https://github.com/YOUR_USER/ai-critic#readme
Project-URL: Bug Tracker, https://github.com/YOUR_USER/ai-critic/issues
Project-URL: Changelog, https://github.com/YOUR_USER/ai-critic/blob/main/CHANGELOG.md
Keywords: machine-learning,model-evaluation,fairness,mlops,ai-critic,calibration,robustness,explainability,scikit-learn,xgboost,lightgbm,responsible-ai
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.24
Requires-Dist: scikit-learn>=1.3
Requires-Dist: scipy>=1.11
Requires-Dist: pandas>=2.0
Provides-Extra: reports
Requires-Dist: matplotlib>=3.7; extra == "reports"
Requires-Dist: jinja2>=3.1; extra == "reports"
Provides-Extra: all
Requires-Dist: ai-critic[reports]; extra == "all"

# ai-critic

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

[![PyPI version](https://img.shields.io/pypi/v/ai-critic.svg)](https://pypi.org/project/ai-critic/)
[![Python](https://img.shields.io/pypi/pyversions/ai-critic.svg)](https://pypi.org/project/ai-critic/)
[![Downloads](https://img.shields.io/pypi/dm/ai-critic.svg)](https://pypi.org/project/ai-critic/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![CI](https://github.com/YOUR_USER/ai-critic/actions/workflows/ci.yml/badge.svg)](https://github.com/YOUR_USER/ai-critic/actions)

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

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

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

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

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

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

---

## CLI

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

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

---

## Pesos customizados

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

---

## Execução paralela

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

---

## Evaluadores customizados

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

```python
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](CHANGELOG.md).
