nous 0.0.1__py3-none-any.whl → 0.2.0__py3-none-any.whl

nous/__init__.py

@@ -1,2 +1,103 @@
-# nous/__init__.py
-__version__ = "0.0.1"
+from .version import __version__
+from .model import NousNet
+from .facts import BetaFactLayer, PiecewiseLinearCalibrator
+from .prototypes import ScaledPrototypeLayer
+from .rules import FixedPairRuleLayer, SoftmaxRuleLayer, SparseRuleLayer, SimpleNousBlock
+
+# Explainability (core API)
+from .explain import (
+    rule_impact_df,
+    minimal_sufficient_explanation,
+    select_pruning_threshold_global,
+    select_pruning_threshold_global_bs,
+    global_rulebook,
+    generate_enhanced_explanation,
+    explanation_fidelity_metrics,
+    explanation_stability,
+    aggregator_mixture_report,
+    suggest_rule_counterfactuals,
+    render_fact_descriptions,
+    AGG_NAMES,
+)
+from .explain.aggregator import format_agg_mixture
+
+# Prototype tracing utilities
+from .explain.traces import (
+    describe_prototype,
+    prototype_report_global,
+    prototype_contribution_df,
+    prototype_top_rules,
+    trace_rule_to_base_facts,
+    get_last_block_static_metadata,
+)
+
+# Export utilities
+from .export import (
+    export_numpy_inference,
+    validate_numpy_vs_torch,
+    export_and_validate,
+    load_numpy_module,
+)
+
+# Training and evaluation
+from .training import (
+    train_model,
+    evaluate_classification,
+    evaluate_regression,
+    make_sparse_regression_hook,
+)
+
+# Dataset helpers (used in examples)
+from .data import get_wine_data, get_california_housing_data
+
+# Utilities
+from .utils import set_global_seed
+
+__all__ = [
+    "__version__",
+    # Core model and components
+    "NousNet",
+    "BetaFactLayer",
+    "PiecewiseLinearCalibrator",
+    "ScaledPrototypeLayer",
+    "FixedPairRuleLayer",
+    "SoftmaxRuleLayer",
+    "SparseRuleLayer",
+    "SimpleNousBlock",
+    # Explainability (core)
+    "rule_impact_df",
+    "minimal_sufficient_explanation",
+    "select_pruning_threshold_global",
+    "select_pruning_threshold_global_bs",
+    "global_rulebook",
+    "generate_enhanced_explanation",
+    "explanation_fidelity_metrics",
+    "explanation_stability",
+    "aggregator_mixture_report",
+    "suggest_rule_counterfactuals",
+    "render_fact_descriptions",
+    "AGG_NAMES",
+    "format_agg_mixture",
+    # Prototype tracing utilities
+    "describe_prototype",
+    "prototype_report_global",
+    "prototype_contribution_df",
+    "prototype_top_rules",
+    "trace_rule_to_base_facts",
+    "get_last_block_static_metadata",
+    # Export utilities
+    "export_numpy_inference",
+    "validate_numpy_vs_torch",
+    "export_and_validate",
+    "load_numpy_module",
+    # Training and evaluation
+    "train_model",
+    "evaluate_classification",
+    "evaluate_regression",
+    "make_sparse_regression_hook",
+    # Dataset helpers
+    "get_wine_data",
+    "get_california_housing_data",
+    # Utilities
+    "set_global_seed",
+]

nous/data/__init__.py

@@ -0,0 +1,4 @@
+from .wine import get_wine_data
+from .california import get_california_housing_data
+
+__all__ = ["get_wine_data", "get_california_housing_data"]

nous/data/california.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+import numpy as np
+from typing import Tuple, List
+from sklearn.model_selection import train_test_split
+from sklearn.preprocessing import StandardScaler
+from sklearn.datasets import fetch_california_housing
+
+def get_california_housing_data(scale_y: bool = True):
+    """
+    Load California Housing and return standardized X and (optionally) standardized y.
+    Returns
+    -------
+    X_train, X_val, X_test, y_train, y_val, y_test, feature_names, class_names, task_type, y_scaler
+    """
+    data = fetch_california_housing()
+    X, y = data.data, data.target
+    feature_names = data.feature_names
+
+    X_train_full, X_test, y_train_full, y_test = train_test_split(X, y, test_size=0.2, random_state=42)
+
+    x_scaler = StandardScaler()
+    X_train_full = x_scaler.fit_transform(X_train_full)
+    X_test = x_scaler.transform(X_test)
+
+    X_train, X_val, y_train, y_val = train_test_split(X_train_full, y_train_full, test_size=0.2, random_state=42)
+
+    y_scaler = None
+    if scale_y:
+        y_scaler = StandardScaler()
+        y_train = y_scaler.fit_transform(y_train.reshape(-1,1)).ravel()
+        y_val   = y_scaler.transform(y_val.reshape(-1,1)).ravel()
+    return X_train, X_val, X_test, y_train, y_val, y_test, feature_names, None, "regression", y_scaler

