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

ai_critic/critic.py

@@ -20,15 +20,19 @@ class AICritic:
 
     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" : return full payload
+            - "executive" : only executive summary
+            - "technical" : only technical summary
+            - "details" : only low-level module outputs
+            - list : subset of views
+        plot : bool
+            - True : generate plots (learning curve, heatmap, robustness)
+            - False : no plots
         """
 
         # =========================
@@ -37,23 +41,23 @@ class AICritic:
         details = {}
 
         # Data analysis + heatmap
-        data_report = data(self.X, self.y, plot=plot)
+        data_report = data.evaluate(self.X, self.y, plot=plot)
         details["data"] = data_report
 
         # Model configuration
-        details["config"] = config(
+        details["config"] = config.evaluate(
             self.model,
             n_samples=data_report["n_samples"],
             n_features=data_report["n_features"]
         )
 
         # Performance + learning curve
-        details["performance"] = performance(
+        details["performance"] = performance.evaluate(
             self.model, self.X, self.y, plot=plot
         )
 
         # Robustness + CV clean vs noisy
-        details["robustness"] = robustness(
+        details["robustness"] = robustness.evaluate(
             self.model,
             self.X,
             self.y,

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-0.2.2.dist-info/METADATA

@@ -0,0 +1,225 @@
+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.1.dist-info → ai_critic-0.2.2.dist-info}/RECORD

@@ -1,12 +1,12 @@
 ai_critic/__init__.py,sha256=H6DlPMmbcFUamhsNULPLk9vHx81XCiXuKKf63EJ8eM0,53
-ai_critic/critic.py,sha256=4fKwR7LtXGlQihstZWqauBZT2BmbaSLpuO9FBV42tus,2287
+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=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/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,,

{ai_critic-0.2.1.dist-info → ai_critic-0.2.2.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**.