ai-critic 0.2.5__py3-none-any.whl → 1.1.0__py3-none-any.whl

ai_critic/critic.py

@@ -2,14 +2,17 @@ from ai_critic.evaluators import (
     robustness,
     config,
     data,
-    performance
+    performance,
+    adapters  # <- novo import
 )
 from ai_critic.evaluators.summary import HumanSummary
+from ai_critic.sessions import CriticSessionStore
+from ai_critic.evaluators.scoring import compute_scores
 
 
 class AICritic:
     """
-    Automated reviewer for scikit-learn models.
+    Automated reviewer for scikit-learn, PyTorch, or TensorFlow models.
 
     Produces a multi-layered risk assessment including:
     - Data integrity analysis
@@ -19,22 +22,37 @@ class AICritic:
     - Human-readable executive and technical summaries
     """
 
-    def __init__(self, model, X, y, random_state=None):
+    def __init__(self, model, X, y, random_state=None, session=None, framework="sklearn", adapter_kwargs=None):
         """
         Parameters
         ----------
-        model : sklearn-compatible estimator
+        model : object
+            scikit-learn estimator, torch.nn.Module, or tf.keras.Model
         X : np.ndarray
             Feature matrix
         y : np.ndarray
             Target vector
         random_state : int or None
             Global seed for reproducibility (optional)
+        session : str or None
+            Optional session name for longitudinal comparison
+        framework : str
+            "sklearn" (default), "torch", or "tensorflow"
+        adapter_kwargs : dict
+            Extra kwargs para o adaptador (ex: epochs, lr, batch_size)
         """
-        self.model = model
+        adapter_kwargs = adapter_kwargs or {}
+        self.framework = framework.lower()
+        if self.framework != "sklearn":
+            self.model = adapters.ModelAdapter(model, framework=self.framework, **adapter_kwargs)
+        else:
+            self.model = model
+
         self.X = X
         self.y = y
         self.random_state = random_state
+        self.session = session
+        self._store = CriticSessionStore() if session else None
 
     def evaluate(self, view="all", plot=False):
         """
@@ -47,15 +65,10 @@ class AICritic:
             - "executive" : executive summary only
             - "technical" : technical summary only
             - "details" : low-level evaluator outputs
-            - list : subset of views (e.g. ["executive", "details"])
+            - list : subset of views
         plot : bool
-            - True : generate plots (learning curve, heatmap, robustness)
+            - True : generate plots
             - False : no plots
-
-        Returns
-        -------
-        dict
-            Evaluation payload according to selected view
         """
 
         # =========================
@@ -66,25 +79,23 @@ class AICritic:
         # -------------------------
         # Data analysis
         # -------------------------