nous/data/wine.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+import numpy as np
+from typing import Tuple, List
+from sklearn.model_selection import train_test_split
+from sklearn.preprocessing import StandardScaler, LabelEncoder
+
+def get_wine_data():
+    """
+    Load Wine dataset via ucimlrepo and return standardized splits.
+    Returns
+    -------
+    X_train, X_val, X_test, y_train, y_val, y_test, feature_names, class_names, task_type, y_scaler
+    """
+    from ucimlrepo import fetch_ucirepo
+    wine = fetch_ucirepo(id=109)
+    X, y_df = wine.data.features, wine.data.targets
+    feature_names = X.columns.tolist()
+    y = LabelEncoder().fit_transform(y_df.values.ravel())
+    class_names = [f"Class_{i+1}" for i in range(len(np.unique(y)))]
+    X_train_full, X_test, y_train_full, y_test = train_test_split(
+        X, y, test_size=0.2, random_state=42, stratify=y
+    )
+    preprocessor = StandardScaler()
+    X_train_full = preprocessor.fit_transform(X_train_full)
+    X_test = preprocessor.transform(X_test)
+    X_train, X_val, y_train, y_val = train_test_split(
+        X_train_full, y_train_full, test_size=0.2, random_state=42, stratify=y_train_full
+    )
+    return X_train, X_val, X_test, y_train, y_val, y_test, feature_names, class_names, "classification", None

nous/explain/__init__.py

@@ -0,0 +1,26 @@
+from .aggregator import AGG_NAMES, aggregator_mixture_report, format_agg_mixture
+from .facts_desc import render_fact_descriptions
+from .loo import rule_impact_df
+from .mse import minimal_sufficient_explanation
+from .pruning import select_pruning_threshold_global, select_pruning_threshold_global_bs
+from .global_book import global_rulebook
+from .generate import generate_enhanced_explanation
+from .fidelity import explanation_fidelity_metrics
+from .stability import explanation_stability
+from .cf import suggest_rule_counterfactuals
+
+__all__ = [
+    "AGG_NAMES",
+    "aggregator_mixture_report",
+    "format_agg_mixture",
+    "render_fact_descriptions",
+    "rule_impact_df",
+    "minimal_sufficient_explanation",
+    "select_pruning_threshold_global",
+    "select_pruning_threshold_global_bs",
+    "global_rulebook",
+    "generate_enhanced_explanation",
+    "explanation_fidelity_metrics",
+    "explanation_stability",
+    "suggest_rule_counterfactuals",
+]

nous/explain/aggregator.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+import numpy as np
+import pandas as pd
+from typing import List
+from ..model import NousNet
+
+AGG_NAMES = ['AND', 'OR', 'k-of-n', 'NOT']
+
+def format_agg_mixture(weights) -> str:
+    parts = []
+    for i in range(weights.shape[0]):
+        w = float(weights[i])
+        if w > 1e-6:
+            parts.append(f"{w:.2f} {AGG_NAMES[i]}")
+    return " + ".join(parts) if parts else "∅"
+
+def aggregator_mixture_report(model: NousNet, X, max_samples: int = 1000, device=None) -> pd.DataFrame:
+    device = device or next(model.parameters()).device
+    n = min(len(X), max_samples)
+    acc = []
+    for i in range(n):
+        _, _, internals = model.forward_explain(X[i], device=device)
+        for key in [k for k in internals.keys() if k.startswith("block_")]:
+            aw = internals[key]['aggregator_weights']
+            if aw is None:
+                continue
+            acc.append(aw.cpu().numpy())
+    if not acc:
+        return pd.DataFrame(columns=["AND", "OR", "k-of-n", "NOT", "entropy"])
+    A = np.concatenate(acc, axis=0)
+    mean = A.mean(axis=0)
+    ent = (-A * np.clip(np.log(A + 1e-12), -50, 50)).sum(axis=1).mean()
+    cols = AGG_NAMES[:A.shape[1]]
+    return pd.DataFrame([dict(**{c: float(v) for c, v in zip(cols, mean)}, entropy=float(ent))])

