ai-critic 0.1.0__tar.gz → 0.2.1__tar.gz

ai_critic-0.2.1/PKG-INFO

@@ -0,0 +1,258 @@
+Metadata-Version: 2.4
+Name: ai-critic
+Version: 0.2.1
+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**
+
+---
+
+## 🚀 What is ai-critic?
+
+`ai-critic` é um **auditor de risco automatizado 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, o `ai-critic` responde à pergunta crítica:
+
+> “Este modelo pode ser implantado com segurança?”
+
+Ele faz isso analisando as principais áreas de risco:
+
+*   **Integridade dos Dados:** (*data leakage*, desequilíbrio, 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*:
+
+*   **Executiva:** (tomadores de decisão)
+*   **Técnica:** (engenheiros de ML)
+*   **Detalhada:** (auditores e depuração)
+
+## 🎯 Por que o ai-critic Existe: Filosofia Central
+
+A maioria das ferramentas de ML:
+
+*   assume que métricas = verdade
+*   confia cegamente na validação cruzada
+*   despeja números brutos sem interpretação
+
+O `ai-critic` é cético por design.
+
+Ele trata:
+
+*   pontuações perfeitas como **sinais**, não sucesso
+*   métricas de robustez como **dependentes do contexto**
+*   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.**
+
+O `ai-critic` aplica heurísticas de raciocínio humano à avaliação de ML:
+
+*   “Isso é bom demais para ser verdade?”
+*   “Isso pode estar vazando o alvo (*target*)?”
+*   “A robustez importa se a linha de base estiver errada?”
+
+## 🛠️ Instalação
+
+Instale o `ai-critic` via pip:
+
+```bash
+pip install ai-critic
+```
+
+**Requisitos:**
+
+*   Python ≥ 3.8
+*   `scikit-learn`
+
+## 💡 Início Rápido
+
+Audite seu modelo treinado em apenas algumas linhas:
+
+```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 deve estar treinado
+
+# 2. Inicializar e avaliar com ai-critic
+critic = AICritic(model, X, y)
+report = critic.evaluate()
+
+# A visualização padrão é 'all' (todas as camadas)
+print(report)
+```
+
+## 🧩 Saída Multi-Camadas
+
+O `ai-critic` nunca despeja tudo de uma vez. Ele estrutura os resultados em camadas de decisão claras.
+
+### 🔹 Visualização Executiva (`view="executive"`)
+
+Projetado para CTOs, gerentes e *stakeholders*. Sem 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."
+}
+```
+
+### 🔹 Visualização Técnica (`view="technical"`)
+
+Projetado para engenheiros de ML. Acionável, diagnóstico e focado 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."
+  ]
+}
+```
+
+### 🔹 Visualização Detalhada (`view="details"`)
+
+Projetado para auditoria, depuração e conformidade.
+
+```python
+critic.evaluate(view="details")
+```
+
+Inclui:
+
+*   Métricas brutas
+*   Correlações de recursos
+*   Pontuações de robustez
+*   Avisos estruturais
+*   Rastreabilidade completa
+
+### 🔹 Visualizaçã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 |
+| `y` | Vetor alvo |
+
+**Uso:** `AICritic(model, X, y)`
+
+### `evaluate()`
+
+| Parâmetro | Descrição |
+| :--- | :--- |
+| `view` | Camada de saída desejada: `"executive"`, `"technical"`, `"details"`, ou `"all"` (padrão) |
+
+**Uso:** `evaluate(view="all")`
+
+## 🧠 O que o ai-critic Detecta
+
+| Categoria | Riscos Detectados |
+| :--- | :--- |
+| **🔍 Riscos de Dados** | Vazamento de alvo via correlação, NaNs, desequilíbrio de classes |
+| **🧱 Riscos Estruturais** | Árvores excessivamente complexas, altas taxas de recurso/amostra, *configuration smells* |
+| **📈 Riscos de Validação** | Pontuações de CV suspeitosamente perfeitas, variância irreal |
+| **🧪 Riscos de Robustez** | Sensibilidade a ruído, robustez enganosa se a linha de base estiver inflada |
+
+## 🧪 Exemplo: Detectando Vazamento de Dados
+
+```python
+import numpy as np
+# ... (imports e código do 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)
+```
+
+**Saída (Visualização Executiva):**
+
+```
+❌ Não Confiável
+Forte evidência de vazamento de dados inflando o desempenho do modelo.
+```
+
+## 🛡️ Melhores Práticas
+
+*   Execute o `ai-critic` antes da implantação.
+*   Nunca confie cegamente em pontuações de CV perfeitas.
+*   Use a Visualização Executiva em seu *pipeline* de CI/CD como um portão de modelo.
+*   Use a Visualização Técnica durante a iteração do modelo.
+*   Use a Visualização Detalhada para auditoria e conformidade.
+
+## 🧭 Casos de Uso Típicos
+
+*   Auditorias de modelo pré-implantação
+*   Governança e conformidade de ML
+*   Portões de modelo 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
+
+O `ai-critic` não é uma ferramenta de *benchmarking*. É uma **ferramenta de decisão**.
+
+Se um modelo falhar aqui, não significa que seja ruim — significa que **não deve ser confiável ainda**.

