ai-critic 0.2.1__tar.gz → 0.2.2__tar.gz

ai_critic-0.2.2/PKG-INFO

@@ -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.2/README.md

@@ -0,0 +1,215 @@
+# 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 → ai_critic-0.2.2}/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-0.2.1 → ai_critic-0.2.2}/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."],