nous/explain/cf.py

@@ -0,0 +1,137 @@
+from __future__ import annotations
+import numpy as np
+import torch
+from typing import Optional, Sequence, List, Dict, Any
+from ..model import NousNet
+from .loo import rule_impact_df
+
+def suggest_rule_counterfactuals(
+    model: NousNet, x_sample, feature_names: Sequence[str], class_names: Optional[Sequence[str]] = None,
+    target: str = "flip",              # 'flip' (classification), 'margin_drop', 'reg_delta'
+    target_value: Optional[float] = None,  # for margin_drop/reg_delta
+    y_scaler=None,
+    k_rules: int = 3, fact_target_level: float = 0.1, max_features: int = 2,
+    loo_mode: str = 'frozen', top_m_rules: int = 10, use_pre_norm: bool = False,
+    alphas: Sequence[float] = (0.5, 1.0, 1.5, 2.0),
+    device=None
+) -> List[Dict[str, Any]]:
+    """
+    Suggest counterfactual input deltas guided by influential rules using β-fact geometry.
+    Verifies suggested deltas by forward_explain.
+    """
+    device = device or next(model.parameters()).device
+    task = model.config['task_type']
+
+    base_probas, base_logits, base_internals = model.forward_explain(x_sample, device=device)
+    if task == "classification":
+        pred_idx = int(np.argmax(base_probas))
+        runner_up = int(np.argsort(base_logits)[-2]) if base_logits.size > 1 else pred_idx
+        base_margin = float(base_logits[pred_idx] - base_logits[runner_up])
+    else:
+        base_pred = float(base_logits[0])
+
+    imp = rule_impact_df(
+        model, x_sample, feature_names, class_names=class_names,
+        loo_mode=loo_mode, top_m_rules=top_m_rules, use_pre_norm=use_pre_norm
+    )
+    if imp.empty:
+        return []
+
+    if task == "classification":
+        margin_col = [c for c in imp.columns if c.startswith("Δmargin(")][0]
+        imp = imp.sort_values(by=margin_col, ascending=False)
+    else:
+        imp = imp.sort_values(by="Δprediction", ascending=False)
+    imp = imp.head(k_rules)
+
+    x = torch.tensor(x_sample, dtype=torch.float32, device=device).unsqueeze(0)
+    if model.calibrators is not None:
+        x_cal = torch.stack([calib(x[:, i]) for i, calib in enumerate(model.calibrators)], dim=1)
+    else:
+        x_cal = x
+    diff, k_vec, nu_vec, net_w = model.fact.compute_diff_and_params(x_cal)  # [1,F], [F], [F], [F,D]
+    facts_act = model.fact(x_cal).squeeze(0)
+
+    suggestions = []
+    for _, row in imp.iterrows():
+        b = int(row["block"]) - 1
+        r = int(row["rule"]) - 1
+        details = base_internals[f'block_{b}']
+        facts_used = details.get("facts_used", None)
+        if isinstance(facts_used, torch.Tensor):
+            facts_used = facts_used.cpu().numpy()
+        if facts_used is None or facts_used.shape[0] <= r:
+            continue
+        used = facts_used[r]
+        used = [int(used)] if np.ndim(used) == 0 else [int(u) for u in used.tolist()]
+
+        used_sorted = sorted(used, key=lambda fid: float(facts_act[fid].item()), reverse=True)[:max(1, min(len(used), 2))]
+
+        deltas: Dict[int, float] = {}
+        for fid in used_sorted:
+            y_now = float(facts_act[fid].item()) + 1e-12
+            kf = float(k_vec[fid].item())
+            nuf = float(nu_vec[fid].item())
+            diff_now = float(diff[0, fid].item())
+            w = net_w[fid].detach().clone()  # [D]
+
+            y_target = float(fact_target_level)
+            # Invert β: diff_target = (logit(y_target^(1/nu))) / k
+            diff_target = float(torch.logit(torch.tensor(y_target, device=device).pow(1.0/max(nuf,1e-6))))
+            diff_target = diff_target / max(kf, 1e-6)
+            delta_diff = diff_target - diff_now
+
+            w_np = w.cpu().numpy()
+            idxs = np.argsort(-np.abs(w_np))[:max_features]
+            w_sel = torch.zeros_like(w)
+            w_sel[idxs] = w[idxs]
+            denom = float(w_sel.pow(2).sum().item())
+            if denom < 1e-12:
+                continue
+            delta_x_cal = (delta_diff / denom) * w_sel  # minimal L2 shift in x̃
+
+            delta_x = delta_x_cal.clone()
+            if model.calibrators is not None:
+                for i in idxs:
+                    xi = x[0, i]
+                    slope_i = model.calibrators[i].local_slope(xi)
+                    delta_x[i] = delta_x_cal[i] / slope_i
+
+            for i in idxs:
+                deltas[i] = deltas.get(i, 0.0) + float(delta_x[i].item())
+
+        if not deltas:
+            continue
+
+        feat_deltas = sorted([(feature_names[i], d) for i, d in deltas.items()], key=lambda t: -abs(t[1]))
+        success = False
+        new_out = None
+        for a in alphas:
+            x_try = x.clone()
+            for i, d in deltas.items():
+                x_try[0, i] = x_try[0, i] + a * d
+            prob2, logit2, _ = model.forward_explain(x_try.squeeze(0).cpu().numpy(), device=device)
+            if task == "classification":
+                new_pred = int(np.argmax(prob2))
+                new_margin = float(logit2[pred_idx] - logit2[runner_up])
+                if target == "flip" and new_pred != pred_idx:
+                    success, new_out = True, {"pred": new_pred, "margin": new_margin}
+                    break
+                if target == "margin_drop" and target_value is not None and new_margin <= base_margin - float(target_value):
+                    success, new_out = True, {"pred": new_pred, "margin": new_margin}
+                    break
+            else:
+                new_pred = float(logit2[0])
+                if target == "reg_delta" and target_value is not None:
+                    if (new_pred - base_pred) <= float(target_value):
+                        success, new_out = True, {"pred": new_pred}
+                        break
+
+        suggestions.append({
+            "rule": (b+1, r+1),
+            "facts": [f"F{fid+1}" for fid in used_sorted],
+            "deltas": feat_deltas,
+            "verified": success,
+            "new_out": new_out
+        })
+    return suggestions

