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

ai_critic/critic.py

@@ -10,50 +10,93 @@ from ai_critic.evaluators.summary import HumanSummary
 class AICritic:
     """
     Automated reviewer for scikit-learn models.
-    Produces a multi-layered risk assessment with visualizations.
+
+    Produces a multi-layered risk assessment including:
+    - Data integrity analysis
+    - Model configuration sanity checks
+    - Performance evaluation (CV + learning curves)
+    - Robustness & leakage heuristics
+    - Human-readable executive and technical summaries
     """
 
-    def __init__(self, model, X, y):
+    def __init__(self, model, X, y, random_state=None):
+        """
+        Parameters
+        ----------
+        model : sklearn-compatible estimator
+        X : np.ndarray
+            Feature matrix
+        y : np.ndarray
+            Target vector
+        random_state : int or None
+            Global seed for reproducibility (optional)
+        """
         self.model = model
         self.X = X
         self.y = y
+        self.random_state = random_state
 
     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
+        Evaluate the model.
+
+        Parameters
+        ----------
+        view : str or list
+            - "all" : full payload (default)
+            - "executive" : executive summary only
+            - "technical" : technical summary only
+            - "details" : low-level evaluator outputs
+            - list : subset of views (e.g. ["executive", "details"])
+        plot : bool
+            - True : generate plots (learning curve, heatmap, robustness)
+            - False : no plots
+
+        Returns
+        -------
+        dict
+            Evaluation payload according to selected view
         """
 
         # =========================
-        # Low-level technical details
+        # Low-level evaluator outputs
         # =========================
         details = {}
 
-        # Data analysis + heatmap
-        data_report = data(self.X, self.y, plot=plot)
+        # -------------------------
+        # Data analysis
+        # -------------------------
+        data_report = data.evaluate(
+            self.X,
+            self.y,
+            plot=plot
+        )
         details["data"] = data_report
 
-        # Model configuration
-        details["config"] = config(
+        # -------------------------
+        # Model configuration sanity
+        # -------------------------
+        details["config"] = config.evaluate(
             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
+        # -------------------------
+        # Performance evaluation
+        # (CV strategy inferred automatically)
+        # -------------------------
+        details["performance"] = performance.evaluate(
+            self.model,
+            self.X,
+            self.y,
+            plot=plot
         )
 
-        # Robustness + CV clean vs noisy
-        details["robustness"] = robustness(
+        # -------------------------
+        # Robustness & leakage analysis
+        # -------------------------
+        details["robustness"] = robustness.evaluate(
             self.model,
             self.X,
             self.y,
@@ -62,17 +105,19 @@ class AICritic:
         )
 
         # =========================
-        # Human interpretation
+        # Human-centered summaries
         # =========================
-        human = HumanSummary().generate(details)
+        human_summary = HumanSummary().generate(details)
 
         # =========================
-        # Full payload
+        # Full payload (PUBLIC API)
         # =========================
         payload = {
-            "executive": human["executive_summary"],
-            "technical": human["technical_summary"],
-            "details": details
+            "executive": human_summary["executive_summary"],
+            "technical": human_summary["technical_summary"],
+            "details": details,
+            # Convenience shortcut (prevents KeyError in user code)
+            "performance": details["performance"]
         }
 
         # =========================

ai_critic/evaluators/__init__.py

@@ -1,4 +1,11 @@
-from .robustness import evaluate as robustness
-from .config import evaluate as config
-from .data import evaluate as data
-from .performance import evaluate as performance
+from . import data
+from . import performance
+from . import robustness
+from . import config
+
+__all__ = [
+    "data",
+    "performance",
+    "robustness",
+    "config",
+]

ai_critic/evaluators/performance.py

@@ -2,9 +2,21 @@ from sklearn.model_selection import cross_val_score, learning_curve
 import matplotlib.pyplot as plt
 import numpy as np
 
+from .validation import make_cv
+
+
 def evaluate(model, X, y, plot=False):
-    # CV básico
-    scores = cross_val_score(model, X, y, cv=3)
+    """
+    Avalia a performance do modelo usando validação cruzada
+    automaticamente adequada (StratifiedKFold ou KFold).
+    """
+
+    # =========================
+    # Cross-validation adaptativa
+    # =========================
+    cv = make_cv(y)
+
+    scores = cross_val_score(model, X, y, cv=cv)
     mean = float(scores.mean())
     std = float(scores.std())
     suspicious = mean > 0.995
@@ -13,9 +25,11 @@ def evaluate(model, X, y, plot=False):
         "cv_mean_score": mean,
         "cv_std": std,
         "suspiciously_perfect": suspicious,
+        "validation_strategy": type(cv).__name__,
         "message": (
             "Perfect CV score detected — possible data leakage."
-            if suspicious else "CV performance within expected range."
+            if suspicious
+            else "CV performance within expected range."
         )
     }
 
@@ -24,15 +38,30 @@ def evaluate(model, X, y, plot=False):
     # =========================
     if plot:
         train_sizes, train_scores, test_scores = learning_curve(
-            model, X, y, cv=3, train_sizes=np.linspace(0.1, 1.0, 5)
+            model,
+            X,
+            y,
+            cv=cv,  # <- MESMA estratégia de validação
+            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.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")

ai_critic/evaluators/robustness.py

@@ -12,8 +12,13 @@ def evaluate(model, X, y, leakage_suspected=False, plot=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()
+    from .validation import make_cv
+
+    cv = make_cv(y)
+
+    score_clean = cross_val_score(model_clean, X, y, cv=cv, n_jobs=1).mean()
+    score_noisy = cross_val_score(model_noisy, X_noisy, y, cv=cv, n_jobs=1).mean()
+
     drop = score_clean - score_noisy
 
     # =========================

ai_critic/evaluators/summary.py

@@ -78,6 +78,13 @@ class HumanSummary:
             recommendations.append(
                 "Fix baseline performance issues before trusting robustness metrics."
             )
+        elif robustness_verdict == "fragile":
+            key_risks.append(
+                "Model is fragile under noise perturbations."
+            )
+            recommendations.append(
+                "Consider regularization or simpler model architecture."
+            )
 
         technical_summary = {
             "key_risks": key_risks or ["No significant risks detected."],

ai_critic/evaluators/validation.py

@@ -0,0 +1,41 @@
+# validation.py
+import numpy as np
+from sklearn.model_selection import KFold, StratifiedKFold
+
+def infer_problem_type(y):
+    """
+    Infer whether the task is classification or regression.
+    """
+    y = np.asarray(y)
+
+    unique_values = np.unique(y)
+    n_unique = len(unique_values)
+
+    # Heurística conservadora
+    if (
+        np.issubdtype(y.dtype, np.integer)
+        or n_unique <= 20
+    ):
+        return "classification"
+
+    return "regression"
+
+
+def make_cv(y, n_splits=3, random_state=42):
+    """
+    Automatically selects the correct CV strategy.
+    """
+    problem_type = infer_problem_type(y)
+
+    if problem_type == "classification":
+        return StratifiedKFold(
+            n_splits=n_splits,
+            shuffle=True,
+            random_state=random_state
+        )
+
+    return KFold(
+        n_splits=n_splits,
+        shuffle=True,
+        random_state=random_state
+    )

ai_critic-0.2.3.dist-info/METADATA

@@ -0,0 +1,76 @@
+Metadata-Version: 2.4
+Name: ai-critic
+Version: 0.2.3
+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
+
+Performance under noise
+
+> Visualizations are optional and do not affect the decision logic.
+
+---
+
+## ⚙️ Main API
+
+### `AICritic(model, X, y)`
+
+* `model`: scikit-learn compatible estimator
+* `X`: feature matrix
+* `y`: target vector
+
+### `evaluate(view="all", plot=False)`
+
+* `view`: `"executive"`, `"technical"`, `"details"`, `"all"` or custom list
+* `plot`: generates graphs when `True`
+
+---
+
+## 🧠 What ai-critic Detects
+
+| Category | Risks |
+
+| ------------ | ---------------------------------------- |
+
+| 🔍 Data | Target Leakage, NaNs, Imbalance |
+
+| 🧱 Structure | Excessive Complexity, Overfitting |
+
+| 📈 Validation | Perfect or Statistically Suspicious CV |
+
+| 🧪 Robustness | Stable, Fragile, or Misleading |
+
+---
+
+## 🛡️ Best Practices
+
+* **CI/CD:** Use executive output as a *quality gate*
+* **Iteration:** Use technical output during tuning
+* **Governance:** Log detailed output
+* **Skepticism:** Never blindly trust a perfect CV
+
+---
+
+## 🧭 Use Cases
+
+* Pre-deployment Audit
+* ML Governance
+* CI/CD Pipelines
+* Risk Communication for Non-Technical Users
+
+---
+
+## 📄 License
+
+Distributed under the **MIT License**.
+
+---
+
+## 🧠 Final Note
+
+**ai-critic** is not a *benchmarking* tool. It's a **decision-making tool**.
+
+If a model fails here, it doesn't mean it's bad—it means it **shouldn't be trusted yet**.

ai_critic-0.2.3.dist-info/RECORD

@@ -0,0 +1,13 @@
+ai_critic/__init__.py,sha256=H6DlPMmbcFUamhsNULPLk9vHx81XCiXuKKf63EJ8eM0,53
+ai_critic/critic.py,sha256=0fsMpvvV4JSp59vsj4ie9xUSJcTpzM1P8MBRtYKHzxc,3785
+ai_critic/evaluators/__init__.py,sha256=ri6InmL8_LIcO-JZpU_gEFKLO4URdqo3z6rh7fV6M8Y,169
+ai_critic/evaluators/config.py,sha256=gBXaS8Qxl14f40JnvMWgA0Z0SGEtbCuCHpTOPem0H90,1163
+ai_critic/evaluators/data.py,sha256=YAK5NkwCeJOny_UueZ5ALwvEcRDIbEck404eV2oqWnc,1871
+ai_critic/evaluators/performance.py,sha256=1CQx5DueK0XkelYyJnAGRJ3AjQtjsKeW8_1JQZqKVOI,1973
+ai_critic/evaluators/robustness.py,sha256=mfVQ67Z6t6aRvtIq-XQEQYbwvyf8UefM1myeOGVrnAE,1869
+ai_critic/evaluators/summary.py,sha256=O9ZCrph93VV6pFcMIx2a7DizPIccRUqbGcUZ6oDmOLs,3791
+ai_critic/evaluators/validation.py,sha256=rnzRwD78Cugey33gl9geE8JoBURsKEEnqrIOhBZv0LY,904
+ai_critic-0.2.3.dist-info/METADATA,sha256=znefvwZLLg1yHQSrlVyO0M_97T3gJrt0N_mN0xDKUiM,1615
+ai_critic-0.2.3.dist-info/WHEEL,sha256=qELbo2s1Yzl39ZmrAibXA2jjPLUYfnVhUNTlyF1rq0Y,92
+ai_critic-0.2.3.dist-info/top_level.txt,sha256=TRyZkm1vyLLcFDg_80yeg5cHvPis_oW1Ti170417jkw,10
+ai_critic-0.2.3.dist-info/RECORD,,

{ai_critic-0.2.1.dist-info → ai_critic-0.2.3.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.9.0)
+Generator: setuptools (80.10.1)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

ai_critic-0.2.1.dist-info/METADATA

@@ -1,258 +0,0 @@
-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.dist-info/RECORD

@@ -1,12 +0,0 @@
-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,,