mbe-eval 0.1.0__py3-none-any.whl

mbe_eval/__init__.py

@@ -0,0 +1,4 @@
+from .core import MBEEvaluator, MBEReport
+from .sample_eval import simulate_mbe_evaluation
+
+__all__ = ["MBEEvaluator", "MBEReport", "simulate_mbe_evaluation"]

mbe_eval/core.py

@@ -0,0 +1,133 @@
+import os
+import pandas as pd
+import numpy as np
+import pingouin as pg
+from scipy.stats import pearsonr, spearmanr
+from dataclasses import dataclass
+import matplotlib.pyplot as plt
+import seaborn as sns
+from rich.console import Console
+from rich.table import Table
+from rich.panel import Panel
+
+console = Console()
+
+@dataclass
+class MBEReport:
+    metric_name: str
+    baseline_name: str
+    absolute_r: float
+    absolute_p: float
+    partial_r: float
+    partial_p: float
+    is_loss_proxy: bool
+
+class MBEEvaluator:
+    """
+    The Marginal Baseline Eval (MBE) framework.
+    Evaluates whether a proposed representation metric offers independent
+    structural insight beyond a trivial baseline (e.g. early validation loss).
+    """
+    
+    def __init__(self, metric_name: str = "Proposed Metric", baseline_name: str = "Validation Loss"):
+        self.metric_name = metric_name
+        self.baseline_name = baseline_name
+        
+    def evaluate(self, metric_vals: np.ndarray, baseline_vals: np.ndarray, target_vals: np.ndarray, 
+                 alpha: float = 0.05, output_dir: str = "mbe_reports") -> MBEReport:
+        """
+        Runs Stage 1 (Absolute Correlation) and Stage 4 (Partial Correlation).
+        """
+        console.print(Panel(f"[bold cyan]Marginal Baseline Eval (MBE) - {self.metric_name}[/bold cyan]"))
+        
+        # Stage 1: Absolute Correlation (Does it predict the target at all?)
+        # We use Spearman rank correlation as the primary measure for structural metrics
+        abs_r, abs_p = spearmanr(metric_vals, target_vals)
+        
+        # Stage 4: Partial Correlation (Does it beat the baseline?)
+        # Partial correlation requires linear controls, so we use Pearson on the ranks if desired,
+        # but pingouin partial_corr handles linear partials well. We'll use pingouin.
+        df = pd.DataFrame({
+            'Target': target_vals,
+            'Metric': metric_vals,
+            'Baseline': baseline_vals
+        })
+        
+        pcorr = pg.partial_corr(data=df, x='Metric', y='Target', covar='Baseline', method='spearman')
+        part_r = pcorr['r'].values[0]
+        part_p = pcorr['p_val'].values[0]
+        
+        is_proxy = part_p > alpha
+        
+        report = MBEReport(
+            metric_name=self.metric_name,
+            baseline_name=self.baseline_name,
+            absolute_r=abs_r, absolute_p=abs_p,
+            partial_r=part_r, partial_p=part_p,
+            is_loss_proxy=is_proxy
+        )
+        
+        self._print_rich_report(report)
+        self._generate_plots(df, report, output_dir)
+        
+        return report
+
+    def _print_rich_report(self, r: MBEReport):
+        table = Table(title="MBE Evaluation Results", show_header=True, header_style="bold magenta")
+        table.add_column("Stage", style="dim", width=20)
+        table.add_column("Test", width=40)
+        table.add_column("Correlation", justify="right")
+        table.add_column("p-value", justify="right")
+        table.add_column("Verdict", justify="center")
+        
+        # Absolute
+        abs_verdict = "[bold green]PASS[/bold green]" if r.absolute_p < 0.05 else "[bold red]FAIL[/bold red]"
+        abs_p_str = f"[green]{r.absolute_p:.2e}[/green]" if r.absolute_p < 0.05 else f"[red]{r.absolute_p:.2e}[/red]"
+        table.add_row("1: Absolute", f"Correlation with Final Target", f"{r.absolute_r:.3f}", abs_p_str, abs_verdict)
+        
+        # Partial
+        part_verdict = "[bold red]FAIL[/bold red]" if r.is_loss_proxy else "[bold green]PASS[/bold green]"
+        part_p_str = f"[red]{r.partial_p:.2e}[/red]" if r.is_loss_proxy else f"[green]{r.partial_p:.2e}[/green]"
+        table.add_row("4: MBE Control", f"Controlling for {r.baseline_name}", f"{r.partial_r:.3f}", part_p_str, part_verdict)
+        
+        console.print(table)
+        
+        if r.is_loss_proxy:
+            console.print(f"[bold red]DIAGNOSIS: {r.metric_name} is a disguised Loss Proxy.[/bold red]")
+            console.print(f"It provides NO independent predictive signal beyond {r.baseline_name}.\n")
+        else:
+            console.print(f"[bold green]DIAGNOSIS: {r.metric_name} provides independent structural insight![/bold green]\n")
+
+    def _generate_plots(self, df: pd.DataFrame, r: MBEReport, output_dir: str):
+        os.makedirs(output_dir, exist_ok=True)
+        sns.set_theme(style="whitegrid")
+        
+        fig, axes = plt.subplots(1, 2, figsize=(14, 6))
+        fig.suptitle(f"MBE Report: {r.metric_name}", fontsize=16, fontweight='bold')
+        
+        # Plot 1: Metric vs Target (Absolute)
+        sns.regplot(ax=axes[0], data=df, x='Metric', y='Target', scatter_kws={'alpha':0.6, 's':80}, color='indigo')
+        axes[0].set_title(f"Stage 1: Absolute Correlation\nρ = {r.absolute_r:.3f} (p = {r.absolute_p:.2e})", fontsize=14)
+        axes[0].set_xlabel(r.metric_name, fontsize=12)
+        axes[0].set_ylabel("Final Target (e.g., Accuracy)", fontsize=12)
+        
+        # Plot 2: Bar chart of correlation collapse
+        labels = ['Absolute\n(Uncontrolled)', f'Marginal\n(Controlling {r.baseline_name})']
+        vals = [abs(r.absolute_r), abs(r.partial_r)]
+        colors = ['#2ecc71' if r.absolute_p < 0.05 else '#e74c3c', 
+                  '#2ecc71' if not r.is_loss_proxy else '#e74c3c']
+        
+        axes[1].bar(labels, vals, color=colors, alpha=0.8, edgecolor='black', linewidth=1.5)
+        axes[1].set_ylim(0, 1.0)
+        axes[1].set_ylabel("Absolute Magnitude of Spearman ρ", fontsize=12)
+        axes[1].set_title("Stage 4: Predictive Power Collapse", fontsize=14)
+        
+        for i, v in enumerate(vals):
+            axes[1].text(i, v + 0.02, f"|ρ|={v:.3f}", ha='center', fontsize=12, fontweight='bold')
+
+        plt.tight_layout()
+        save_path = os.path.join(output_dir, f"mbe_report_{r.metric_name.replace(' ', '_')}.png")
+        plt.savefig(save_path, dpi=300, bbox_inches='tight')
+        plt.close()
+        
+        console.print(f"[dim]Generated graphical report at: {save_path}[/dim]")