nous/explain/facts_desc.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+from typing import Dict, Sequence
+from ..model import NousNet
+
+def render_fact_descriptions(model: NousNet, feature_names: Sequence[str], top_k_feats: int = 4, eps: float = 0.03) -> Dict[int, str]:
+    """
+    Create human-readable descriptions of base β-facts using (L-R) weights.
+    """
+    L, R, th, k, nu = model.fact.get_rule_parameters()
+    desc = {}
+    for fid in range(L.shape[0]):
+        net = L[fid] - R[fid]
+        pos = [(feature_names[i], net[i]) for i in range(len(net)) if net[i] > eps]
+        neg = [(feature_names[i], -net[i]) for i in range(len(net)) if net[i] < -eps]
+        pos = sorted(pos, key=lambda t: -abs(t[1]))[:top_k_feats]
+        neg = sorted(neg, key=lambda t: -abs(t[1]))[:top_k_feats]
+        pos_str = " + ".join([f"{w:.2f}·{n}" for n, w in pos]) if pos else "0"
+        neg_str = " + ".join([f"{w:.2f}·{n}" for n, w in neg]) if neg else "0"
+        base = f"β( [L−R](x̃) = ({pos_str}) − ({neg_str}) > {th[fid]:.2f}; k={k[fid]:.2f}, ν={nu[fid]:.2f} )"
+        if model.calibrators is not None:
+            base += "  where x̃ are calibrated features"
+        desc[fid] = base
+    return desc