-        data_report = data.evaluate(
+        details["data"] = data.evaluate(
             self.X,
             self.y,
             plot=plot
         )
-        details["data"] = data_report
 
         # -------------------------
         # Model configuration sanity
         # -------------------------
         details["config"] = config.evaluate(
             self.model,
-            n_samples=data_report["n_samples"],
-            n_features=data_report["n_features"]
+            n_samples=details["data"]["n_samples"],
+            n_features=details["data"]["n_features"]
         )
 
         # -------------------------
         # Performance evaluation
-        # (CV strategy inferred automatically)
         # -------------------------
         details["performance"] = performance.evaluate(
             self.model,
@@ -94,32 +105,36 @@ class AICritic:
         )
 
         # -------------------------
-        # Robustness & leakage analysis
+        # Robustness evaluation
         # -------------------------
         details["robustness"] = robustness.evaluate(
             self.model,
             self.X,
             self.y,
-            leakage_suspected=data_report["data_leakage"]["suspected"],
+            leakage_suspected=details["data"]["data_leakage"]["suspected"],
             plot=plot
         )
 
         # =========================
-        # Human-centered summaries
+        # Human summaries
         # =========================
         human_summary = HumanSummary().generate(details)
 
-        # =========================
-        # Full payload (PUBLIC API)
-        # =========================
         payload = {
             "executive": human_summary["executive_summary"],
             "technical": human_summary["technical_summary"],
             "details": details,
-            # Convenience shortcut (prevents KeyError in user code)
-            "performance": details["performance"]
+            "performance": details["performance"],
         }
 
+        # =========================
+        # Session persistence (optional)
+        # =========================
+        if self.session:
+            scores = compute_scores(payload)
+            payload["scores"] = scores
+            self._store.save(self.session, payload)
+
         # =========================
         # View selector
         # =========================
@@ -130,22 +145,56 @@ class AICritic:
             return {k: payload[k] for k in view if k in payload}
 
         return payload.get(view)
+
+    def compare_with(self, previous_session: str) -> dict:
+        """
+        Compare current session with a previous one.
+        """
+
+        if not self.session:
+            raise ValueError("Current session name not set.")
+
+        current = self._store.load(self.session)
+        previous = self._store.load(previous_session)
+
+        if not previous:
+            raise FileNotFoundError(
+                f"Session '{previous_session}' not found."
+            )
+
+        diff = {
+            "global_score": {
+                "current": current["scores"]["global"],
+                "previous": previous["scores"]["global"],
+                "delta": current["scores"]["global"] - previous["scores"]["global"],
+            },
+            "components": {}
+        }
+
+        for key, value in current["scores"]["components"].items():
+            prev_value = previous["scores"]["components"].get(key)
+            if prev_value is not None:
+                diff["components"][key] = {
+                    "current": value,
+                    "previous": prev_value,
+                    "delta": value - prev_value
+                }
+
+        return {
+            "current_session": self.session,
+            "previous_session": previous_session,
+            "score_diff": diff,
+            "note": (
+                "Score deltas indicate changes in risk profile, "
+                "not absolute model quality."
+            )
+        }
+
     def deploy_decision(self):
         """
         Final deployment gate.
-
-        Returns
-        -------
-        dict
-            {
-                "deploy": bool,
-                "risk_level": str,
-                "blocking_issues": list[str],
-                "confidence": float
-            }
         """
 
-        # Reusa TODA a pipeline existente
         report = self.evaluate(view="all", plot=False)
 
         data_risk = report["details"]["data"]["data_leakage"]["suspected"]
@@ -156,9 +205,7 @@ class AICritic:
         blocking_issues = []
         risk_level = "low"
 
-        # =========================
-        # Hard blockers (❌)
-        # =========================
+        # Hard blockers
         if data_risk and perfect_cv:
             blocking_issues.append(
                 "Data leakage combined with suspiciously perfect CV score"
@@ -177,9 +224,7 @@ class AICritic:
             )
             risk_level = "high"
 
-        # =========================
-        # Soft blockers (⚠️)
-        # =========================
+        # Soft blockers
         if risk_level != "high":
             if robustness_verdict == "fragile":
                 blocking_issues.append(
@@ -199,14 +244,8 @@ class AICritic:
                 )
                 risk_level = "medium"
 
-        # =========================
-        # Final decision
-        # =========================
         deploy = len(blocking_issues) == 0
 
-        # =========================
-        # Confidence heuristic
-        # =========================
         confidence = 1.0
         confidence -= 0.35 if data_risk else 0
         confidence -= 0.25 if perfect_cv else 0
@@ -220,4 +259,3 @@ class AICritic:
             "blocking_issues": blocking_issues,
             "confidence": confidence
         }
-

ai_critic/evaluators/adapters.py

