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

ai_critic/evaluators/summary.py

@@ -10,6 +10,10 @@ class HumanSummary:
         robustness_verdict = report["robustness"].get("verdict")
         structural_warnings = report["config"]["structural_warnings"]
 
+        explainability = report.get("explainability", {})
+        explain_verdict = explainability.get("verdict")
+        max_feature_drop = explainability.get("max_performance_drop", 0)
+
         # =========================
         # Executive summary
         # =========================
@@ -18,11 +22,19 @@ class HumanSummary:
             risk_level = "high"
             deploy = False
             main_reason = "Strong evidence of data leakage inflating model performance."
+        elif explain_verdict == "feature_leakage_risk":
+            verdict = "❌ Unreliable"
+            risk_level = "high"
+            deploy = False
+            main_reason = (
+                "Model behavior is dominated by a single feature, "
+                "suggesting shortcut learning or leakage."
+            )
         elif robustness_verdict in ("fragile", "misleading") or structural_warnings:
             verdict = "⚠️ Risky"
             risk_level = "medium"
             deploy = False
-            main_reason = "Structural or robustness-related risks detected."
+            main_reason = "Structural, robustness, or dependency-related risks detected."
         else:
             verdict = "✅ Acceptable"
             risk_level = "low"
@@ -71,6 +83,21 @@ class HumanSummary:
                 "Reduce model complexity or adjust hyperparameters."
             )
 
+        if explain_verdict == "feature_leakage_risk":
+            key_risks.append(
+                f"Single feature causes a {max_feature_drop:.2f} performance drop when permuted."
+            )
+            recommendations.append(
+                "Remove or heavily regularize the dominant feature and retrain."
+            )
+        elif explain_verdict == "feature_dependency":
+            key_risks.append(
+                "Model relies disproportionately on a small subset of features."
+            )
+            recommendations.append(
+                "Increase regularization or collect more diverse data."
+            )
+
         if robustness_verdict == "misleading":
             key_risks.append(
                 "Robustness metrics are misleading due to inflated baseline performance."
@@ -92,7 +119,8 @@ class HumanSummary:
                 "data_leakage": leakage,
                 "suspicious_cv": perfect_cv,
                 "structural_risk": bool(structural_warnings),
-                "robustness_verdict": robustness_verdict
+                "robustness_verdict": robustness_verdict,
+                "explainability_verdict": explain_verdict
             },
             "recommendations": recommendations
         }

ai_critic/feedback/__init__.py

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

ai_critic/feedback/store.py

@@ -0,0 +1,23 @@
+class FeedbackStore:
+    def __init__(self):
+        self.storage = []
+
+    def add(self, session_id, report, success: bool):
+        self.storage.append({
+            "session": session_id,
+            "success": success,
+            "report": report
+        })
+
+    def stats(self):
+        positives = sum(1 for x in self.storage if x["success"])
+        negatives = sum(1 for x in self.storage if not x["success"])
+
+        return {
+            "total": len(self.storage),
+            "positives": positives,
+            "negatives": negatives
+        }
+
+    def all(self):
+        return self.storage

ai_critic/learning/__init__.py

@@ -0,0 +1,13 @@
+from .features import extract_features
+from .critic_model import CriticModel
+from .trainer import CriticTrainer
+from .policy import policy_decision
+from .recommender import recommend_changes
+
+__all__ = [
+    "extract_features",
+    "CriticModel",
+    "CriticTrainer",
+    "policy_decision",
+    "recommend_changes",
+]

ai_critic/learning/critic_model.py

@@ -0,0 +1,25 @@
+import joblib
+from sklearn.linear_model import LogisticRegression
+import numpy as np
+
+class CriticModel:
+    def __init__(self, path="critic_model.joblib"):
+        self.path = path
+        self.model = LogisticRegression()
+        self.is_trained = False
+
+    def train(self, X, y):
+        self.model.fit(X, y)
+        self.is_trained = True
+        joblib.dump(self.model, self.path)
+
+    def load(self):
+        self.model = joblib.load(self.path)
+        self.is_trained = True
+
+    def predict_proba(self, features: dict) -> float:
+        if not self.is_trained:
+            return 0.5  # neutro
+
+        X = np.array([list(features.values())])
+        return float(self.model.predict_proba(X)[0][1])

ai_critic/learning/features.py

@@ -0,0 +1,15 @@
+def extract_features(report: dict) -> dict:
+    data = report["details"]["data"]
+    perf = report["details"]["performance"]
+    robust = report["details"]["robustness"]
+    config = report["details"]["config"]
+
+    return {
+        "n_samples": report["meta"]["n_samples"],
+        "n_features": report["meta"]["n_features"],
+        "data_leakage": int(data["data_leakage"]["suspected"]),
+        "perfect_cv": int(perf["suspiciously_perfect"]),
+        "robustness_fragile": int(robust["verdict"] == "fragile"),
+        "robustness_misleading": int(robust["verdict"] == "misleading"),
+        "structural_risk_high": int(config["risk_level"] == "high"),
+    }

ai_critic/learning/policy.py

@@ -0,0 +1,20 @@
+def policy_decision(rule_decision: dict, ml_score: float):
+    if rule_decision["risk_level"] == "high":
+        return {
+            "deploy": False,
+            "reason": "Blocked by rules",
+            "ml_score": ml_score
+        }
+
+    if ml_score < 0.4:
+        return {
+            "deploy": False,
+            "reason": "ML predicts failure",
+            "ml_score": ml_score
+        }
+
+    return {
+        "deploy": True,
+        "reason": "Approved by ML + rules",
+        "ml_score": ml_score
+    }

