ai-critic 0.2.0__py3-none-any.whl → 0.2.1__py3-none-any.whl

ai_critic/critic.py

@@ -10,7 +10,7 @@ from ai_critic.evaluators.summary import HumanSummary
 class AICritic:
     """
     Automated reviewer for scikit-learn models.
-    Produces a multi-layered risk assessment.
+    Produces a multi-layered risk assessment with visualizations.
     """
 
     def __init__(self, model, X, y):
@@ -18,7 +18,7 @@ class AICritic:
         self.X = X
         self.y = y
 
-    def evaluate(self, view="all"):
+    def evaluate(self, view="all", plot=False):
         """
         view:
             - "all"
@@ -26,6 +26,9 @@ class AICritic:
             - "technical"
             - "details"
             - list of views
+        plot:
+            - True: gera gráficos de learning curve, heatmap e robustez
+            - False: sem gráficos
         """
 
         # =========================
@@ -33,24 +36,29 @@ class AICritic:
         # =========================
         details = {}
 
-        data_report = data(self.X, self.y)
+        # 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
+            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"]
+            leakage_suspected=data_report["data_leakage"]["suspected"],
+            plot=plot
         )
 
         # =========================

ai_critic/evaluators/data.py

@@ -1,49 +1,57 @@
 import numpy as np
+import matplotlib.pyplot as plt
+import seaborn as sns
+import pandas as pd
 
-def evaluate(X, y):
+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 (JSON-safe)
+    # 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)
-        }
+        report["class_balance"] = {int(v): int(c) for v, c in zip(values, counts)}
     else:
         report["class_balance"] = "many_classes"
 
-    # 🔎 Data leakage detection (high correlation with target)
+    # 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)
-            })
+            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."
+            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

ai_critic/evaluators/performance.py

@@ -1,20 +1,43 @@
-from sklearn.model_selection import cross_val_score
+from sklearn.model_selection import cross_val_score, learning_curve
+import matplotlib.pyplot as plt
+import numpy as np
 
-def evaluate(model, X, y):
+def evaluate(model, X, y, plot=False):
+    # CV básico
     scores = cross_val_score(model, X, y, cv=3)
-
     mean = float(scores.mean())
     std = float(scores.std())
-
     suspicious = mean > 0.995
 