ai_critic-0.2.1/README.md

@@ -0,0 +1,248 @@
+# ai-critic: Automated Risk Auditor for Machine Learning Models**
+
+---
+
+## 🚀 What is ai-critic?
+
+`ai-critic` é um **auditor de risco automatizado 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, o `ai-critic` responde à pergunta crítica:
+
+> “Este modelo pode ser implantado com segurança?”
+
+Ele faz isso analisando as principais áreas de risco:
+
+*   **Integridade dos Dados:** (*data leakage*, desequilíbrio, 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*:
+
+*   **Executiva:** (tomadores de decisão)
+*   **Técnica:** (engenheiros de ML)
+*   **Detalhada:** (auditores e depuração)
+
+## 🎯 Por que o ai-critic Existe: Filosofia Central
+
+A maioria das ferramentas de ML:
+
+*   assume que métricas = verdade
+*   confia cegamente na validação cruzada
+*   despeja números brutos sem interpretação
+
+O `ai-critic` é cético por design.
+
+Ele trata:
+
+*   pontuações perfeitas como **sinais**, não sucesso
+*   métricas de robustez como **dependentes do contexto**
+*   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.**
+
+O `ai-critic` aplica heurísticas de raciocínio humano à avaliação de ML:
+
+*   “Isso é bom demais para ser verdade?”
+*   “Isso pode estar vazando o alvo (*target*)?”
+*   “A robustez importa se a linha de base estiver errada?”
+
+## 🛠️ Instalação
+
+Instale o `ai-critic` via pip:
+
+```bash
+pip install ai-critic
+```
+
+**Requisitos:**
+
+*   Python ≥ 3.8
+*   `scikit-learn`
+
+## 💡 Início Rápido
+
+Audite seu modelo treinado em apenas algumas linhas:
+
+```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 deve estar treinado
+
+# 2. Inicializar e avaliar com ai-critic
+critic = AICritic(model, X, y)
+report = critic.evaluate()
+
+# A visualização padrão é 'all' (todas as camadas)
+print(report)
+```
+
+## 🧩 Saída Multi-Camadas
+
+O `ai-critic` nunca despeja tudo de uma vez. Ele estrutura os resultados em camadas de decisão claras.
+
+### 🔹 Visualização Executiva (`view="executive"`)
+
+Projetado para CTOs, gerentes e *stakeholders*. Sem 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."
+}
+```
+
+### 🔹 Visualização Técnica (`view="technical"`)
+
+Projetado para engenheiros de ML. Acionável, diagnóstico e focado 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."
+  ]
+}
+```
+
+### 🔹 Visualização Detalhada (`view="details"`)
+
+Projetado para auditoria, depuração e conformidade.
+
+```python
+critic.evaluate(view="details")
+```
+
+Inclui:
+
+*   Métricas brutas
+*   Correlações de recursos
+*   Pontuações de robustez
+*   Avisos estruturais
+*   Rastreabilidade completa
+
+### 🔹 Visualizaçã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 |
+| `y` | Vetor alvo |
+
+**Uso:** `AICritic(model, X, y)`
+
+### `evaluate()`
+
+| Parâmetro | Descrição |
+| :--- | :--- |
+| `view` | Camada de saída desejada: `"executive"`, `"technical"`, `"details"`, ou `"all"` (padrão) |
+
+**Uso:** `evaluate(view="all")`
+
+## 🧠 O que o ai-critic Detecta
+
+| Categoria | Riscos Detectados |
+| :--- | :--- |
+| **🔍 Riscos de Dados** | Vazamento de alvo via correlação, NaNs, desequilíbrio de classes |
+| **🧱 Riscos Estruturais** | Árvores excessivamente complexas, altas taxas de recurso/amostra, *configuration smells* |
+| **📈 Riscos de Validação** | Pontuações de CV suspeitosamente perfeitas, variância irreal |
+| **🧪 Riscos de Robustez** | Sensibilidade a ruído, robustez enganosa se a linha de base estiver inflada |
+
+## 🧪 Exemplo: Detectando Vazamento de Dados
+
+```python
+import numpy as np
+# ... (imports e código do 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)
+```
+
+**Saída (Visualização Executiva):**
+
+```
+❌ Não Confiável
+Forte evidência de vazamento de dados inflando o desempenho do modelo.
+```
+
+## 🛡️ Melhores Práticas
+
+*   Execute o `ai-critic` antes da implantação.
+*   Nunca confie cegamente em pontuações de CV perfeitas.
+*   Use a Visualização Executiva em seu *pipeline* de CI/CD como um portão de modelo.
+*   Use a Visualização Técnica durante a iteração do modelo.
+*   Use a Visualização Detalhada para auditoria e conformidade.
+
+## 🧭 Casos de Uso Típicos
+
+*   Auditorias de modelo pré-implantação
+*   Governança e conformidade de ML
+*   Portões de modelo 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
+
+O `ai-critic` não é uma ferramenta de *benchmarking*. É uma **ferramenta de decisão**.
+
+Se um modelo falhar aqui, não significa que seja ruim — significa que **não deve ser confiável ainda**.