@@ -0,0 +1,84 @@
+# evaluators/adapters.py
+import numpy as np
+
+try:
+    import torch
+    import torch.nn as nn
+except ImportError:
+    torch = None
+
+try:
+    import tensorflow as tf
+except ImportError:
+    tf = None
+
+class ModelAdapter:
+    """
+    Wraps scikit-learn, PyTorch, or TensorFlow models to provide a
+    unified fit/predict interface for AICritic.
+    """
+
+    def __init__(self, model, framework="sklearn", **kwargs):
+        """
+        Parameters
+        ----------
+        model : object
+            The original model (sklearn estimator, torch.nn.Module, or tf.keras.Model)
+        framework : str
+            One of "sklearn", "torch", "tensorflow"
+        kwargs : dict
+            Extra hyperparameters for training (epochs, batch_size, optimizer, etc)
+        """
+        self.model = model
+        self.framework = framework.lower()
+        self.kwargs = kwargs
+
+        if self.framework not in ("sklearn", "torch", "tensorflow"):
+            raise ValueError(f"Unsupported framework: {framework}")
+
+        # PyTorch default settings
+        if self.framework == "torch":
+            self.epochs = kwargs.get("epochs", 5)
+            self.lr = kwargs.get("lr", 1e-3)
+            self.loss_fn = kwargs.get("loss_fn", nn.MSELoss())
+            self.optimizer_class = kwargs.get("optimizer", torch.optim.Adam)
+            self.device = kwargs.get("device", "cpu")
+            self.model.to(self.device)
+
+        # TensorFlow default settings
+        if self.framework == "tensorflow":
+            self.epochs = kwargs.get("epochs", 5)
+            self.batch_size = kwargs.get("batch_size", 32)
+            self.loss_fn = kwargs.get("loss_fn", "mse")
+            self.optimizer = kwargs.get("optimizer", "adam")
+            self.model.compile(optimizer=self.optimizer, loss=self.loss_fn)
+
+    def fit(self, X, y):
+        if self.framework == "sklearn":
+            self.model.fit(X, y)
+        elif self.framework == "torch":
+            X_tensor = torch.tensor(X, dtype=torch.float32).to(self.device)
+            y_tensor = torch.tensor(y, dtype=torch.float32).to(self.device).view(-1, 1)
+            optimizer = self.optimizer_class(self.model.parameters(), lr=self.lr)
+
+            self.model.train()
+            for epoch in range(self.epochs):
+                optimizer.zero_grad()
+                output = self.model(X_tensor)
+                loss = self.loss_fn(output, y_tensor)
+                loss.backward()
+                optimizer.step()
+        elif self.framework == "tensorflow":
+            self.model.fit(X, y, epochs=self.epochs, batch_size=self.batch_size, verbose=0)
+        return self
+
+    def predict(self, X):
+        if self.framework == "sklearn":
+            return self.model.predict(X)
+        elif self.framework == "torch":
+            self.model.eval()
+            with torch.no_grad():
+                X_tensor = torch.tensor(X, dtype=torch.float32).to(self.device)
+                return self.model(X_tensor).cpu().numpy().flatten()
+        elif self.framework == "tensorflow":
+            return self.model.predict(X).flatten()

ai_critic/evaluators/scoring.py

@@ -0,0 +1,39 @@
+def compute_scores(report: dict) -> dict:
+    """
+    Converts critic signals into a coarse 0–100 score.
+    Score is NOT an objective metric.
+    """
+
+    score = 100
+
+    data_leakage = report["details"]["data"]["data_leakage"]["suspected"]
+    perfect_cv = report["details"]["performance"]["suspiciously_perfect"]
+    robustness = report["details"]["robustness"]["verdict"]
+    structural = report["details"]["config"]["structural_warnings"]
+
+    if data_leakage:
+        score -= 30
+
+    if perfect_cv:
+        score -= 20
+
+    if robustness == "fragile":
+        score -= 15
+    elif robustness == "misleading":
+        score -= 25
+
+    if structural:
+        score -= 10
+
+    return {
+        "global": max(0, min(100, score)),
+        "components": {
+            "data_integrity": 0 if data_leakage else 100,
+            "validation": 70 if perfect_cv else 100,
+            "robustness": {
+                "stable": 100,
+                "fragile": 65,
+                "misleading": 40
+            }.get(robustness, 100),
+        }
+    }