-    return {
+    result = {
         "cv_mean_score": mean,
         "cv_std": std,
         "suspiciously_perfect": suspicious,
         "message": (
             "Perfect CV score detected — possible data leakage."
-            if suspicious
-            else "CV performance within expected range."
+            if suspicious else "CV performance within expected range."
         )
     }
+
+    # =========================
+    # Learning curve
+    # =========================
+    if plot:
+        train_sizes, train_scores, test_scores = learning_curve(
+            model, X, y, cv=3, train_sizes=np.linspace(0.1, 1.0, 5)
+        )
+        plt.figure(figsize=(6,4))
+        plt.plot(train_sizes, np.mean(train_scores, axis=1), label="Treino")
+        plt.plot(train_sizes, np.mean(test_scores, axis=1), label="Validação")
+        plt.fill_between(train_sizes,
+                         np.mean(test_scores, axis=1)-np.std(test_scores, axis=1),
+                         np.mean(test_scores, axis=1)+np.std(test_scores, axis=1),
+                         alpha=0.2)
+        plt.xlabel("Amostra de treino")
+        plt.ylabel("Score")
+        plt.title("Learning Curve")
+        plt.legend()
+        plt.tight_layout()
+        plt.show()
+
+    return result

ai_critic/evaluators/robustness.py

@@ -1,10 +1,10 @@
 import numpy as np
 from sklearn.base import clone
 from sklearn.model_selection import cross_val_score
+import matplotlib.pyplot as plt
 
-def evaluate(model, X, y, leakage_suspected=False):
+def evaluate(model, X, y, leakage_suspected=False, plot=False):
     noise_level = 0.02  # 2% relative noise
-
     scale = np.std(X)
     noise = np.random.normal(0, noise_level * scale, X.shape)
     X_noisy = X + noise
@@ -12,18 +12,12 @@ def evaluate(model, X, y, leakage_suspected=False):
     model_clean = clone(model)
     model_noisy = clone(model)
 
-    score_clean = cross_val_score(
-        model_clean, X, y, cv=3, n_jobs=1
-    ).mean()
-
-    score_noisy = cross_val_score(
-        model_noisy, X_noisy, y, cv=3, n_jobs=1
-    ).mean()
-
+    score_clean = cross_val_score(model_clean, X, y, cv=3, n_jobs=1).mean()
+    score_noisy = cross_val_score(model_noisy, X_noisy, y, cv=3, n_jobs=1).mean()
     drop = score_clean - score_noisy
 
     # =========================
-    # Semantic robustness logic
+    # Verdict
     # =========================
     if leakage_suspected and score_clean > 0.98:
         verdict = "misleading"
@@ -38,6 +32,19 @@ def evaluate(model, X, y, leakage_suspected=False):
         verdict = "stable"
         message = "Model shows acceptable robustness to noise."
 
+    # =========================
+    # Plot CV Clean vs Noisy
+    # =========================
+    if plot:
+        plt.figure(figsize=(4,4))
+        plt.bar(["Original", "Com Ruído"], [score_clean, score_noisy], color=['green','red'])
+        plt.ylabel("CV Score")
+        plt.title("Robustez do Modelo")
+        plt.ylim(0, 1)
+        plt.tight_layout()
+        plt.savefig("robustness.png", dpi=150)  # Salva automaticamente
+        plt.show()
+
     return {
         "cv_score_original": float(score_clean),
         "cv_score_noisy": float(score_noisy),

{ai_critic-0.2.0.dist-info → ai_critic-0.2.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ai-critic
-Version: 0.2.0
+Version: 0.2.1
 Summary: Fast AI evaluator for scikit-learn models
 Author-email: Luiz Seabra <filipedemarco@yahoo.com>
 Requires-Python: >=3.9
@@ -8,68 +8,71 @@ Description-Content-Type: text/markdown
 Requires-Dist: numpy
 Requires-Dist: scikit-learn
 
-# ai-critic
+# ai-critic: Automated Risk Auditor for Machine Learning Models**
 
-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)
+## 🚀 What is ai-critic?
 
-## 🚀 O que é 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.
 
-**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:
+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:
-*   **Integridade dos Dados:** (vazamento de dados, desequilíbrio, valores NaNs)
+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*:
-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
+*   **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
-*   expõe números brutos sem interpretação
+*   despeja números brutos sem interpretação
 
-**ai-critic é cético por design.**
+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
+
+*   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.**
 
-ai-critic aplica heurísticas de raciocínio humano à avaliação de *machine learning*:
+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?”
-*   “A robustez ainda importa se a linha de base estiver errada?”
+*   “Isso pode estar vazando o alvo (*target*)?”
+*   “A robustez importa se a linha de base estiver errada?”
 
 ## 🛠️ Instalação
 
-Você pode instalar `ai-critic` usando pip:
+Instale o `ai-critic` via pip:
 
 ```bash
 pip install ai-critic
 ```
 
 **Requisitos:**
+
 *   Python ≥ 3.8
-*   scikit-learn
+*   `scikit-learn`
 
 ## 💡 Início Rápido
 
-Audite seu modelo treinado em poucas linhas de código:
+Audite seu modelo treinado em apenas algumas linhas:
 
 ```python
 from sklearn.datasets import load_breast_cancer
@@ -79,29 +82,30 @@ 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
+model.fit(X, y)  # O modelo deve 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)
+# A visualização padrã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.
+O `ai-critic` nunca despeja tudo de uma vez. Ele estrutura os resultados em camadas de decisão claras.
 
-### 🔹 Visão Executiva (`view="executive"`)
+### 🔹 Visualização Executiva (`view="executive"`)
 
-Projetada para CTOs, gerentes e *stakeholders*. Zero jargão de ML.
+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",
@@ -111,15 +115,16 @@ critic.evaluate(view="executive")
 }
 ```
 
-### 🔹 Visão Técnica (`view="technical"`)
+### 🔹 Visualização Técnica (`view="technical"`)
 
-Projetada para engenheiros de ML. É acionável, diagnóstica e focada no que precisa ser corrigido.
+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": [
@@ -141,22 +146,23 @@ critic.evaluate(view="technical")
 }
 ```
 
-### 🔹 Visão Detalhada (`view="details"`)
+### 🔹 Visualização Detalhada (`view="details"`)
 
-Projetada para auditoria, depuração e conformidade.
+Projetado para auditoria, depuração e conformidade.
 
 ```python
 critic.evaluate(view="details")
 ```
 
 Inclui:
+
 *   Métricas brutas
-*   Correlações
+*   Correlações de recursos
 *   Pontuações de robustez
 *   Avisos estruturais
 *   Rastreabilidade completa
 
-### 🔹 Visão Combinada (`view="all"`)
+### 🔹 Visualização Combinada (`view="all"`)
 
 Retorna todas as três camadas em um único dicionário.
 
@@ -165,6 +171,7 @@ critic.evaluate(view="all")
 ```
 
 **Retorna:**
+
 ```json
 {
   "executive": {...},
@@ -179,9 +186,9 @@ critic.evaluate(view="all")
 
 | Parâmetro | Descrição |
 | :--- | :--- |
-| `model` | Modelo `scikit-learn` treinado. |
-| `X` | Matriz de recursos (features). |
-| `y` | Vetor alvo (target). |
+| `model` | Modelo `scikit-learn` treinado |
+| `X` | Matriz de recursos |
+| `y` | Vetor alvo |
 
 **Uso:** `AICritic(model, X, y)`
 
@@ -189,24 +196,24 @@ critic.evaluate(view="all")
 
 | Parâmetro | Descrição |
 | :--- | :--- |
-| `view` | A camada de saída desejada: `"executive"`, `"technical"`, `"details"`, ou `"all"` (padrão). |
+| `view` | Camada de saída desejada: `"executive"`, `"technical"`, `"details"`, ou `"all"` (padrão) |
 
 **Uso:** `evaluate(view="all")`
 
-## 🧠 O que ai-critic Detecta
+## 🧠 O que o 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. |
+| **🔍 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: Detecção de Vazamento de Dados
+## 🧪 Exemplo: Detectando Vazamento de Dados
 
 ```python
 import numpy as np
-# ... (código de importação e modelo)
+# ... (imports e código do modelo)
 
 # Vazamento artificial: adicionando o alvo como um recurso
 X_leaky = np.hstack([X, y.reshape(-1, 1)])
@@ -217,7 +224,8 @@ executive_report = critic.evaluate(view="executive")
 print(executive_report)
 ```
 
-**Resultado (Executive View):**
+**Saída (Visualização Executiva):**
+
 ```
 ❌ Não Confiável
 Forte evidência de vazamento de dados inflando o desempenho do modelo.
@@ -225,26 +233,26 @@ Forte evidência de vazamento de dados inflando o desempenho do modelo.
 
 ## 🛡️ Melhores Práticas
 
-*   Execute `ai-critic` antes da implantação.
+*   Execute o `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.
+*   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.
-*   *Gates* de modelo em CI/CD.
-*   Ensino de ceticismo em ML.
-*   Explicação de risco de ML para *stakeholders* não técnicos.
+*   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**.
+Distribuído sob a Licença MIT.
 
 ## 🧠 Nota Final
 
-`ai-critic` não é uma ferramenta de *benchmark*. **É uma ferramenta de decisão.**
+O `ai-critic` não é uma ferramenta de *benchmarking*. É 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**.
+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.dist-info/RECORD

@@ -0,0 +1,12 @@
+ai_critic/__init__.py,sha256=H6DlPMmbcFUamhsNULPLk9vHx81XCiXuKKf63EJ8eM0,53
+ai_critic/critic.py,sha256=4fKwR7LtXGlQihstZWqauBZT2BmbaSLpuO9FBV42tus,2287
+ai_critic/evaluators/__init__.py,sha256=Jmmz9899YD__4Uj3bA6R7vYOwlH2giPc1wuCSLv7FVw,170
+ai_critic/evaluators/config.py,sha256=gBXaS8Qxl14f40JnvMWgA0Z0SGEtbCuCHpTOPem0H90,1163
+ai_critic/evaluators/data.py,sha256=YAK5NkwCeJOny_UueZ5ALwvEcRDIbEck404eV2oqWnc,1871
+ai_critic/evaluators/performance.py,sha256=JpXM_7-RN_q_FvXga4TkSVBBo90Nk0AdBWbjmS-D1oI,1469
+ai_critic/evaluators/robustness.py,sha256=UiGTpE-h2d2U19p1Ce4XpcMv4NMb2I4MmrlTrsPTIag,1808
+ai_critic/evaluators/summary.py,sha256=drP43HrWu1WJfLiUIQVczJ5Qs8sfoywpXFdavd2ogQI,3516
+ai_critic-0.2.1.dist-info/METADATA,sha256=TFYwZAG1AvWnvVweQpBS3p9obX11h_M_CNVFgzt6MLs,7064
+ai_critic-0.2.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+ai_critic-0.2.1.dist-info/top_level.txt,sha256=TRyZkm1vyLLcFDg_80yeg5cHvPis_oW1Ti170417jkw,10
+ai_critic-0.2.1.dist-info/RECORD,,

ai_critic-0.2.0.dist-info/RECORD

@@ -1,12 +0,0 @@
-ai_critic/__init__.py,sha256=H6DlPMmbcFUamhsNULPLk9vHx81XCiXuKKf63EJ8eM0,53
-ai_critic/critic.py,sha256=tGplbcJQgvXycuj9mIkYJkNQEMxHGC2Fpv946b05Ol4,1944
-ai_critic/evaluators/__init__.py,sha256=Jmmz9899YD__4Uj3bA6R7vYOwlH2giPc1wuCSLv7FVw,170
-ai_critic/evaluators/config.py,sha256=gBXaS8Qxl14f40JnvMWgA0Z0SGEtbCuCHpTOPem0H90,1163
-ai_critic/evaluators/data.py,sha256=CStPVKSNR9lXFtLNsNleH-uc52_RMKo2rc3cfFzeTTs,1315
-ai_critic/evaluators/performance.py,sha256=SWknmNiS9G7WWwmxJJNLL3R5i_I1ZLBIDLW_71jkKBQ,521
-ai_critic/evaluators/robustness.py,sha256=2xAZe-puoUE9tde5giKxlGpPs7oyU4y2t8DR4bGW0zs,1365
-ai_critic/evaluators/summary.py,sha256=drP43HrWu1WJfLiUIQVczJ5Qs8sfoywpXFdavd2ogQI,3516
-ai_critic-0.2.0.dist-info/METADATA,sha256=L78H-7HH9B47puaVCkTNfO44AqSOkPMzifVS2wQ6E98,7256
-ai_critic-0.2.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-ai_critic-0.2.0.dist-info/top_level.txt,sha256=TRyZkm1vyLLcFDg_80yeg5cHvPis_oW1Ti170417jkw,10
-ai_critic-0.2.0.dist-info/RECORD,,