nous/explain/fidelity.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+import numpy as np
+import torch
+from typing import Optional, Sequence, Dict, Any
+from ..model import NousNet
+from .mse import minimal_sufficient_explanation
+
+def explanation_fidelity_metrics(
+    model: NousNet, x_sample, feature_names: Sequence[str], class_names: Optional[Sequence[str]] = None,
+    margin_tolerance: float = 0.0, prob_tolerance: float = 0.0, pred_tolerance_reg: float = 0.02,
+    device=None
+) -> Dict[str, float]:
+    """
+    Sufficiency and comprehensiveness metrics using MSE masks.
+    """
+    device = device or next(model.parameters()).device
+    task = model.config['task_type']
+
+    base_probas, base_logits, base_internals = model.forward_explain(x_sample, device=device)
+    if task == "classification":
+        pred_idx = int(np.argmax(base_probas))
+        runner_up = int(np.argsort(base_logits)[-2]) if base_logits.size > 1 else pred_idx
+        base_margin = float(base_logits[pred_idx] - base_logits[runner_up])
+    else:
+        base_pred = float(base_logits[0])
+
+    mse = minimal_sufficient_explanation(
+        model, x_sample, feature_names, class_names=class_names,
+        margin_tolerance=margin_tolerance, prob_tolerance=prob_tolerance,
+        pred_tolerance_reg=pred_tolerance_reg, freeze_non_active=True, device=device
+    )
+    kept_masks = mse["kept_masks"]
+
+    prob_s, logit_s, _ = model.forward_explain(x_sample, restrict_masks=kept_masks, device=device)
+    inv_masks = [(torch.ones_like(m) - m) for m in kept_masks]
+    prob_c, logit_c, _ = model.forward_explain(x_sample, restrict_masks=inv_masks, device=device)
+
+    if task == "classification":
+        runner_up = int(np.argsort(base_logits)[-2]) if base_logits.size > 1 else pred_idx
+        margin_s = float(logit_s[pred_idx] - logit_s[runner_up])
+        margin_c = float(logit_c[pred_idx] - logit_c[runner_up])
+        return {
+            "base_margin": base_margin,
+            "sufficiency_margin": margin_s,
+            "comprehensiveness_margin": margin_c,
+            "kept_size": float(sum(int(m.sum().item()) for m in kept_masks))
+        }
+    else:
+        pred_s = float(logit_s[0])
+        pred_c = float(logit_c[0])
+        return {
+            "base_pred": base_pred,
+            "sufficiency_pred": pred_s,
+            "comprehensiveness_pred": pred_c,
+            "kept_size": float(sum(int(m.sum().item()) for m in kept_masks))
+        }

nous/explain/generate.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+import numpy as np
+from typing import Optional, Sequence
+from ..model import NousNet
+from .loo import rule_impact_df
+
+def generate_enhanced_explanation(
+    model: NousNet, x_sample, y_true, feature_names: Sequence[str], class_names: Optional[Sequence[str]] = None, y_scaler=None,
+    loo_mode: str = 'replacement', top_m_rules: Optional[int] = None, use_pre_norm: bool = False,
+    use_pruning: bool = False, pruning_threshold: float = 0.0, vs_class_idx: Optional[int] = None
+) -> str:
+    """
+    Human-readable explanation text with top rule impacts for a single sample.
+    """
+    task = model.config['task_type']
+    base_probas, base_logits, _ = model.forward_explain(
+        x_sample, apply_pruning=use_pruning, pruning_threshold=pruning_threshold
+    )
+
+    if y_scaler is not None:
+        y_true_unscaled = y_scaler.inverse_transform(np.array(y_true).reshape(-1, 1)).item()
+        base_pred_unscaled = y_scaler.inverse_transform(base_logits.reshape(-1, 1)).item()
+    else:
+        y_true_unscaled = y_true
+        base_pred_unscaled = base_logits[0] if task == 'regression' else None
+
+    if task == "classification":
+        pred_idx = int(np.argmax(base_probas))
+        pred_name = class_names[pred_idx] if class_names else f"Class {pred_idx}"
+        conf = float(base_probas[pred_idx])
+        true_name = class_names[y_true] if class_names is not None else str(y_true)
+    else:
+        pred_name = f"Value: {base_pred_unscaled:.3f}"
+        true_name = f"{y_true_unscaled:.3f}"
+
+    lines = []
+    model_tag = model.config['rule_selection_method'].upper()
+    lines.append(f"MODEL: {model_tag} rules | TASK: {task.upper()}")
+    lines.append(f"SAMPLE PREDICTION: {pred_name}")
+    if task == "classification":
+        lines.append(f"  - Confidence: {conf:.3f}")
+        lines.append(f"  - Ground Truth: {true_name}")
+    else:
+        lines.append(f"  - Ground Truth: {true_name}")
+    if use_pruning:
+        lines.append(f"  - Pruning: |act| >= {pruning_threshold:.4f} (forward uses pruned activations)")
+    lines.append("-"*60)
+
+    imp = rule_impact_df(
+        model, x_sample, feature_names, class_names=class_names, vs_class=vs_class_idx,
+        loo_mode=loo_mode, top_m_rules=top_m_rules, use_pre_norm=use_pre_norm,
+        use_pruning=use_pruning, pruning_threshold=pruning_threshold
+    )
+    if imp.empty:
+        lines.append("No active rules above threshold.")
+        return "\n".join(lines)
+
+    if vs_class_idx is not None and task == "classification":
+        lines.append(f"(Contrastive) Why '{pred_name}' vs '{class_names[vs_class_idx]}'?")
+    lines.append("CAUSAL RULE IMPACT (Top 5):")
+
+    for _, row in imp.head(5).iterrows():
+        b, r = row['block'], row['rule']
+        aggs, facts = row['aggregators'], row['facts']
+        badge = ""
+        if 'supports_pred' in row:
+            badge = " [+]" if row['supports_pred'] else " [-]"
+        if 'critical_flip' in row and row['critical_flip']:
+            badge += " [CRITICAL]"
+
+        if task == "classification":
+            margin_col = [c for c in imp.columns if c.startswith("Δmargin(")][0]
+            s = f"Δmargin={row[margin_col]:+.3f}{badge}"
+        else:
+            delta_pred = row['Δprediction']
+            if y_scaler is not None:
+                delta_pred_unscaled = delta_pred * y_scaler.scale_[0]
+                s = f"Δprediction={delta_pred_unscaled:+.3f}"
+            else:
+                s = f"Δprediction={delta_pred:+.3f}"
+        lines.append(f"  • B{b}/R{r}: {s} | {aggs}\n    {facts}")
+
+    if len(imp) > 5:
+        lines.append(f"  ... and {len(imp) - 5} more active rules.")
+
+    return "\n".join(lines)