ai_critic/sessions/__init__.py

@@ -0,0 +1,3 @@
+from .store import CriticSessionStore
+
+__all__ = ["CriticSessionStore"]

ai_critic/sessions/store.py

@@ -0,0 +1,33 @@
+import json
+from pathlib import Path
+from datetime import datetime
+
+
+class CriticSessionStore:
+    """
+    Simple local persistence layer for ai-critic sessions.
+    """
+
+    def __init__(self, base_dir: str | None = None):
+        self.base_dir = Path(
+            base_dir or Path.home() / ".ai_critic_sessions"
+        )
+        self.base_dir.mkdir(parents=True, exist_ok=True)
+
+    def _session_path(self, name: str) -> Path:
+        return self.base_dir / f"{name}.json"
+
+    def save(self, name: str, payload: dict):
+        data = {
+            "timestamp": datetime.utcnow().isoformat(),
+            "payload": payload
+        }
+        with open(self._session_path(name), "w") as f:
+            json.dump(data, f, indent=2)
+
+    def load(self, name: str) -> dict | None:
+        path = self._session_path(name)
+        if not path.exists():
+            return None
+        with open(path) as f:
+            return json.load(f)["payload"]

ai_critic-1.1.0.dist-info/METADATA

@@ -0,0 +1,289 @@
+Metadata-Version: 2.4
+Name: ai-critic
+Version: 1.1.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 🧠: The Quality Gate for Machine Learning Models
+
+**ai-critic** is a specialized **decision-making** tool designed to audit the reliability and readiness for deployment of **scikit-learn**, **PyTorch**, and **TensorFlow** models.
+
+Instead of merely measuring performance (accuracy, F1 score), **ai-critic** acts as a **Quality Gate**, actively probing the model to uncover *hidden risks* that commonly cause production failures — such as **data leakage**, **structural overfitting**, and **fragility under noise**.
+
+> **ai-critic does not ask “How good is this model?”**
+> It asks **“Can this model be trusted?”**
+
+---
+
+## 🚀 Getting Started (The Basics)
+
+This section is ideal for beginners who need a **fast and reliable verdict** on a trained model.
+
+### Installation
+
+Install directly from PyPI:
+
+```bash
+pip install ai-critic
+```
+
+---
+
+### The Quick Verdict
+
+With just a few lines of code, you obtain an **executive-level assessment** and a **deployment recommendation**.
+
+```python
+from ai_critic import AICritic
+from sklearn.ensemble import RandomForestClassifier
+from sklearn.datasets import make_classification
+
+# 1. Prepare data and model
+X, y = make_classification(n_samples=1000, n_features=20, random_state=42)
+model = RandomForestClassifier(max_depth=5, random_state=42)
+
+# 2. Initialize the Critic
+critic = AICritic(model, X, y)
+
+# 3. Run the audit (executive mode)
+report = critic.evaluate(view="executive")
+
+print(f"Verdict: {report['verdict']}")
+print(f"Risk Level: {report['risk_level']}")
+print(f"Main Reason: {report['main_reason']}")
+```
+
+**Expected Output (example):**
+
+```text
+Verdict: ⚠️ Risky
+Risk Level: medium
+Main Reason: Structural or robustness-related risks detected.
+```
+
+This output is intentionally **conservative**.
+If **ai-critic** recommends deployment, it means meaningful risks were *not* detected.
+
+---
+
+## 💡 Understanding the Critique (The Intermediary)
+
+For data scientists who want to understand **why** the model received a given verdict and **how to improve it**.
+
+---
+
+### The Four Pillars of the Audit
+
+**ai-critic** evaluates models across four independent risk dimensions:
+
+| Pillar                 | Main Risk Detected                     | Internal Module          |
+| ---------------------- | -------------------------------------- | ------------------------ |
+| 📊 **Data Integrity**  | Target Leakage & Correlation Artifacts | `evaluators.data`        |
+| 🧠 **Model Structure** | Over-complexity & Misconfiguration     | `evaluators.config`      |
+| 📈 **Performance**     | Suspicious CV or Learning Curves       | `evaluators.performance` |
+| 🧪 **Robustness**      | Sensitivity to Noise                   | `evaluators.robustness`  |
+
+Each pillar contributes signals used later in the **deployment gate**.
+
+---
+
+### Full Technical & Visual Analysis
+
+To access **all internal diagnostics**, including plots and recommendations, use `view="all"`.
+
+```python
+full_report = critic.evaluate(view="all", plot=True)
+
+technical_summary = full_report["technical"]
+
+print("\n--- Key Risks Detected ---")
+for i, risk in enumerate(technical_summary["key_risks"], start=1):
+    print(f"{i}. {risk}")
+
+print("\n--- Recommendations ---")
+for rec in technical_summary["recommendations"]:
+    print(f"- {rec}")
+```
+
+Generated plots may include:
+
+* Feature correlation heatmaps
+* Learning curves
+* Robustness degradation charts
+
+---
+
+### Robustness Test (Noise Injection)
+
+A model that collapses under small perturbations is **not production-safe**.
+
+```python
+robustness = full_report["details"]["robustness"]
+
+print("\n--- Robustness Analysis ---")
+print(f"Original CV Score: {robustness['cv_score_original']:.4f}")
+print(f"Noisy CV Score: {robustness['cv_score_noisy']:.4f}")
+print(f"Performance Drop: {robustness['performance_drop']:.4f}")
+print(f"Verdict: {robustness['verdict']}")
+```
+
+**Possible Verdicts:**
+
+* `stable` → acceptable degradation
+* `fragile` → high sensitivity to noise
+* `misleading` → performance likely inflated by leakage
+
+---
+
+## ⚙️ Integration and Governance (The Advanced)
+
+This section targets **MLOps engineers**, **architects**, and teams operating automated pipelines.
+
+---
+
+### Multi-Framework Support
+
+**ai-critic 1.0+** supports models from multiple frameworks with the **same API**:
+
+```python
+# PyTorch Example
+import torch
+import torch.nn as nn
+from ai_critic import AICritic
+
+X = torch.randn(1000, 20)
+y = torch.randint(0, 2, (1000,))
+
+model = nn.Sequential(
+    nn.Linear(20, 32),
+    nn.ReLU(),
+    nn.Linear(32, 2)
+)
+
+critic = AICritic(model, X, y, framework="torch", adapter_kwargs={"epochs":5, "batch_size":64})
+report = critic.evaluate(view="executive")
+print(report)
+
+# TensorFlow Example
+import tensorflow as tf
+
+model = tf.keras.Sequential([
+    tf.keras.layers.Dense(32, activation="relu", input_shape=(20,)),
+    tf.keras.layers.Dense(2)
+])
+critic = AICritic(model, X.numpy(), y.numpy(), framework="tensorflow", adapter_kwargs={"epochs":5})
+report = critic.evaluate(view="executive")
+print(report)
+```
+
+> No need to rewrite evaluation code — **one Critic API works for sklearn, PyTorch, or TensorFlow**.
+
+---
+
+### The Deployment Gate (`deploy_decision`)
+
+The `deploy_decision()` method aggregates *all detected risks* and produces a final gate decision.
+
+```python
+decision = critic.deploy_decision()
+
+if decision["deploy"]:
+    print("✅ Deployment Approved")
+else:
+    print("❌ Deployment Blocked")
+
+print(f"Risk Level: {decision['risk_level']}")
+print(f"Confidence Score: {decision['confidence']:.2f}")
+
+print("\nBlocking Issues:")
+for issue in decision["blocking_issues"]:
+    print(f"- {issue}")
+```
+
+**Conceptual model:**
+
+* **Hard Blockers** → deployment denied
+* **Soft Blockers** → deployment discouraged
+* **Confidence Score (0–1)** → heuristic trust level
+
+---
+
+### Modes & Views (API Design)
+
+The `evaluate()` method supports **multiple modes** via the `view` parameter:
+
+| View          | Description                        |
+| ------------- | ---------------------------------- |
+| `"executive"` | High-level verdict (non-technical) |
+| `"technical"` | Risks & recommendations            |
+| `"details"`   | Raw evaluator outputs              |
+| `"all"`       | Complete payload                   |
+
+Example:
+
+```python
+critic.evaluate(view="technical")
+critic.evaluate(view=["executive", "performance"])
+```
+
+---
+
+### Session Tracking & Model Comparison
+
+You can persist evaluations and compare model versions over time.
+
+```python
+critic_v1 = AICritic(model, X, y, session="v1")
+critic_v1.evaluate()
+
+critic_v2 = AICritic(model, X, y, session="v2")
+critic_v2.evaluate()
+
+comparison = critic_v2.compare_with("v1")
+print(comparison["score_diff"])
+```
+
+This enables:
+
+* Regression tracking
+* Risk drift detection
+* Governance & audit trails
+
+---
+
+### Best Practices & Use Cases
+
+| Scenario                | Recommended Usage                      |
+| ----------------------- | -------------------------------------- |
+| **CI/CD**               | Block merges using `deploy_decision()` |
+| **Model Tuning**        | Use technical view for guidance        |
+| **Governance**          | Persist session outputs                |
+| **Stakeholder Reports** | Share executive summaries              |
+
+---
+
+## 🔒 API Stability
+
+Starting from version **1.0.0**, the public API of **ai-critic** follows semantic versioning.
+Breaking changes will only occur in major releases.
+
+---
+
+## 📄 License
+
+Distributed under the **MIT License**.
+
+---
+
+## 🧠 Final Note
+
+> **ai-critic is not a benchmarking tool.**
+> It is a *decision-making system*.
+
+A failed audit does **not** mean the model is bad — it means the model **is not ready to be trusted**.
+
+The purpose of **ai-critic** is to introduce *structured skepticism* into machine learning workflows — exactly where it belongs.

