Metadata-Version: 2.4
Name: ai-critic
Version: 0.2.0
Summary: Fast AI evaluator for scikit-learn models
Author-email: Luiz Seabra <filipedemarco@yahoo.com>
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: numpy
Requires-Dist: scikit-learn

# ai-critic

Automated Risk Auditor for Machine Learning Models

[![PyPI version](https://img.shields.io/pypi/v/ai-critic.svg)](https://pypi.org/project/ai-critic/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## 🚀 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:

```bash
pip install ai-critic
```

**Requisitos:**
*   Python ≥ 3.8
*   scikit-learn

## 💡 Início Rápido

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

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

```python
critic.evaluate(view="executive")
```

**Exemplo de Saída:**
```json
{
  "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.

```python
critic.evaluate(view="technical")
```

**Exemplo de Saída:**
```json
{
  "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.

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

```python
critic.evaluate(view="all")
```

**Retorna:**
```json
{
  "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

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