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

ai_critic/critic.py

@@ -10,53 +10,92 @@ 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):
         """
         Evaluate the model.
 
-        Parameters:
-        -----------
+        Parameters
+        ----------
         view : str or list
-            - "all" : return full payload
-            - "executive" : only executive summary
-            - "technical" : only technical summary
-            - "details" : only low-level module outputs
-            - list : subset of views
+            - "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.evaluate(self.X, self.y, plot=plot)
+        # -------------------------
+        # Data analysis
+        # -------------------------
+        data_report = data.evaluate(
+            self.X,
+            self.y,
+            plot=plot
+        )
         details["data"] = data_report
 
-        # Model configuration
+        # -------------------------
+        # Model configuration sanity
+        # -------------------------
         details["config"] = config.evaluate(
             self.model,
             n_samples=data_report["n_samples"],
             n_features=data_report["n_features"]
         )
 
-        # Performance + learning curve
+        # -------------------------
+        # Performance evaluation
+        # (CV strategy inferred automatically)
+        # -------------------------
         details["performance"] = performance.evaluate(
-            self.model, self.X, self.y, plot=plot
+            self.model,
+            self.X,
+            self.y,
+            plot=plot
         )
 
-        # Robustness + CV clean vs noisy
+        # -------------------------
+        # Robustness & leakage analysis
+        # -------------------------
         details["robustness"] = robustness.evaluate(
             self.model,
             self.X,
@@ -66,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/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.2.dist-info/METADATA

@@ -1,225 +0,0 @@
-Metadata-Version: 2.4
-Name: ai-critic
-Version: 0.2.2
-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)
-[![Python Versions](https://img.shields.io/pypi/pyversions/ai-critic.svg)](https://pypi.org/project/ai-critic/)
-
-O **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 complexos em decisões claras e centradas no ser humano.
-
-Diferente das ferramentas tradicionais que focam apenas em métricas de desempenho, o **ai-critic** adota uma postura cética por design, respondendo à pergunta fundamental: **“Este modelo pode ser implantado com segurança?”**
-
----
-
-## 🚀 O que é o ai-critic?
-
-O `ai-critic` avalia modelos treinados antes da implantação, analisando quatro áreas principais de risco:
-
-*   **Integridade dos Dados:** (*data leakage*, desequilíbrio, NaNs).
-*   **Estrutura do Modelo:** (risco de *overfitting*, complexidade, configurações suspeitas).
-*   **Comportamento de Validação:** (pontuações suspeitamente perfeitas de cross-validation).
-*   **Robustez:** (sensibilidade a ruído e estabilidade do modelo).
-
-Os resultados são organizados em três camadas semânticas para diferentes *stakeholders*:
-*   **Executiva:** Decisões para stakeholders e gerentes.
-*   **Técnica:** Diagnósticos para engenheiros de ML.
-*   **Detalhada:** Saída completa de métricas e análises técnicas, incluindo gráficos opcionais.
-
----
-
-## 🎯 Por que o ai-critic Existe: Filosofia Central
-
-A maioria das ferramentas de ML tradicionais assume que métricas são a verdade absoluta, confia cegamente na validação cruzada e entrega números brutos sem interpretação.
-
-O **ai-critic** é cético por design. Ele trata:
-*   **Pontuações perfeitas** como sinais de alerta, não necessariamente sucesso.
-*   **Métricas de robustez** como dependentes do contexto.
-*   **Implantação** como uma decisão de gestão de risco, não apenas uma meta técnica.
-
-A filosofia central é: **Métricas não falham modelos — o contexto falha.** O `ai-critic` aplica heurísticas de raciocínio humano:
-*   “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`
-*   `matplotlib`, `seaborn`, `numpy`, `pandas` (para visualizações opcionais)
-
----
-
-## 💡 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)
-
-# 2. Inicializar e avaliar com ai-critic
-critic = AICritic(model, X, y)
-
-# Realização de avaliação completa (padrão view="all")
-report = critic.evaluate(plot=True)
-print(report)
-```
-
----
-
-## 🧩 Saída Multi-Camadas
-
-O `ai-critic` estrutura os resultados em camadas de decisão claras através do parâmetro `view`.
-
-### 🔹 Visualização Executiva (`view="executive"`)
-Projetado para stakeholders e gestores. Sem jargão técnico.
-
-```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. Focado em diagnósticos e ações corretivas.
-
-```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. Agrega todos os outputs dos módulos internos.
-
-```python
-details = critic.evaluate(view="details")
-print(details["data"]["class_balance"])
-print(details["robustness"]["performance_drop"])
-```
-
-### 🔹 Visualização Combinada (`view="all"`)
-Retorna todas as três camadas em um único dicionário, facilitando a integração com pipelines de CI/CD.
-
----
-
-## 📊 Visualizações e Gráficos
-
-Ao definir `plot=True` no método `evaluate()`, o `ai-critic` gera automaticamente:
-*   **Heatmap de Correlação:** Identificação visual de vazamento de dados.
-*   **Learning Curve:** Diagnóstico de overfitting e necessidade de mais dados.
-*   **Gráfico de Robustez:** Visualização da queda de performance sob ruído.
-
----
-
-## ⚙️ API Principal e Modularização
-
-### `AICritic(model, X, y)`
-*   `model`: Modelo `scikit-learn` treinado.
-*   `X`: Matriz de recursos.
-*   `y`: Vetor alvo.
-
-### `evaluate(view="all", plot=False)`
-*   `view`: Camada de saída (`"executive"`, `"technical"`, `"details"`, `"all"` ou lista customizada).
-*   `plot`: `True` para gerar gráficos automáticos.
-
-### Uso Modular (Avançado)
-Cada módulo retorna um dicionário padronizado consistente:
-```python
-from ai_critic.evaluators import data, config, performance, robustness
-
-data_report = data.evaluate(X, y, plot=True)
-config_report = config.evaluate(model, n_samples=data_report["n_samples"], n_features=data_report["n_features"])
-```
-
----
-
-## 🧠 O que o ai-critic Detecta
-
-| Categoria | Riscos Detectados |
-| :--- | :--- |
-| **🔍 Dados** | Vazamento de alvo via correlação, NaNs, desequilíbrio de classes. |
-| **🧱 Estrutura** | Árvores excessivamente complexas, altas taxas de recurso/amostra, configurações suspeitas. |
-| **📈 Validação** | Pontuações de CV suspeitosamente perfeitas, variância irreal. |
-| **🧪 Robustez** | Sensibilidade a ruído, robustez enganosa (stable, fragile, misleading). |
-
----
-
-## 🛡️ Melhores Práticas
-
-*   **CI/CD:** Use a Visualização Executiva como um portão de qualidade automatizado.
-*   **Debugging:** Use a Visualização Técnica durante a iteração do modelo.
-*   **Compliance:** Utilize a Visualização Detalhada para rastreabilidade e auditoria.
-*   **Ceticismo:** Nunca confie cegamente em pontuações de CV perfeitas.
-
----
-
-## 🧭 Casos de Uso Típicos
-*   Auditorias de modelo pré-implantação.
-*   Governança e conformidade de ML.
-*   Portões de modelo em pipelines CI/CD.
-*   Explicação de riscos para stakeholders não técnicos.
-
----
-
-## 📄 Licença
-
-Distribuído sob a **MIT License**.
-
----
-
-## 🧠 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.2.dist-info/RECORD

@@ -1,12 +0,0 @@
-ai_critic/__init__.py,sha256=H6DlPMmbcFUamhsNULPLk9vHx81XCiXuKKf63EJ8eM0,53
-ai_critic/critic.py,sha256=XShAtVzrvdqVSNVzzusDFSywOOmJYO-TjbodJXw9-IM,2521
-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=O9ZCrph93VV6pFcMIx2a7DizPIccRUqbGcUZ6oDmOLs,3791
-ai_critic-0.2.2.dist-info/METADATA,sha256=ZmxIS3QFXr8Lng4aM5c8Tuh65eUKxpIuXoGF6OGHW3s,7854
-ai_critic-0.2.2.dist-info/WHEEL,sha256=qELbo2s1Yzl39ZmrAibXA2jjPLUYfnVhUNTlyF1rq0Y,92
-ai_critic-0.2.2.dist-info/top_level.txt,sha256=TRyZkm1vyLLcFDg_80yeg5cHvPis_oW1Ti170417jkw,10
-ai_critic-0.2.2.dist-info/RECORD,,