{ai_critic-0.2.5.dist-info → ai_critic-1.1.0.dist-info}/RECORD

@@ -1,13 +1,17 @@
 ai_critic/__init__.py,sha256=H6DlPMmbcFUamhsNULPLk9vHx81XCiXuKKf63EJ8eM0,53
-ai_critic/critic.py,sha256=Qewfu3mRRu1ORywij7zcEnL_kq_U-OUSHAG1PnTJdlA,6739
+ai_critic/critic.py,sha256=I9MeVHVCN-lWffPm3DJCgbFVVW8VTIs_qhXd-aP3X5Q,8277
 ai_critic/evaluators/__init__.py,sha256=ri6InmL8_LIcO-JZpU_gEFKLO4URdqo3z6rh7fV6M8Y,169
+ai_critic/evaluators/adapters.py,sha256=8Xw9Ccg1iGVNwVQDGVIqhWj5-Sg6evqCZhg21u8EP20,3068
 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/scoring.py,sha256=GBkmDa5Q6RZY4hJfzrCbxbBopsOsRjsNtzyoQHqgWHA,1046
 ai_critic/evaluators/summary.py,sha256=O9ZCrph93VV6pFcMIx2a7DizPIccRUqbGcUZ6oDmOLs,3791
 ai_critic/evaluators/validation.py,sha256=rnzRwD78Cugey33gl9geE8JoBURsKEEnqrIOhBZv0LY,904