mbe_eval/sample_eval.py

@@ -0,0 +1,70 @@
+import numpy as np
+from scipy.stats import pearsonr
+import pingouin as pg
+import pandas as pd
+
+def simulate_mbe_evaluation():
+    """
+    Simulates the Marginal Baseline Eval (MBE) on a dummy representation metric.
+    MBE tests whether a proposed metric offers independent predictive signal 
+    beyond a trivial baseline (early validation loss).
+    """
+    print("==================================================")
+    print("Marginal Baseline Eval (MBE) - Sample Test Run")
+    print("==================================================\n")
+    
+    # 1. Generate heterogeneous dummy data (simulating 30 training runs)
+    np.random.seed(42)
+    n_runs = 30
+    
+    # Underlying true model capability (unobserved)
+    true_capability = np.random.randn(n_runs)
+    
+    # Early Validation Loss (our trivial baseline) perfectly tracks capability + some noise
+    early_val_loss = -true_capability + np.random.randn(n_runs) * 0.2
+    
+    # Final Epoch 200 Accuracy (our target to predict) perfectly tracks capability + some noise
+    final_test_acc = true_capability + np.random.randn(n_runs) * 0.1
+    
+    # Our proposed dummy metric: Gradient L2 Norm
+    # IT IS A LOSS PROXY! It mathematically correlates heavily with early val loss.
+    proposed_metric = early_val_loss + np.random.randn(n_runs) * 0.3
+    
+    # 2. Stage 1: Absolute Correlation (The False Assurance)
+    # Does the metric predict final accuracy?
+    r_metric, p_metric = pearsonr(proposed_metric, final_test_acc)
+    print(f"[Stage 1] Absolute Correlation Check:")
+    print(f"  Correlation of Proposed Metric with Final Accuracy: r = {r_metric:.3f} (p = {p_metric:.3e})")
+    
+    if p_metric < 0.05:
+        print("  -> RESULT: PASS. Metric correlates significantly with generalization.\n")
+    
+    # 3. Stage 2: The MBE Partial-Correlation Baseline Control
+    # Does the metric offer MARGINAL signal beyond the trivial validation loss baseline?
+    print("[Stage 2] The MBE Baseline Control (Partial Correlation):")
+    
+    df = pd.DataFrame({
+        'Final_Acc': final_test_acc,
+        'Proposed_Metric': proposed_metric,
+        'Baseline_Loss': early_val_loss
+    })
+    
+    # Calculate partial correlation: Metric vs Final Acc, controlling for Baseline Loss
+    pcorr_metric = pg.partial_corr(data=df, x='Proposed_Metric', y='Final_Acc', covar='Baseline_Loss')
+    r_partial = pcorr_metric['r'].values[0]
+    p_partial = pcorr_metric['p-val'].values[0]
+    
+    print(f"  Marginal Correlation (Controlling for Early Val Loss): r = {r_partial:.3f} (p = {p_partial:.3f})")
+    
+    if p_partial > 0.05:
+        print("  -> RESULT: FAIL. The metric offers NO independent predictive signal.")
+        print("  -> DIAGNOSIS: The proposed metric is a disguised Loss Proxy.\n")
+    else:
+        print("  -> RESULT: PASS. The metric offers independent structural insight.\n")
+        
+    print("==================================================")
+    print("MBE Evaluation Complete.")
+    print("==================================================")
+
+if __name__ == "__main__":
+    simulate_mbe_evaluation()