ai_critic-0.2.1/ai_critic/critic.py

@@ -0,0 +1,87 @@
+from ai_critic.evaluators import (
+    robustness,
+    config,
+    data,
+    performance
+)
+from ai_critic.evaluators.summary import HumanSummary
+
+
+class AICritic:
+    """
+    Automated reviewer for scikit-learn models.
+    Produces a multi-layered risk assessment with visualizations.
+    """
+
+    def __init__(self, model, X, y):
+        self.model = model
+        self.X = X
+        self.y = y
+
+    def evaluate(self, view="all", plot=False):
+        """
+        view:
+            - "all"
+            - "executive"
+            - "technical"
+            - "details"
+            - list of views
+        plot:
+            - True: gera gráficos de learning curve, heatmap e robustez
+            - False: sem gráficos
+        """
+
+        # =========================
+        # Low-level technical details
+        # =========================
+        details = {}
+
+        # Data analysis + heatmap
+        data_report = data(self.X, self.y, plot=plot)
+        details["data"] = data_report
+
+        # Model configuration
+        details["config"] = config(
+            self.model,
+            n_samples=data_report["n_samples"],
+            n_features=data_report["n_features"]
+        )
+
+        # Performance + learning curve
+        details["performance"] = performance(
+            self.model, self.X, self.y, plot=plot
+        )
+
+        # Robustness + CV clean vs noisy
+        details["robustness"] = robustness(
+            self.model,
+            self.X,
+            self.y,
+            leakage_suspected=data_report["data_leakage"]["suspected"],
+            plot=plot
+        )
+
+        # =========================
+        # Human interpretation
+        # =========================
+        human = HumanSummary().generate(details)
+
+        # =========================
+        # Full payload
+        # =========================
+        payload = {
+            "executive": human["executive_summary"],
+            "technical": human["technical_summary"],
+            "details": details
+        }
+
+        # =========================
+        # View selector
+        # =========================
+        if view == "all":
+            return payload
+
+        if isinstance(view, list):
+            return {k: payload[k] for k in view if k in payload}
+
+        return payload.get(view)