-ai_critic-0.2.5.dist-info/METADATA,sha256=NNLka05cHrUg1YykLfivgXFmOs_KLy0ERvSEq8OksCk,6512
-ai_critic-0.2.5.dist-info/WHEEL,sha256=qELbo2s1Yzl39ZmrAibXA2jjPLUYfnVhUNTlyF1rq0Y,92
-ai_critic-0.2.5.dist-info/top_level.txt,sha256=TRyZkm1vyLLcFDg_80yeg5cHvPis_oW1Ti170417jkw,10
-ai_critic-0.2.5.dist-info/RECORD,,
+ai_critic/sessions/__init__.py,sha256=Yp7mphSPJwt8a4cJgcQNErqwqHVuP_xAJODrs0y0Abw,72
+ai_critic/sessions/store.py,sha256=65m9WXFVFWv4pPzvXV4l8zLHoHWMfCGe6eHh4X-8agY,947
+ai_critic-1.1.0.dist-info/METADATA,sha256=gIxyPwmDrmkqzZdLILBkq6uOl_2UAu5QRIV7Xis2rGc,8114
+ai_critic-1.1.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+ai_critic-1.1.0.dist-info/top_level.txt,sha256=TRyZkm1vyLLcFDg_80yeg5cHvPis_oW1Ti170417jkw,10
+ai_critic-1.1.0.dist-info/RECORD,,