mbe_eval/utils.py

@@ -0,0 +1,50 @@
+import torch
+import math
+import numpy as np
+
+def compute_fim_norm(model, loss_fn, inputs, targets):
+    """
+    Computes Gradient Effective Rank (FIM_norm) via the dual Gram matrix.
+    This exactly implements the mathematical formulation from the MBE paper.
+    """
+    N = inputs.shape[0]
+    
+    # We need per-sample gradients. Since standard PyTorch accumulates,
+    # we compute it one by one for exactness. (In practice, functorch/vmap is faster, 
+    # but a simple loop is highly readable for a demonstration.)
+    
+    grads = []
+    model.eval() # ensure no batchnorm tracking during this
+    
+    for i in range(N):
+        x = inputs[i:i+1]
+        y = targets[i:i+1]
+        
+        loss = loss_fn(model(x), y)
+        model.zero_grad()
+        loss.backward()
+        
+        # Flatten all parameters' gradients into a single vector
+        g_vec = torch.cat([p.grad.flatten() for p in model.parameters() if p.grad is not None])
+        grads.append(g_vec.detach())
+        
+    G = torch.stack(grads) # shape: (N, P)
+    
+    # The Dual Gram Matrix
+    S_dual = (1.0 / N) * torch.matmul(G, G.T) # shape: (N, N)
+    
+    # Eigendecomposition
+    eigenvalues = torch.linalg.eigvalsh(S_dual)
+    eigenvalues = eigenvalues[eigenvalues > 1e-12] # numerical noise floor
+    
+    if len(eigenvalues) == 0:
+        return 1.0 # Max normalized rank
+        
+    # Shannon entropy of normalized spectrum
+    p = eigenvalues / eigenvalues.sum()
+    H = -(p * torch.log(p)).sum().item()
+    
+    erank = math.exp(H)
+    fim_norm = erank / N
+    
+    return fim_norm

