Metadata-Version: 2.4
Name: ai-critic
Version: 3.4.1
Summary: Graph-based evaluation engine for machine learning models
Author: Luiz Filipe Seabra
License: MIT
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: numpy<2.3,>=1.23
Requires-Dist: scikit-learn<2.0,>=1.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Provides-Extra: viz
Requires-Dist: graphviz; extra == "viz"
Provides-Extra: full
Requires-Dist: graphviz; extra == "full"
Requires-Dist: pandas; extra == "full"

# 🚀 AI Critic 3.4.0 (Unified Edition)

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

AI Critic é um **motor de avaliação de modelos de machine learning baseado em grafo**, projetado para ir além de métricas isoladas.

Ele executa um **pipeline estruturado** que analisa múltiplas dimensões do modelo — performance, robustez, explainability, dados e estrutura — e entrega um **relatório unificado, interpretável e acionável**.

---

# 🔥 O QUE MUDOU NA 4.0

### 🧠 Arquitetura Unificada

* Um único pipeline central (`evaluate()`)
* Um único formato de saída (`report`)
* Eliminação de múltiplos formatos inconsistentes

---

### 📦 Report Padronizado (JSON-first)

Todos os resultados seguem o mesmo schema:

```python
report = {
    "scores": {},        # score técnico (0–1)
    "details": {},       # outputs dos nodes
    "risk": {},          # score interpretável (0–100)
    "summary": {},       # interpretação humana
    "suggestions": []    # ações recomendadas
}
```

👉 Isso torna o sistema:

* API-ready
* fácil de salvar/logar
* pronto para produção

---

### ⚡ Graph Engine Melhorado

* Execução baseada em dependências reais (topological sort)
* Suporte a execução paralela

---

### 🎯 Sistema de Scoring em Camadas

* **Score técnico (0–1)** → agregador
* **Score interpretável (0–100)** → risk scoring

---

### 💡 Suggestion Engine Integrado

* Recomendações automáticas baseadas no comportamento do modelo

---

# ⚡ QUICK START

```python
from ai_critic import AICritic
from sklearn.ensemble import RandomForestClassifier
from sklearn.datasets import load_iris

# Dados
data = load_iris()
X, y = data.data, data.target

# Modelo
model = RandomForestClassifier().fit(X, y)

# Critic
critic = AICritic(weights={
    "performance": 1.0,
    "robustness": 1.5
})

# Avaliação
report = critic.evaluate(model, X, y, parallel=True)

# 🔹 Scores técnicos
print(report["scores"])

# 🔹 Score de risco (0–100)
print(report["risk"])

# 🔹 Resumo humano
print(report["summary"])

# 🔹 Sugestões
for s in report["suggestions"]:
    print("-", s)
```

---

# 🧩 PIPELINE INTERNO

```text
evaluate()
   ↓
EvaluationGraph (nodes)
   ↓
raw_results
   ↓
ScoreAggregator (0–1)
   ↓
build_report()
   ↓
scoring.py (risk 0–100)
   ↓
summary.py (human)
   ↓
SuggestionEngine
```

---

# 🧱 COMPONENTES PRINCIPAIS

## 1. Evaluation Graph

Sistema baseado em DAG (Directed Acyclic Graph):

* Resolve dependências automaticamente
* Executa nós na ordem correta
* Permite paralelização

Exemplo:

```
performance → robustness → explainability
```

---

## 2. Score Aggregator

Combina scores dos evaluators:

```python
critic = AICritic(weights={
    "performance": 1.0,
    "robustness": 2.0
})
```

---

## 3. Evaluator Plugins

Extensível via plugins:

```python
from ai_critic.plugins.base import EvaluatorPlugin
from ai_critic.plugins.registry import EvaluatorRegistry

class FairnessEvaluator(EvaluatorPlugin):
    name = "fairness"
    dependencies = ["performance"]
    weight = 1.0

    def evaluate(self, model, dataset, context=None):
        return {
            "score": 0.92,
            "verdict": "stable",
            "message": "Fairness is acceptable"
        }

EvaluatorRegistry.register(FairnessEvaluator())
```

---

## 4. Risk Scoring (0–100)

Transforma sinais técnicos em diagnóstico interpretável:

```python
report["risk"] = {
    "global_score": 78.5,
    "verdict": "usable_with_caution",
    "component_scores": {...},
    "penalties": [...]
}
```

---

## 5. Human Summary

Resumo de alto nível:

```python
report["summary"] = {
    "executive_summary": {
        "verdict": "⚠️ Risky",
        "deploy_recommended": False
    }
}
```

---

## 6. Suggestion Engine

Sugestões automáticas:

```python
[
    "Check for data leakage",
    "Improve robustness with regularization"
]
```

---

# 🖥️ CLI

```bash
ai-critic --model model.pkl --data dataset.csv --target label
```

Saída:

* scores
* risco
* resumo

---

# 🧠 FILOSOFIA DE DESIGN

### 1. Single Source of Truth

Um único formato de dados → evita inconsistência

---

### 2. Graph-first Thinking

Avaliação como pipeline dependente, não funções isoladas

---

### 3. JSON-native

Tudo pronto para:

* APIs
* dashboards
* logs
* SaaS

---

### 4. Actionable AI

Não só métricas — decisões:

* “deploy ou não?”
* “onde está o risco?”
* “o que corrigir?”

---

# 🔥 POSICIONAMENTO

AI Critic não é só uma lib de métricas.

É um:

> 🧠 **Linting engine para modelos de machine learning**

---

# 🚀 ROADMAP (PRÓXIMO NÍVEL)

* API REST (`/evaluate`)
* Dashboard visual
* Telemetria de modelos
* Aprendizado contínuo (feedback loop)
* Benchmark global entre modelos

---

# 💬 RESUMO

Você transformou o projeto em:

✅ pipeline unificado
✅ arquitetura escalável
✅ pronto para produto
✅ pronto para SaaS

---

Se quiser, posso agora te ajudar a transformar isso em:

👉 landing page estilo startup
👉 README que viraliza no GitHub
👉 ou pitch para investidores

Só falar 👍