ai_critic-0.2.1/ai_critic/evaluators/config.py

@@ -0,0 +1,35 @@
+import math
+
+def evaluate(model, n_samples=None, n_features=None):
+    params = model.get_params()
+    model_type = type(model).__name__
+
+    report = {
+        "model_type": model_type,
+        "n_params": len(params),
+        "uses_random_state": "random_state" in params
+    }
+
+    # 🧠 Structural overfitting heuristics
+    warnings = []
+
+    if n_samples and hasattr(model, "max_depth"):
+        max_depth = params.get("max_depth")
+        if max_depth is not None:
+            recommended_depth = math.log2(n_samples)
+            if max_depth > recommended_depth:
+                warnings.append({
+                    "issue": "structural_overfitting_risk",
+                    "max_depth": max_depth,
+                    "recommended_max_depth": int(recommended_depth),
+                    "message": "Tree depth may be too high for dataset size."
+                })
+
+    if n_samples and n_features and n_features > n_samples:
+        warnings.append({
+            "issue": "high_feature_sample_ratio",
+            "message": "More features than samples can cause instability."
+        })
+
+    report["structural_warnings"] = warnings
+    return report

ai_critic-0.2.1/ai_critic/evaluators/data.py

@@ -0,0 +1,57 @@
+import numpy as np
+import matplotlib.pyplot as plt
+import seaborn as sns
+import pandas as pd
+
+def evaluate(X, y, plot=False):
+    report = {
+        "n_samples": int(X.shape[0]),
+        "n_features": int(X.shape[1]),
+        "has_nan": bool(np.isnan(X).any() or np.isnan(y).any())
+    }
+
+    # Class balance
+    if len(set(y)) < 20:
+        values, counts = np.unique(y, return_counts=True)
+        report["class_balance"] = {int(v): int(c) for v, c in zip(values, counts)}
+    else:
+        report["class_balance"] = "many_classes"
+
+    # Data leakage detection
+    suspicious_features = []
+    y_mean = np.mean(y)
+    y_centered = y - y_mean
+    for i in range(X.shape[1]):
+        feature = X[:, i]
+        if np.std(feature) == 0:
+            continue
+        corr = np.corrcoef(feature, y_centered)[0, 1]
+        if abs(corr) > 0.98:
+            suspicious_features.append({"feature_index": int(i), "correlation": float(corr)})
+
+    report["data_leakage"] = {
+        "suspected": bool(len(suspicious_features) > 0),
+        "details": suspicious_features,
+        "message": (
+            "Highly correlated features may reveal the target directly."
+            if suspicious_features else "No obvious data leakage detected."
+        )
+    }
+
+    # =========================
+    # Heatmap de correlação Features x Target
+    # =========================
+    if plot:
+        feature_names = [f"feat_{i}" for i in range(X.shape[1])]
+        df = pd.DataFrame(X, columns=feature_names)
+        df['target'] = y
+        corr_matrix = df.corr()
+
+        plt.figure(figsize=(10,8))
+        sns.heatmap(corr_matrix, annot=False, cmap="coolwarm")  # <- removi os números
+        plt.title("Correlação Features x Target")
+        plt.tight_layout()
+        plt.savefig("heatmap_correlation.png", dpi=150)  # Salva automaticamente
+        plt.show()
+
+    return report