mbe_eval-0.1.0.dist-info/METADATA

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: mbe-eval
+Version: 0.1.0
+Summary: Marginal Baseline Eval (MBE): A framework for rigorously auditing representation metrics in deep neural networks.
+Home-page: https://github.com/AparajeetS/metric-audit-paper-code
+Author: Aparajeet Shadangi
+Author-email: author@example.com
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: scipy
+Requires-Dist: pandas
+Requires-Dist: pingouin
+Requires-Dist: torch
+Requires-Dist: torchvision
+Requires-Dist: matplotlib
+Requires-Dist: seaborn
+Requires-Dist: scikit-learn
+Requires-Dist: rich
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# The Marginal Baseline Eval (MBE)
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Welcome to the **Marginal Baseline Eval (MBE)** repository! 
+
+This repository provides the formal implementation of the MBE protocol — a strict, 4-stage validation methodology designed to rigorously audit representation metrics in deep neural networks. 
+
+It was originally built during a massive case study that mathematically falsified the Gradient Effective Rank (FIM_norm) metric.
+
+## Why Do We Need MBE?
+
+The AI safety and interpretability communities frequently propose internal structural metrics (e.g., representation geometry, effective rank, gradient coherence) to predict generalization or track model health. 
+
+However, many of these metrics are secretly **Loss Proxies**. Because early validation loss trivially predicts final test accuracy, any metric that mathematically correlates with the *magnitude* of the loss will automatically correlate with generalization. Such a metric provides **zero independent structural insight**.
+
+The MBE protocol catches these false positive metrics using a rigorous **partial-correlation baseline control**.
+
+## Installation
+
+You can install the framework directly from PyPI:
+
+```bash
+pip install mbe-eval
+```
+
+Or, if you want to run the PyTorch demos, clone the repository:
+
+```bash
+git clone https://github.com/AparajeetS/metric-audit-paper-code.git
+cd metric-audit-paper-code
+pip install -r requirements.txt
+```
+
+## The MBE API
+
+MBE is a fully importable Python framework powered by `pandas` and `pingouin`. You can integrate it directly into your own model evaluation pipelines.
+
+```python
+from mbe_eval import MBEEvaluator
+
+# Pass your experimental arrays (numpy arrays)
+evaluator = MBEEvaluator(metric_name="My Cool Metric", baseline_name="Epoch 20 Val Loss")
+report = evaluator.evaluate(metric_vals, baseline_vals, target_vals)
+```
+This automatically prints a beautiful `rich` diagnostics table to the console and generates a high-resolution `seaborn` graphical report in the `mbe_reports/` directory.
+
+## Real PyTorch Demos
+
+We provide two end-to-end PyTorch scripts in the `examples/` directory that actually train neural networks and run the evaluation live.
+
+**1. The Acid Test (Stage 1)**
+Shows how a metric can successfully track capacity and noise, giving false assurance.
+```bash
+python examples/01_run_acid_test.py
+```
+
+**2. The Heterogeneous Grid (Stage 4)**
+The killer demo. Trains 20 models with randomized hyperparameters, computes the Gradient Effective Rank, and runs the final MBE Partial Correlation control to prove the metric is a disguised loss proxy.
+```bash
+python examples/02_run_heterogeneous_grid.py
+```
+
+## Repository Structure
+
+```
+metric-audit-paper-code/
+├── mbe_eval/               # The core MBE evaluation API
+│   ├── __init__.py
+│   ├── core.py             # MBEEvaluator class
+│   ├── utils.py            # PyTorch FIM_norm extraction
+│   └── sample_eval.py      # Basic synthetic simulation
+├── examples/               # Real end-to-end PyTorch demos
+│   ├── 01_run_acid_test.py
+│   └── 02_run_heterogeneous_grid.py
+├── experiments/            # All 12 original paper experiment scripts
+├── metric_audit/           # Core FIM_norm computation library
+├── docs/
+│   └── RESULTS.md          # Raw numerical results for the paper
+├── PAPER.md                # Full technical writeup
+├── requirements.txt
+├── LICENSE
+└── README.md
+```
+
+## Citation
+
+If you use the Marginal Baseline Eval in your own representation evaluation, please cite the accompanying manuscript:
+
+```
+Shadangi, A. (2026). Does It Beat the Baseline? A Comprehensive Negative Result 
+on Gradient Effective Rank as a Generalization Predictor. arXiv preprint.
+```