ai_critic/learning/recommender.py

@@ -0,0 +1,26 @@
+def recommend_changes(report):
+    recs = []
+
+    config = report["details"]["config"]
+    perf = report["details"]["performance"]
+    data = report["details"]["data"]
+
+    if config["risk_level"] == "high":
+        recs.append(
+            "Reduce model complexity (e.g., lower max_depth, fewer estimators)."
+        )
+
+    if perf["suspiciously_perfect"]:
+        recs.append(
+            "Suspiciously perfect performance detected — verify data leakage."
+        )
+
+    if data["data_leakage"]["suspected"]:
+        recs.append(
+            "Potential target leakage — review feature engineering pipeline."
+        )
+
+    if not recs:
+        recs.append("No critical changes recommended.")
+
+    return recs

ai_critic/learning/trainer.py

@@ -0,0 +1,16 @@
+from .features import extract_features
+
+class CriticTrainer:
+    def __init__(self, critic_model, min_samples=10):
+        self.model = critic_model
+        self.min_samples = min_samples
+        self.X = []
+        self.y = []
+
+    def add_feedback(self, report, success: bool):
+        features = extract_features(report)
+        self.X.append(list(features.values()))
+        self.y.append(int(success))
+
+        if len(self.y) >= self.min_samples:
+            self.model.train(self.X, self.y)

ai_critic/ml/suggester.py

@@ -0,0 +1,63 @@
+# ai_critic/ml/suggester.py
+
+def suggest_fix(event: dict) -> dict:
+    """
+    Lightweight ML-ready suggestion engine.
+    Today: rule-based.
+    Tomorrow: trained on global telemetry.
+    """
+
+    signals = event["signals"]
+    score = event["score"]
+
+    # 🔴 Casos críticos
+    if signals["leakage"] and signals["perfect_cv"]:
+        return {
+            "verdict": "critical",
+            "suggestion": (
+                "Strong evidence of data leakage. "
+                "Audit features highly correlated with the target, "
+                "remove shortcuts and re-run validation."
+            )
+        }
+
+    # 🟠 Robustez fraca
+    if signals["robustness"] == "fragile":
+        return {
+            "verdict": "warning",
+            "suggestion": (
+                "Model is fragile under noise. "
+                "Consider stronger regularization, "
+                "simpler architecture or more data."
+            )
+        }
+
+    # 🟠 Estrutura pesada
+    if signals["structural"] == "high":
+        return {
+            "verdict": "warning",
+            "suggestion": (
+                "Model complexity may be too high for dataset size. "
+                "Reduce depth, number of parameters or features."
+            )
+        }
+
+    # 🟢 Caso saudável
+    if score >= 85:
+        return {
+            "verdict": "ok",
+            "suggestion": (
+                "Model behavior looks consistent. "
+                "No critical risks detected at this stage."
+            )
+        }
+
+    # 🟡 Default
+    return {
+        "verdict": "review",
+        "suggestion": (
+            "No critical failures detected, "
+            "but model could benefit from further validation "
+            "and robustness checks."
+        )
+    }

ai_critic/telemetry/anonymizer.py

@@ -0,0 +1,9 @@
+def anonymize(report: dict) -> dict:
+    return {
+        "model_type": report["meta"]["model_type"],
+        "score": report["score"]["global"],
+        "signals": {
+            "leakage": report["details"]["data"]["data_leakage"]["suspected"],
+            "robustness": report["details"]["robustness"]["verdict"],
+        }
+    }

ai_critic/telemetry/client.py

@@ -0,0 +1,6 @@
+def collect_and_send(report, enabled=True):
+    if not enabled:
+        return
+
+    payload = anonymize(report)
+    send(payload)

ai_critic/telemetry/event.py

@@ -0,0 +1,15 @@
+def build_event(report: dict) -> dict:
+    return {
+        "model_type": report["meta"]["model_type"],
+        "framework": report["meta"]["framework"],
+        "n_samples": report["meta"]["n_samples"],
+        "n_features": report["meta"]["n_features"],
+        "score": report["scores"]["global"],
+        "risk_level": report["executive"]["risk_level"],
+        "signals": {
+            "leakage": report["details"]["data"]["data_leakage"]["suspected"],
+            "perfect_cv": report["details"]["performance"]["suspiciously_perfect"],
+            "robustness": report["details"]["robustness"]["verdict"],
+            "structural": report["details"]["config"]["risk_level"],
+        }
+    }

ai_critic/telemetry/local_store.py

@@ -0,0 +1,9 @@
+import json
+from pathlib import Path
+
+STORE = Path.home() / ".ai_critic" / "telemetry.jsonl"
+STORE.parent.mkdir(exist_ok=True)
+
+def save(event: dict):
+    with open(STORE, "a") as f:
+        f.write(json.dumps(event) + "\n")

ai_critic/telemetry/schema.py

@@ -0,0 +1,11 @@
+from dataclasses import dataclass
+
+@dataclass
+class TelemetryEvent:
+    model_type: str
+    framework: str
+    problem_type: str
+    n_samples: int
+    n_features: int
+    score: int
+    verdict: str

ai_critic/telemetry/sender.py

@@ -0,0 +1,9 @@
+def send(payload: dict):
+    try:
+        requests.post(
+            "https://api.ai-critic.dev/telemetry",
+            json=payload,
+            timeout=1
+        )
+    except Exception:
+        pass  # nunca quebra o usuário