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

ai_critic-0.2.0/PKG-INFO

@@ -0,0 +1,250 @@
+Metadata-Version: 2.4
+Name: ai-critic
+Version: 0.2.0
+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)
+
+## 🚀 O que é ai-critic?
+
+**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:
+
+> “Este modelo pode ser implantado com segurança?”
+
+Ele faz isso analisando:
+*   **Integridade dos Dados:** (vazamento de dados, desequilíbrio, valores 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
+
+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
+
+**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
+
+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*:
+*   “Isso é bom demais para ser verdade?”
+*   “Isso pode estar vazando o alvo?”
+*   “A robustez ainda importa se a linha de base estiver errada?”
+
+## 🛠️ Instalação
+
+Você pode instalar `ai-critic` usando pip:
+
+```bash
+pip install ai-critic
+```
+
+**Requisitos:**
+*   Python ≥ 3.8
+*   scikit-learn
+
+## 💡 Início Rápido
+
+Audite seu modelo treinado em poucas linhas de código:
+
+```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 precisa 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)
+print(report)
+```
+
+## 🧩 Saída Multi-Camadas
+
+`ai-critic` nunca despeja tudo de uma vez. Ele estrutura os resultados em camadas de decisão claras.
+
+### 🔹 Visão Executiva (`view="executive"`)
+
+Projetada para CTOs, gerentes e *stakeholders*. Zero 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."
+}
+```
+
+### 🔹 Visão Técnica (`view="technical"`)
+
+Projetada para engenheiros de ML. É acionável, diagnóstica e focada 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."
+  ]
+}
+```
+
+### 🔹 Visão Detalhada (`view="details"`)
+
+Projetada para auditoria, depuração e conformidade.
+
+```python
+critic.evaluate(view="details")
+```
+
+Inclui:
+*   Métricas brutas
+*   Correlações
+*   Pontuações de robustez
+*   Avisos estruturais
+*   Rastreabilidade completa
+
+### 🔹 Visã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 (features). |
+| `y` | Vetor alvo (target). |
+
+**Uso:** `AICritic(model, X, y)`
+
+### `evaluate()`
+
+| Parâmetro | Descrição |
+| :--- | :--- |
+| `view` | A camada de saída desejada: `"executive"`, `"technical"`, `"details"`, ou `"all"` (padrão). |
+
+**Uso:** `evaluate(view="all")`
+
+## 🧠 O que 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. |
+
+### 🧪 Exemplo: Detecção de Vazamento de Dados
+
+```python
+import numpy as np
+# ... (código de importação e 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)
+```
+
+**Resultado (Executive View):**
+```
+❌ Não Confiável
+Forte evidência de vazamento de dados inflando o desempenho do modelo.
+```
+
+## 🛡️ Melhores Práticas
+
+*   Execute `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.
+
+## 🧭 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.
+
+## 📄 Licença
+
+Distribuído sob a **Licença MIT**.
+
+## 🧠 Nota Final
+
+`ai-critic` não é uma ferramenta de *benchmark*. **É 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**.

ai_critic-0.2.0/README.md

@@ -0,0 +1,240 @@
+# 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)
+
+## 🚀 O que é ai-critic?
+
+**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:
+
+> “Este modelo pode ser implantado com segurança?”
+
+Ele faz isso analisando:
+*   **Integridade dos Dados:** (vazamento de dados, desequilíbrio, valores 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
+
+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
+
+**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
+
+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*:
+*   “Isso é bom demais para ser verdade?”
+*   “Isso pode estar vazando o alvo?”
+*   “A robustez ainda importa se a linha de base estiver errada?”
+
+## 🛠️ Instalação
+
+Você pode instalar `ai-critic` usando pip:
+
+```bash
+pip install ai-critic
+```
+
+**Requisitos:**
+*   Python ≥ 3.8
+*   scikit-learn
+
+## 💡 Início Rápido
+
+Audite seu modelo treinado em poucas linhas de código:
+
+```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 precisa 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)
+print(report)
+```
+
+## 🧩 Saída Multi-Camadas
+
+`ai-critic` nunca despeja tudo de uma vez. Ele estrutura os resultados em camadas de decisão claras.
+
+### 🔹 Visão Executiva (`view="executive"`)
+
+Projetada para CTOs, gerentes e *stakeholders*. Zero 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."
+}
+```
+
+### 🔹 Visão Técnica (`view="technical"`)
+
+Projetada para engenheiros de ML. É acionável, diagnóstica e focada 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."
+  ]
+}
+```
+
+### 🔹 Visão Detalhada (`view="details"`)
+
+Projetada para auditoria, depuração e conformidade.
+
+```python
+critic.evaluate(view="details")
+```
+
+Inclui:
+*   Métricas brutas
+*   Correlações
+*   Pontuações de robustez
+*   Avisos estruturais
+*   Rastreabilidade completa
+
+### 🔹 Visã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 (features). |
+| `y` | Vetor alvo (target). |
+
+**Uso:** `AICritic(model, X, y)`
+
+### `evaluate()`
+
+| Parâmetro | Descrição |
+| :--- | :--- |
+| `view` | A camada de saída desejada: `"executive"`, `"technical"`, `"details"`, ou `"all"` (padrão). |
+
+**Uso:** `evaluate(view="all")`
+
+## 🧠 O que 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. |
+
+### 🧪 Exemplo: Detecção de Vazamento de Dados
+
+```python
+import numpy as np
+# ... (código de importação e 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)
+```
+
+**Resultado (Executive View):**
+```
+❌ Não Confiável
+Forte evidência de vazamento de dados inflando o desempenho do modelo.
+```
+
+## 🛡️ Melhores Práticas
+
+*   Execute `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.
+
+## 🧭 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.
+
+## 📄 Licença
+
+Distribuído sob a **Licença MIT**.
+
+## 🧠 Nota Final
+
+`ai-critic` não é uma ferramenta de *benchmark*. **É 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**.

ai_critic-0.2.0/ai_critic/critic.py

@@ -0,0 +1,79 @@
+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.
+    """
+
+    def __init__(self, model, X, y):
+        self.model = model
+        self.X = X
+        self.y = y
+
+    def evaluate(self, view="all"):
+        """
+        view:
+            - "all"
+            - "executive"
+            - "technical"
+            - "details"
+            - list of views
+        """
+
+        # =========================
+        # Low-level technical details
+        # =========================
+        details = {}
+
+        data_report = data(self.X, self.y)
+        details["data"] = data_report
+
+        details["config"] = config(
+            self.model,
+            n_samples=data_report["n_samples"],
+            n_features=data_report["n_features"]
+        )
+
+        details["performance"] = performance(
+            self.model, self.X, self.y
+        )
+
+        details["robustness"] = robustness(
+            self.model,
+            self.X,
+            self.y,
+            leakage_suspected=data_report["data_leakage"]["suspected"]
+        )
+
+        # =========================
+        # 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.0/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.0/ai_critic/evaluators/data.py

@@ -0,0 +1,49 @@
+import numpy as np
+
+def evaluate(X, y):
+    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)
+    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 (high correlation with target)
+    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."
+        )
+    }
+
+    return report

ai_critic-0.2.0/ai_critic/evaluators/performance.py

@@ -0,0 +1,20 @@
+from sklearn.model_selection import cross_val_score
+
+def evaluate(model, X, y):
+    scores = cross_val_score(model, X, y, cv=3)
+
+    mean = float(scores.mean())
+    std = float(scores.std())
+
+    suspicious = mean > 0.995
+
+    return {
+        "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."
+        )
+    }