mbe_eval-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+mbe_eval/__init__.py,sha256=78eMbBLcXaHAmAkrHzQgNNIZsSiS7LBUyz-wjIbKqMA,159
+mbe_eval/core.py,sha256=2455WF5dTCipo8UYr7nsEDNcJWl4oujs3rQflI-Z69c,6001
+mbe_eval/sample_eval.py,sha256=8-H-_zd5rEEU05p837Zyj1pZeufxXrgZK_O_T7M4QSM,3092
+mbe_eval/utils.py,sha256=L66LsmVwjFTsGu0oaH_7xXUVoEDac_wEhI_gNHiwXfc,1572
+mbe_eval-0.1.0.dist-info/licenses/LICENSE,sha256=w9-S3P-lYZOpilpXgq_hhYezIacu2FZ9RsFIp_18fMY,1075
+metric_audit/__init__.py,sha256=G1_XnKKJZWrZMuGXI1jUUfgZXJkf4mNvzgaRKP1uMUk,30
+metric_audit/sci_tracker.py,sha256=9c-Lgaf660YrNQJVEWF3Hbjl6EaG0T1R2u_3itQ2Tn4,4483
+mbe_eval-0.1.0.dist-info/METADATA,sha256=Kdp9qKRmcya-Os_qy47XdRi8NinMgpVqCw7C9t-BuHk,5058
+mbe_eval-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+mbe_eval-0.1.0.dist-info/top_level.txt,sha256=7RGD-pg-boBEVp3aL7qM9ALR2Fa9An0TMy2lGwrwzfg,22
+mbe_eval-0.1.0.dist-info/RECORD,,

mbe_eval-0.1.0.dist-info/WHEEL

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

mbe_eval-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aparajeet Shadangi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mbe_eval-0.1.0.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+mbe_eval
+metric_audit

metric_audit/__init__.py

@@ -0,0 +1 @@
+# Metric Audit - Core Library

metric_audit/sci_tracker.py