nous/explain/global_book.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+import numpy as np
+import pandas as pd
+from typing import Optional, Sequence
+from ..model import NousNet
+from .loo import rule_impact_df
+
+def global_rulebook(
+    model: NousNet, X, feature_names: Sequence[str], class_names: Optional[Sequence[str]] = None,
+    pruning_threshold: Optional[float] = None, use_pruning: bool = False, allow_replacement: bool = True, freeze_non_active: bool = False,
+    max_samples: int = 1000, device=None
+) -> pd.DataFrame:
+    """
+    Global rulebook aggregation across samples via honest LOO impacts.
+    """
+    from tqdm.auto import tqdm  # optional dep in extras
+
+    device = device or next(model.parameters()).device
+    n = min(len(X), max_samples)
+    totals = {}
+
+    loo_mode = 'replacement'
+    if not allow_replacement and freeze_non_active:
+        loo_mode = 'frozen'
+
+    for i in tqdm(range(n), desc="Analyzing samples"):
+        df = rule_impact_df(
+            model, X[i], feature_names, class_names=class_names,
+            loo_mode=loo_mode, use_pruning=use_pruning, pruning_threshold=(pruning_threshold or 0.0), device=device
+        )
+        if df.empty:
+            continue
+        for _, row in df.iterrows():
+            key = (int(row["block"]), int(row["rule"]), row["aggregators"])
+            d = totals.setdefault(key, {"count": 0, "sum_abs_impact": 0.0, "critical": 0})
+            d["count"] += 1
+            if "critical_flip" in row and row["critical_flip"]:
+                d["critical"] += 1
+            metric_col = [c for c in row.index if c.startswith("Δmargin(")]
+            val = abs(float(row[metric_col[0]])) if metric_col else abs(float(row.get("Δprediction", 0.0)))
+            d["sum_abs_impact"] += val
+
+    rows = []
+    for (b, r, agg), v in totals.items():
+        count = v["count"]
+        rows.append({
+            "block": b, "rule": r, "aggregators": agg,
+            "activation_freq": count / n,
+            "mean_abs_impact": v["sum_abs_impact"] / count if count else 0.0,
+            "critical_rate": v["critical"] / count if count else 0.0
+        })
+    return pd.DataFrame(rows).sort_values("mean_abs_impact", ascending=False).reset_index(drop=True)