{ai_critic-0.2.5.dist-info → ai_critic-1.1.0.dist-info}/WHEEL

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

ai_critic-0.2.5.dist-info/METADATA

@@ -1,200 +0,0 @@
-Metadata-Version: 2.4
-Name: ai-critic
-Version: 0.2.5
-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 🧠: The Quality Gate for Machine Learning Models
-
-**ai-critic** is a specialized **decision-making** tool designed to audit the reliability and readiness for deployment of scikit-learn compatible Machine Learning models.
-
-Instead of just measuring performance (accuracy, F1 score), **ai-critic** acts as a "Quality Gate," operating the model in search of hidden risks that can lead to production failures, such as data leaks, structural overfitting, and vulnerability to noise.
-
----
-
-## 🚀 1. Getting Started (The Basics)
-
-This section is ideal for beginners who need a quick verdict on the health of their model.
-
-### 1.1. Installation
-
-Install the library directly from PyPI:
-
-```bash
-pip install ai-critic
-```
-
-### 1.2. The Quick Verdict
-
-With just a few lines, you can get an executive evaluation and a deployment recommendation.
-
-```python
-from ai_critic import AICritic
-from sklearn.ensemble import RandomForestClassifier
-from sklearn.datasets import make_classification
-
-# 1. Prepare your data and model
-X, y = make_classification(n_samples=1000, n_features=20, random_state=42)
-model = RandomForestClassifier(max_depth=5, random_state=42)
-
-# 2. Initialize Criticism
-# AICritic performs all audits internally
-critic = AICritic(model, X, y)
-
-# 3. Obtain the Executive Summary
-report = critic.evaluate(view="executive")
-
-print(f"Verdict: {report['verdict']}")
-print(f"Risk: {report['risk_level']}")
-print(f"Reason Main: {report['main_reason']}")
-
-#Expected Output:
-
-# Verdict: ✅ Acceptable
-# Risk: Low
-# Main Reason: No critic risks detected.
-
-```
-
----
-
-## 💡 2. Understanding the Critique (The Intermediary)
-
-For the data scientist who needs to understand *why* the model received a verdict and what the next steps are.
-
-### 2.1. The Four Pillars of the Audit
-
-The **ai-critic** evaluates your model across four critic dimensions.
-
-| Category | Main Risk | Code Module |
-| :--- | :--- | :--- |
-| 📈 **Validation** | Suspicious CV Scores | `ai_critic.performance` |
-| 🧪 **Robustness** | Noise Vulnerability | `ai_critic.robustness` |
-
-2.2. Visual and Technical Analysis
-
-The `evaluate` method allows you to view the results and access the complete technical report.
-
-```Python
-# Continuing the previous example...
-
-# 1. Generate the full report and visualizations
-# plot=True generates Correlation, Learning Curve, and Robustness graphs
-full_report = critic.evaluate(view="all", plot=True)
-
-# 2. Access the Technical Summary for Recommendations
-technical_summary = full_report["technical"]
-
-print("\n--- Technical Recommendations ---")
-for i, risk in enumerate(technical_summary["key_risks"]):
-print(f"Risk {i+1}: {risk}")
-print(f"Recommendation: {technical_summary['recommendations'][i]}")
-
-# Example of Risk (if there were one):
-# Risk 1: The depth of the tree may be too high for the size of the dataset.
-
-# Recommendation: Reduce model complexity or adjust hyperparameters.
-
-
-###2.3. Robustness Test
-
-A robust model should maintain its performance even with small disturbances in the data. The `ai-critic` test assesses this by injecting noise into the input data.
-
-```python
-# Accessing the specific result of the Robustness module
-robustness_result = full_report["details"]["robustness"]
-
-print("\n--- Robustness Test ---")
-print(f"Original CV Score: {robustness_result['cv_score_original']:.4f}")
-print(f"CV Score with Noise: {robustness_result['cv_score_noisy']:.4f}")
-print(f"Performance Drop: {robustness_result['performance_drop']:.4f}")
-print(f"Robustness Verdict: {robustness_result['verdict']}")
-
-# Possible Verdicts:
-# - Stable: Acceptable drop.
-
-# - Fragile: Significant drop (risk).
-
-# - Misleading: Original performance inflated by leakage.
-
-```
-
----
-
-## ⚙️ 3. Integration and Governance (The Advanced)
-
-This section is for MLOps engineers and architects looking to integrate **ai-critic** into automated pipelines and create custom deployment logic.
-
-###3.1. The Deployment Gate (`deploy_decision`)
-
-The `deploy_decision()` method is the final control point. It returns a structured object that classifies problems into *Hard Blockers* (prevent deployment) and *Soft Blockers* (require attention, but can be accepted with reservations).
-
-Python
-# Example of use in a CI/CD pipeline
-decision = critic.deploy_decision()
-
-if decision["deploy"]:
-print("✅ Deployment Approved. Risk Level: Low.")
-other:
-print(f"❌ Deployment Blocked. Risk Level: {decision['risk_level'].upper()}")
-print("Blocking Issues:")
-for issue in decision["blocking_issues"]:
-print(f"- {problem}")
-
-# The decision object also includes a heuristic confidence score (0.0 to 1.0)
-print(f"Heuristic Confidence in Model: {decision['confidence']:.2f}")
-
-```
-
-###3.2. AccessFor custom *governance* rules or logic, you can access the raw data of each module through the `"details"` view.
-
-```python
-# Accessing Data Leakage Details
-data_details = critic.evaluate(view="details")["data"]
-
-if data_details["data_leakage"]["suspected"]:
-
-print("\n--- Data Leak Alert ---")
-
-for detail in data_details["data_leakage"]["details"]:
-
-print(f"Feature {detail['feature_index']} with correlation of {detail['correlation']:.4f}")
-
-# Accessing Structural Overfitting Details
-config_details = critic.evaluate(view="details")["config"]
-
-if config_details["structural_warnings"]:
-
-print("\n--- Structural Alert ---")
-
-for warning in config_details["structural_warnings"]:
-
-print(f"Warning: {warning['message']} (Max Depth: {warning['max_depth']}, Recommended: {warning['recommended_max_depth']})")
-```
-
-### 3.3. Best Practices and Use Cases
-
-| Use | Recommended Action |
-| :--- | :--- |
-| **CI/CD** | Use `deploy_decision()` as an automated quality gate. |
-| **Tuning** | Use the technical view to guide hyperparameter optimization. |
-| **Governance** | Log the details view for auditing and compliance. |
-| **Communication** | Use the executive view to report risks to non-technical stakeholders. |
-
----
-
-## 📄 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," but rather that it **shouldn't be trusted yet**. The goal is to inject the necessary skepticism to build truly robust AI systems.