@@ -0,0 +1,134 @@
+"""
+SCI Tracker — Structural Constraint Index (CEI v2)
+
+Measures erank(W_l) / min(n_out, n_in) for each weight matrix.
+No forward pass required. No BatchNorm contamination.
+"""
+
+import math
+import numpy as np
+
+
+# ------------------------------------------------------------------ #
+#  Core math                                                           #
+# ------------------------------------------------------------------ #
+
+def effective_rank(M: np.ndarray) -> float:
+    """
+    erank(M) = exp( H(p) )  where H is Shannon entropy of
+    normalized singular values p_k = σ_k / Σ σ_j.
+    Range: [1, min(n_rows, n_cols)].
+    """
+    sv = np.linalg.svd(M.astype(np.float64), compute_uv=False)
+    sv = sv[sv > 1e-10]
+    if len(sv) == 0:
+        return 1.0
+    p  = sv / sv.sum()
+    H  = -(p * np.log(p + 1e-12)).sum()
+    return float(math.exp(H))
+
+
+def sci_from_weight(W: np.ndarray) -> float:
+    """
+    Structural Constraint Index for a single weight matrix W.
+    sci ∈ (1/r, 1] where r = min(n_out, n_in).
+    Lower = more constrained = more generalizable (hypothesis).
+    """
+    r = min(W.shape[0], W.shape[1])
+    return effective_rank(W) / r
+
+
+def sci_spectrum(W: np.ndarray) -> dict:
+    """
+    Full spectral breakdown for diagnostics.
+    Returns: sci, erank, rank_max, singular values, spectral entropy.
+    """
+    sv   = np.linalg.svd(W.astype(np.float64), compute_uv=False)
+    r    = min(W.shape[0], W.shape[1])
+    sv_p = sv[sv > 1e-10]
+    if len(sv_p) == 0:
+        return {"sci": 1.0, "erank": 1.0, "rank_max": r,
+                "spectral_entropy": 0.0, "sv_max": 0.0, "sv_min": 0.0,
+                "stable_rank": 0.0, "nuclear_norm": 0.0, "spectral_norm": 0.0}
+    p   = sv_p / sv_p.sum()
+    H   = -(p * np.log(p + 1e-12)).sum()
+    er  = math.exp(H)
+    return {
+        "sci":             er / r,
+        "erank":           er,
+        "rank_max":        r,
+        "spectral_entropy": float(H),
+        "sv_max":          float(sv_p[0]),
+        "sv_min":          float(sv_p[-1]),
+        # stable rank = ||W||_F^2 / ||W||_2^2 (Rudelson & Vershynin)
+        "stable_rank":     float((sv_p**2).sum() / (sv_p[0]**2 + 1e-12)),
+        "nuclear_norm":    float(sv_p.sum()),
+        "spectral_norm":   float(sv_p[0]),
+    }
+
+
+# ------------------------------------------------------------------ #
+#  NumPy MLP tracker (no PyTorch needed)                              #
+# ------------------------------------------------------------------ #
+
+class NumpySCITracker:
+    """
+    Tracks SCI across all weight matrices of a numpy MLP.
+
+    Usage:
+        tracker = NumpySCITracker(model)
+        sci_vals, net_sci = tracker.compute()
+    """
+
+    def __init__(self, model):
+        self.model = model   # expects model.W = list of np.ndarray
+
+    def compute(self) -> tuple[list[float], float]:
+        """Returns (per_layer_sci, network_mean_sci)."""
+        vals = [sci_from_weight(W) for W in self.model.W]
+        return vals, float(np.mean(vals))
+
+    def compute_full(self) -> list[dict]:
+        """Returns full spectral breakdown per layer."""
+        return [sci_spectrum(W) for W in self.model.W]
+
+
+# ------------------------------------------------------------------ #
+#  Optional PyTorch wrapper                                           #
+# ------------------------------------------------------------------ #
+
+def pytorch_sci(model, layer_types=None) -> dict:
+    """
+    Compute SCI for all weight matrices in a PyTorch model.
+
+    Args:
+        model: nn.Module
+        layer_types: tuple of types to include (default: Linear + Conv2d)
+
+    Returns:
+        dict mapping layer_name -> sci_spectrum dict, plus "network_sci" mean.
+    """
+    try:
+        import torch
+        import torch.nn as nn
+    except ImportError:
+        raise ImportError("PyTorch not available; use NumpySCITracker for numpy models.")
+
+    if layer_types is None:
+        layer_types = (nn.Linear, nn.Conv2d)
+
+    results = {}
+    sci_list = []
+
+    for name, module in model.named_modules():
+        if isinstance(module, layer_types):
+            W = module.weight.detach().cpu().numpy()
+            if W.ndim > 2:
+                # Conv2d: (C_out, C_in, kH, kW) → reshape to (C_out, C_in*kH*kW)
+                W = W.reshape(W.shape[0], -1)
+            spec = sci_spectrum(W)
+            results[name] = spec
+            sci_list.append(spec["sci"])
+
+    results["network_sci"] = float(np.mean(sci_list)) if sci_list else float("nan")
+    return results