mod-trace 0.2.0__tar.gz → 0.3.1__tar.gz

{mod_trace-0.2.0 → mod_trace-0.3.1}/.gitignore

@@ -8,3 +8,5 @@ examples/*.cbm
 examples/*.onnx
 # but keep the synthetic ONNX demo models (committed as examples)
 !examples/onnx/
+/mt-demo/
+/.claude/

{mod_trace-0.2.0 → mod_trace-0.3.1}/Cargo.lock

@@ -16,7 +16,7 @@ checksum = "6b947ae49db0d222b1dbc6b113ce7248a3fc3a6ca21b696717bfc000ba4484d8"
 
 [[package]]
 name = "mod-trace"
-version = "0.2.0"
+version = "0.3.1"
 dependencies = [
  "serde",
  "serde_json",

{mod_trace-0.2.0 → mod_trace-0.3.1}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "mod-trace"
-version = "0.2.0"
+version = "0.3.1"
 edition = "2024"
 description = "Rust CLI for inspecting ML model artifacts without loading the framework"
 license = "MIT"

{mod_trace-0.2.0 → mod_trace-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mod-trace
-Version: 0.2.0
+Version: 0.3.1
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
@@ -27,18 +27,14 @@ What is inside this model file?
 
 It can inspect real artifacts such as CatBoost `.cbm` files, LightGBM `.txt`/`.lgb` text models, and ONNX `.onnx` graphs, then report structure, size, parameters, operator mix, rough inference cost, and changes between versions. CatBoost, LightGBM, and ONNX are all read natively — no Python, framework, or runtime needed (CatBoost `--deep` is the one optional exception).
 
-The secondary tensor lab keeps the original `EXPLAIN ANALYZE` idea for tiny neural-network plans:
-
-```sql
-EXPLAIN ANALYZE SELECT ...
-```
-
-becomes:
+The most useful command is `explain-diff`, which says in plain English what changed between two model versions:
 
 ```sh
-mod-trace trace examples/tiny_attention_plan.json
+mod-trace explain-diff old_model.onnx new_model.onnx
 ```
 
+(A secondary "tensor lab" for handcrafted JSON plans lives in [docs/tensor-lab.md](docs/tensor-lab.md).)
+
 ## Core Commands
 
 ```sh
@@ -73,7 +69,10 @@ mod-trace explain model.onnx
 mod-trace diff old_model.cbm new_model.cbm
 mod-trace diff --json old_model.cbm new_model.cbm
 mod-trace diff --deep old_model.cbm new_model.cbm
+mod-trace explain-diff old_model.onnx new_model.onnx
 mod-trace check --max-size-growth 20% --fail-on-feature-change old_model.cbm new_model.cbm
+mod-trace inspect model.lgb        # LightGBM (.lgb/.txt), read natively
+mod-trace diff old.lgb new.lgb
 ```
 
 ## Why This Exists
@@ -160,10 +159,54 @@ cargo run -- check path/to/old_model.cbm path/to/new_model.cbm \
 cargo run -- check path/to/old_model.onnx path/to/new_model.onnx \
   --max-size-growth 20% \
   --max-ops-growth 25% \
+  --max-parameter-growth 30% \
   --fail-on-new-op
 ```
 
-`check` prints a short PASS/FAIL report and exits nonzero when a rule fails.
+Check rules:
+
+| Rule | Applies to | Fails when |
+|------|------------|-----------|
+| `--max-size-growth <pct>` | all | file size grows more than `<pct>` |
+| `--max-parameter-growth <pct>` | ONNX | parameter count grows more than `<pct>` |
+| `--max-ops-growth <pct>` | ONNX | estimated op count grows more than `<pct>` |
+| `--fail-on-new-op` | ONNX | a new operator type appears |
+| `--fail-on-feature-change` | CatBoost, LightGBM | feature names change |
+| `--fail-on-training-config-change` | CatBoost, LightGBM | objective/learning rate/etc. change |
+
+`check` prints a short PASS/FAIL report and exits nonzero when a rule fails. Any number of rules can be combined; any one failing fails the whole check.
+
+## Explain Diff
+
+`explain-diff` is the plain-English version of `diff` — it reports what actually changed between two model versions, not just raw numbers:
+
+```sh
+mod-trace explain-diff old_model.onnx new_model.onnx
+```
+
+```text
+Model Change Explanation
+------------------------
+Type: ONNX
+Old: old_model.onnx
+New: new_model.onnx
+
+Architecture:
+  Attention layers:  12 -> 24
+  Hidden size:       768 -> 1024
+  Parameters:        110.0M -> 220.0M (+100%)
+  Nodes:             420 -> 820 (+95%)
+
+Estimated inference cost (static op proxy): +94%
+
+New operators introduced:
+  LayerNormalization
+
+Summary:
+  Grew from ~12 to ~24 attention layers; parameters +100%, estimated cost +94%.
+```
+
+Works for ONNX, CatBoost, and LightGBM (tree models report trees / leaves / learned-state instead of attention layers).
 
 ## CatBoost
 
@@ -457,61 +500,38 @@ cargo run -- inspect models/tiny-distilbert-base-cased/model_fixed.onnx
 
 Fixed shapes such as `[1, 8]` produce better numeric estimates than symbolic shapes such as `[batch, sequence]`.
 
-## Tensor Lab
+### Exporting any PyTorch model to ONNX
 
-The original tensor-analysis MVP still exists as a lab for small handcrafted plans:
+mod-trace does not read native PyTorch `.pt`/`.pth` files (those are Python pickles / TorchScript archives). The supported path is to export to ONNX, which is the usual serving format anyway. For a plain `nn.Module` the export is a single call:
 
-```sh
-cargo run -- trace examples/tiny_attention_plan.json
-cargo run -- compare examples/tiny_attention_plan.json
-cargo run -- why examples/tiny_attention_plan.json
-cargo run -- validate examples/broken_shape.json
+```python
+import torch
+
+model.eval()
+dummy = torch.randn(1, n_features)          # one example input with the right shape
+torch.onnx.export(
+    model,
+    dummy,
+    "model.onnx",
+    input_names=["input"],
+    output_names=["output"],
+    opset_version=18,
+    dynamo=True,                            # optional; the modern exporter
+)
 ```
 
-Example plan:
-
-```json
-{
-  "layers": [
-    {
-      "type": "self_attention",
-      "tokens": 3,
-      "head_dim": 4,
-      "value_dim": 4
-    },
-    {
-      "type": "linear",
-      "in": 4,
-      "out": 2
-    },
-    {
-      "type": "softmax"
-    }
-  ]
-}
+```sh
+mod-trace inspect model.onnx
+mod-trace diff old_model.onnx new_model.onnx
 ```
 
-`why` explains the attention cost:
+Use fixed input shapes (e.g. `torch.randn(1, n_features)`) rather than dynamic axes for better cost estimates. Once exported, ONNX is read natively — no PyTorch, ONNX Runtime, or other framework is needed to inspect it.
 
-```text
-Why is attention expensive?
----------------------------
-Attention layer: single_head_attention
-  432 ops
-
-Breakdown:
-  Q projection             96 ops
-  K projection             96 ops
-  V projection             96 ops
-  Q @ K^T                  72 ops
-  attention @ V            72 ops
-
-Explanation:
-  Every token must compare itself against every other token.
-  The score and value-mixing terms grow roughly with tokens^2.
-```
+## Tensor Lab
 
-This is useful for demos and for explaining transformer internals, but it is no longer the primary product surface.
+A secondary lab for explaining transformer internals on small handcrafted JSON
+plans (`trace`, `compare`, `why`, `validate`, `quiz`, `demo`). It is not the
+primary product surface. See [docs/tensor-lab.md](docs/tensor-lab.md).
 
 ## What It Does Not Do
 

{mod_trace-0.2.0 → mod_trace-0.3.1}/README.md

@@ -10,18 +10,14 @@ What is inside this model file?
 
 It can inspect real artifacts such as CatBoost `.cbm` files, LightGBM `.txt`/`.lgb` text models, and ONNX `.onnx` graphs, then report structure, size, parameters, operator mix, rough inference cost, and changes between versions. CatBoost, LightGBM, and ONNX are all read natively — no Python, framework, or runtime needed (CatBoost `--deep` is the one optional exception).
 
-The secondary tensor lab keeps the original `EXPLAIN ANALYZE` idea for tiny neural-network plans:
-
-```sql
-EXPLAIN ANALYZE SELECT ...
-```
-
-becomes:
+The most useful command is `explain-diff`, which says in plain English what changed between two model versions:
 
 ```sh
-mod-trace trace examples/tiny_attention_plan.json
+mod-trace explain-diff old_model.onnx new_model.onnx
 ```
 
+(A secondary "tensor lab" for handcrafted JSON plans lives in [docs/tensor-lab.md](docs/tensor-lab.md).)
+
 ## Core Commands
 
 ```sh
@@ -56,7 +52,10 @@ mod-trace explain model.onnx
 mod-trace diff old_model.cbm new_model.cbm
 mod-trace diff --json old_model.cbm new_model.cbm
 mod-trace diff --deep old_model.cbm new_model.cbm
+mod-trace explain-diff old_model.onnx new_model.onnx
 mod-trace check --max-size-growth 20% --fail-on-feature-change old_model.cbm new_model.cbm
+mod-trace inspect model.lgb        # LightGBM (.lgb/.txt), read natively
+mod-trace diff old.lgb new.lgb
 ```
 
 ## Why This Exists
@@ -143,10 +142,54 @@ cargo run -- check path/to/old_model.cbm path/to/new_model.cbm \
 cargo run -- check path/to/old_model.onnx path/to/new_model.onnx \
   --max-size-growth 20% \
   --max-ops-growth 25% \
+  --max-parameter-growth 30% \
   --fail-on-new-op
 ```
 
-`check` prints a short PASS/FAIL report and exits nonzero when a rule fails.
+Check rules:
+
+| Rule | Applies to | Fails when |
+|------|------------|-----------|
+| `--max-size-growth <pct>` | all | file size grows more than `<pct>` |
+| `--max-parameter-growth <pct>` | ONNX | parameter count grows more than `<pct>` |
+| `--max-ops-growth <pct>` | ONNX | estimated op count grows more than `<pct>` |
+| `--fail-on-new-op` | ONNX | a new operator type appears |
+| `--fail-on-feature-change` | CatBoost, LightGBM | feature names change |
+| `--fail-on-training-config-change` | CatBoost, LightGBM | objective/learning rate/etc. change |
+
+`check` prints a short PASS/FAIL report and exits nonzero when a rule fails. Any number of rules can be combined; any one failing fails the whole check.
+
+## Explain Diff
+
+`explain-diff` is the plain-English version of `diff` — it reports what actually changed between two model versions, not just raw numbers:
+
+```sh
+mod-trace explain-diff old_model.onnx new_model.onnx
+```
+
+```text
+Model Change Explanation
+------------------------
+Type: ONNX
+Old: old_model.onnx
+New: new_model.onnx
+
+Architecture:
+  Attention layers:  12 -> 24
+  Hidden size:       768 -> 1024
+  Parameters:        110.0M -> 220.0M (+100%)
+  Nodes:             420 -> 820 (+95%)
+
+Estimated inference cost (static op proxy): +94%
+
+New operators introduced:
+  LayerNormalization
+
+Summary:
+  Grew from ~12 to ~24 attention layers; parameters +100%, estimated cost +94%.
+```
+
+Works for ONNX, CatBoost, and LightGBM (tree models report trees / leaves / learned-state instead of attention layers).
 
 ## CatBoost
 
@@ -440,61 +483,38 @@ cargo run -- inspect models/tiny-distilbert-base-cased/model_fixed.onnx
 
 Fixed shapes such as `[1, 8]` produce better numeric estimates than symbolic shapes such as `[batch, sequence]`.
 
-## Tensor Lab
+### Exporting any PyTorch model to ONNX
 
-The original tensor-analysis MVP still exists as a lab for small handcrafted plans:
+mod-trace does not read native PyTorch `.pt`/`.pth` files (those are Python pickles / TorchScript archives). The supported path is to export to ONNX, which is the usual serving format anyway. For a plain `nn.Module` the export is a single call:
 
-```sh
-cargo run -- trace examples/tiny_attention_plan.json
-cargo run -- compare examples/tiny_attention_plan.json
-cargo run -- why examples/tiny_attention_plan.json
-cargo run -- validate examples/broken_shape.json
+```python
+import torch
+
+model.eval()
+dummy = torch.randn(1, n_features)          # one example input with the right shape
+torch.onnx.export(
+    model,
+    dummy,
+    "model.onnx",
+    input_names=["input"],
+    output_names=["output"],
+    opset_version=18,
+    dynamo=True,                            # optional; the modern exporter
+)
 ```
 
-Example plan:
-
-```json
-{
-  "layers": [
-    {
-      "type": "self_attention",
-      "tokens": 3,
-      "head_dim": 4,
-      "value_dim": 4
-    },
-    {
-      "type": "linear",
-      "in": 4,
-      "out": 2
-    },
-    {
-      "type": "softmax"
-    }
-  ]
-}
+```sh
+mod-trace inspect model.onnx
+mod-trace diff old_model.onnx new_model.onnx
 ```
 
-`why` explains the attention cost:
+Use fixed input shapes (e.g. `torch.randn(1, n_features)`) rather than dynamic axes for better cost estimates. Once exported, ONNX is read natively — no PyTorch, ONNX Runtime, or other framework is needed to inspect it.
 
-```text
-Why is attention expensive?
----------------------------
-Attention layer: single_head_attention
-  432 ops
-
-Breakdown:
-  Q projection             96 ops
-  K projection             96 ops
-  V projection             96 ops
-  Q @ K^T                  72 ops
-  attention @ V            72 ops
-
-Explanation:
-  Every token must compare itself against every other token.
-  The score and value-mixing terms grow roughly with tokens^2.
-```
+## Tensor Lab
 
-This is useful for demos and for explaining transformer internals, but it is no longer the primary product surface.
+A secondary lab for explaining transformer internals on small handcrafted JSON
+plans (`trace`, `compare`, `why`, `validate`, `quiz`, `demo`). It is not the
+primary product surface. See [docs/tensor-lab.md](docs/tensor-lab.md).
 
 ## What It Does Not Do
 

mod_trace-0.3.1/docs/tensor-lab.md

@@ -0,0 +1,66 @@
+# Tensor Lab (secondary)
+
+The original tensor-analysis MVP. It is **not** the primary product surface —
+mod-trace's main job is inspecting real model artifacts (CatBoost, LightGBM,
+ONNX). The tensor lab is kept for demos and for explaining transformer
+internals on small handcrafted JSON plans, in the spirit of `EXPLAIN ANALYZE`:
+
+```sql
+EXPLAIN ANALYZE SELECT ...
+```
+
+becomes:
+
+```sh
+mod-trace trace examples/tiny_attention_plan.json
+```
+
+## Commands
+
+```sh
+mod-trace trace    examples/tiny_attention_plan.json     # summarize a plan
+mod-trace compare  examples/tiny_attention_plan.json     # compare layers
+mod-trace why      examples/tiny_attention_plan.json     # explain attention cost
+mod-trace validate examples/broken_shape.json            # shape validation
+mod-trace tensor-inspect examples/mlp.json
+mod-trace quiz     examples/mlp.json
+mod-trace demo     attention
+mod-trace explain  <topic> [--step] [--shapes|--memory|--math|--compare] [--quiz]
+```
+
+(With a source checkout, replace `mod-trace` with `cargo run --`.)
+
+## Example plan
+
+```json
+{
+  "layers": [
+    { "type": "self_attention", "tokens": 3, "head_dim": 4, "value_dim": 4 },
+    { "type": "linear", "in": 4, "out": 2 },
+    { "type": "softmax" }
+  ]
+}
+```
+
+## `why` explains the attention cost
+
+```text
+Why is attention expensive?
+---------------------------
+Attention layer: single_head_attention
+  432 ops
+
+Breakdown:
+  Q projection             96 ops
+  K projection             96 ops
+  V projection             96 ops
+  Q @ K^T                  72 ops
+  attention @ V            72 ops
+
+Explanation:
+  Every token must compare itself against every other token.
+  The score and value-mixing terms grow roughly with tokens^2.
+```
+
+This is useful for demos and for explaining transformer internals, but it is no
+longer the primary product surface.

{mod_trace-0.2.0 → mod_trace-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "mod-trace"
-version = "0.2.0"
+version = "0.3.1"
 description = "Rust CLI for inspecting ML model artifacts without loading the framework"
 readme = "README.md"
 requires-python = ">=3.9"

{mod_trace-0.2.0 → mod_trace-0.3.1}/src/main.rs

@@ -40,6 +40,7 @@ fn run() -> Result<(), String> {
         Some("check") => check_cmd(&args.rest),
         Some("doctor") => doctor_cmd(&args.rest),
         Some("explain") => explain_cmd(&args.rest),
+        Some("explain-diff") => explain_diff_cmd(&args.rest),
         Some("explain-model") | Some("walkthrough") => explain_model_cmd(&args.rest),
         Some("demo") => demo_cmd(&args.rest),
         Some("tour") => {
@@ -191,11 +192,15 @@ fn print_doctor_report(report: &DoctorReport) {
     println!();
     println!("Available commands:");
     println!(
-        "  inspect .cbm/.onnx/.json: {}",
+        "  inspect .cbm/.lgb/.onnx/.json: {}",
         available_unavailable(report.commands.inspect_artifacts)
     );
     println!(
-        "  diff .cbm/.onnx: {}",
+        "  diff .cbm/.lgb/.onnx: {}",
+        available_unavailable(report.commands.diff_artifacts)
+    );
+    println!(
+        "  explain-diff .cbm/.lgb/.onnx: {}",
         available_unavailable(report.commands.diff_artifacts)
     );
     println!(
@@ -389,6 +394,7 @@ fn diff_cmd(args: &[String]) -> Result<(), String> {
 struct CheckOptions {
     max_size_growth_pct: Option<f64>,
     max_ops_growth_pct: Option<f64>,
+    max_parameter_growth_pct: Option<f64>,
     fail_on_feature_change: bool,
     fail_on_training_config_change: bool,
     fail_on_new_op: bool,
@@ -415,6 +421,13 @@ fn check_cmd(args: &[String]) -> Result<(), String> {
                 options.max_ops_growth_pct = Some(parse_percent_threshold(value)?);
                 i += 2;
             }
+            "--max-parameter-growth" => {
+                let value = args
+                    .get(i + 1)
+                    .ok_or_else(|| "--max-parameter-growth needs a percentage".to_string())?;
+                options.max_parameter_growth_pct = Some(parse_percent_threshold(value)?);
+                i += 2;
+            }
             "--fail-on-feature-change" => {
                 options.fail_on_feature_change = true;
                 i += 1;
@@ -462,13 +475,16 @@ fn check_cmd(args: &[String]) -> Result<(), String> {
 }
 
 fn check_usage() -> String {
-    "usage: mod-trace check [--max-size-growth 20%] [--max-ops-growth 25%] [--fail-on-feature-change] [--fail-on-training-config-change] [--fail-on-new-op] <old-model> <new-model>".to_string()
+    "usage: mod-trace check [--max-size-growth 20%] [--max-ops-growth 25%] [--max-parameter-growth 30%] [--fail-on-feature-change] [--fail-on-training-config-change] [--fail-on-new-op] <old-model> <new-model>".to_string()
 }
 
 fn check_catboost(old_path: &str, new_path: &str, options: &CheckOptions) -> Result<(), String> {
     if options.max_ops_growth_pct.is_some() {
         return Err("--max-ops-growth is only supported for ONNX artifacts.".to_string());
     }
+    if options.max_parameter_growth_pct.is_some() {
+        return Err("--max-parameter-growth is only supported for ONNX artifacts.".to_string());
+    }
     if options.fail_on_new_op {
         return Err("--fail-on-new-op is only supported for ONNX artifacts.".to_string());
     }
@@ -545,6 +561,15 @@ fn check_onnx(old_path: &str, new_path: &str, options: &CheckOptions) -> Result<
         ));
     }
 
+    if let Some(max_pct) = options.max_parameter_growth_pct {
+        checks.push(growth_check(
+            "parameter growth",
+            old.total_parameter_values,
+            new.total_parameter_values,
+            max_pct,
+        ));
+    }
+
     if options.fail_on_new_op {
         let old_ops = old
             .op_counts
@@ -972,6 +997,268 @@ fn explain_onnx_cmd(path: &str) -> Result<(), String> {
     Ok(())
 }
 
+fn explain_diff_cmd(args: &[String]) -> Result<(), String> {
+    let paths = args
+        .iter()
+        .filter(|arg| !arg.starts_with("--"))
+        .collect::<Vec<_>>();
+    if paths.len() != 2 {
+        return Err(
+            "usage: mod-trace explain-diff <old-model> <new-model>  (.onnx, .cbm, or .lgb/.txt)"
+                .to_string(),
+        );
+    }
+    let (old, new) = (paths[0].as_str(), paths[1].as_str());
+    match (artifact_kind(old), artifact_kind(new)) {
+        (ArtifactKind::Onnx, ArtifactKind::Onnx) => explain_diff_onnx(old, new),
+        (ArtifactKind::LightGbm, ArtifactKind::LightGbm) => explain_diff_lgbm(old, new),
+        (ArtifactKind::CatBoost, ArtifactKind::CatBoost) => explain_diff_catboost(old, new),
+        (left, right) => Err(format!(
+            "explain-diff needs two artifacts of the same supported type (.onnx, .cbm, .lgb): {} vs {}",
+            left.label(),
+            right.label()
+        )),
+    }
+}
+
+fn opt_num(value: Option<usize>) -> String {
+    value
+        .map(|value| value.to_string())
+        .unwrap_or_else(|| "unknown".to_string())
+}
+
+fn format_count_human(count: usize) -> String {
+    let value = count as f64;
+    if value >= 1e9 {
+        format!("{:.1}B", value / 1e9)
+    } else if value >= 1e6 {
+        format!("{:.1}M", value / 1e6)
+    } else if value >= 1e3 {
+        format!("{:.1}K", value / 1e3)
+    } else {
+        count.to_string()
+    }
+}
+
+fn growth_label(old: usize, new: usize) -> String {
+    match growth_percent(old, new) {
+        Some(pct) if pct.abs() < 0.005 => "same".to_string(),
+        Some(pct) => format!("{pct:+.0}%"),
+        None => {
+            if new == old {
+                "same".to_string()
+            } else {
+                "n/a (from zero)".to_string()
+            }
+        }
+    }
+}
+
+fn explain_diff_onnx(old_path: &str, new_path: &str) -> Result<(), String> {
+    let old = onnx::inspect(old_path)?;
+    let new = onnx::inspect(new_path)?;
+
+    let old_layers = estimate_transformer_layers(
+        op_count(&old, "Softmax"),
+        op_count(&old, "LayerNormalization"),
+        op_count(&old, "Attention"),
+    );
+    let new_layers = estimate_transformer_layers(
+        op_count(&new, "Softmax"),
+        op_count(&new, "LayerNormalization"),
+        op_count(&new, "Attention"),
+    );
+    let old_hidden = estimate_hidden_size(&old);
+    let new_hidden = estimate_hidden_size(&new);
+
+    let old_ops = old
+        .op_counts
+        .iter()
+        .map(|(name, _)| name)
+        .collect::<BTreeSet<_>>();
+    let new_ops = new
+        .op_counts
+        .iter()
+        .map(|(name, _)| name)
+        .collect::<BTreeSet<_>>();
+    let added = new_ops
+        .difference(&old_ops)
+        .map(|name| (*name).clone())
+        .collect::<Vec<_>>();
+    let removed = old_ops
+        .difference(&new_ops)
+        .map(|name| (*name).clone())
+        .collect::<Vec<_>>();
+
+    println!("Model Change Explanation");
+    println!("------------------------");
+    println!("Type: ONNX");
+    println!("Old: {}", old.path);
+    println!("New: {}", new.path);
+    println!();
+    println!("Architecture:");
+    println!(
+        "  Attention layers:  {} -> {}",
+        opt_num(old_layers),
+        opt_num(new_layers)
+    );
+    println!(
+        "  Hidden size:       {} -> {}",
+        opt_num(old_hidden),
+        opt_num(new_hidden)
+    );
+    println!(
+        "  Parameters:        {} -> {} ({})",
+        format_count_human(old.total_parameter_values),
+        format_count_human(new.total_parameter_values),
+        growth_label(old.total_parameter_values, new.total_parameter_values)
+    );
+    println!(
+        "  Nodes:             {} -> {} ({})",
+        old.nodes.len(),
+        new.nodes.len(),
+        growth_label(old.nodes.len(), new.nodes.len())
+    );
+    println!();
+    println!(
+        "Estimated inference cost (static op proxy): {}",
+        growth_label(old.estimated_ops, new.estimated_ops)
+    );
+    println!();
+    if added.is_empty() {
+        println!("New operators introduced: none");
+    } else {
+        println!("New operators introduced:");
+        for op in &added {
+            println!("  {op}");
+        }
+    }
+    if !removed.is_empty() {
+        println!("Operators removed:");
+        for op in &removed {
+            println!("  {op}");
+        }
+    }
+    println!();
+    println!("Summary:");
+    match (old_layers, new_layers) {
+        (Some(a), Some(b)) if a != b => println!(
+            "  Grew from ~{a} to ~{b} attention layers; parameters {}, estimated cost {}.",
+            growth_label(old.total_parameter_values, new.total_parameter_values),
+            growth_label(old.estimated_ops, new.estimated_ops)
+        ),
+        _ => println!(
+            "  Parameters {}, estimated cost {}.",
+            growth_label(old.total_parameter_values, new.total_parameter_values),
+            growth_label(old.estimated_ops, new.estimated_ops)
+        ),
+    }
+    println!();
+    println!(
+        "Note: static heuristic over ONNX ops and shapes; cost is an op-count proxy, not measured latency."
+    );
+
+    Ok(())
+}
+
+fn explain_diff_lgbm(old_path: &str, new_path: &str) -> Result<(), String> {
+    let old = lgbm::inspect(old_path)?;
+    let new = lgbm::inspect(new_path)?;
+
+    println!("Model Change Explanation");
+    println!("------------------------");
+    println!("Type: LightGBM");
+    println!("Old: {}", old.path);
+    println!("New: {}", new.path);
+    println!();
+    println!("Architecture:");
+    println!(
+        "  Trees:             {} -> {} ({})",
+        old.num_trees,
+        new.num_trees,
+        growth_label(old.num_trees as usize, new.num_trees as usize)
+    );
+    println!(
+        "  Leaves / tree:     {} -> {}",
+        opt_num(old.num_leaves.map(|value| value as usize)),
+        opt_num(new.num_leaves.map(|value| value as usize))
+    );
+    println!(
+        "  Features:          {} -> {}",
+        opt_num(old.num_features.map(|value| value as usize)),
+        opt_num(new.num_features.map(|value| value as usize))
+    );
+    println!(
+        "  Objective:         {} -> {}",
+        old.objective.as_deref().unwrap_or("unknown"),
+        new.objective.as_deref().unwrap_or("unknown")
+    );
+    println!();
+    match (old.estimated_leaf_values(), new.estimated_leaf_values()) {
+        (Some(o), Some(n)) => println!(
+            "Estimated leaf-slot growth: {}",
+            growth_label(o as usize, n as usize)
+        ),
+        _ => println!("Estimated leaf-slot growth: unknown"),
+    }
+    println!();
+    if old.learned_state_fingerprint != new.learned_state_fingerprint {
+        println!("Learned state: CHANGED (a real retrain - leaf values differ)");
+    } else {
+        println!("Learned state: unchanged (identical leaf values)");
+    }
+    println!();
+    println!("Note: parsed natively from the LightGBM text model.");
+
+    Ok(())
+}
+
+fn explain_diff_catboost(old_path: &str, new_path: &str) -> Result<(), String> {
+    let old = cbm::inspect(old_path)?;
+    let new = cbm::inspect(new_path)?;
+
+    println!("Model Change Explanation");
+    println!("------------------------");
+    println!("Type: CatBoost");
+    println!("Old: {}", old.path);
+    println!("New: {}", new.path);
+    println!();
+    println!("Architecture:");
+    println!(
+        "  Trees:             {} -> {}",
+        opt_num(old.iterations.map(|value| value as usize)),
+        opt_num(new.iterations.map(|value| value as usize))
+    );
+    println!(
+        "  Depth:             {} -> {}",
+        opt_num(old.depth.map(|value| value as usize)),
+        opt_num(new.depth.map(|value| value as usize))
+    );
+    println!(
+        "  Features (recovered): {} -> {}",
+        old.feature_candidates.len(),
+        new.feature_candidates.len()
+    );
+    println!();
+    match (old.estimated_leaf_values(), new.estimated_leaf_values()) {
+        (Some(o), Some(n)) => println!(
+            "Estimated leaf-slot growth: {}",
+            growth_label(o as usize, n as usize)
+        ),
+        _ => println!("Estimated leaf-slot growth: unknown"),
+    }
+    println!();
+    if old.learned_state_fingerprint != new.learned_state_fingerprint {
+        println!("Learned state: CHANGED (split borders / leaf values differ)");
+    } else {
+        println!("Learned state: unchanged");
+    }
+    println!();
+    println!("Note: CatBoost internals are summarized; run `diff --deep` for exact split/leaf changes.");
+
+    Ok(())
+}
+
 fn op_count(report: &onnx::OnnxReport, op_type: &str) -> usize {
     report
         .op_counts
@@ -2549,6 +2836,9 @@ fn check_lgbm(old_path: &str, new_path: &str, options: &CheckOptions) -> Result<
     if options.max_ops_growth_pct.is_some() {
         return Err("--max-ops-growth is only supported for ONNX artifacts.".to_string());
     }
+    if options.max_parameter_growth_pct.is_some() {
+        return Err("--max-parameter-growth is only supported for ONNX artifacts.".to_string());
+    }
     if options.fail_on_new_op {
         return Err("--fail-on-new-op is only supported for ONNX artifacts.".to_string());
     }
@@ -3090,19 +3380,16 @@ fn print_help() {
 Core usage:\n  \
 mod-trace doctor [--json]\n  \
 mod-trace inspect [--deep] [--json] [--limit 20] <model.cbm|model.lgb|model.onnx|model.json>\n  \
-mod-trace diff [--deep] [--json] <old-model> <new-model>  (.cbm, .lgb/.txt LightGBM, or .onnx)\n\n\
-mod-trace check [--max-size-growth 20%] [--max-ops-growth 25%] [--fail-on-feature-change] [--fail-on-training-config-change] [--fail-on-new-op] <old-model> <new-model>\n\n\
+mod-trace diff [--deep] [--json] <old-model> <new-model>  (.cbm, .lgb/.txt LightGBM, or .onnx)\n  \
+mod-trace explain-diff <old-model> <new-model>  (plain-English what changed: layers, params, cost, new ops)\n\n\
+mod-trace check [--max-size-growth 20%] [--max-ops-growth 25%] [--max-parameter-growth 30%] [--fail-on-feature-change] [--fail-on-training-config-change] [--fail-on-new-op] <old-model> <new-model>\n\n\
 Artifact inspectors:\n  \
 mod-trace catboost [--deep] [--json] [--limit 20] <model.cbm> [more.cbm...]\n  \
 mod-trace lightgbm [--json] [--limit 20] <model.lgb|model.txt> [more...]\n  \
-mod-trace onnx [--json] [--limit 20] <model.onnx>\n\n\
-Tensor lab:\n  \
-mod-trace trace <model.json>\n  \
-mod-trace compare <model.json>\n  \
-mod-trace why <model.json>\n  \
-mod-trace validate <model.json>\n  \
-mod-trace tensor-inspect <model.json>\n  \
-mod-trace explain <model.onnx|model.cbm>\n  \
+mod-trace onnx [--json] [--limit 20] <model.onnx>\n  \
+mod-trace explain <model.onnx|model.cbm>\n\n\
+Tensor lab (secondary; see docs/tensor-lab.md):\n  \
+mod-trace trace|compare|why|validate|tensor-inspect <model.json>\n  \
 mod-trace explain <topic> [--step] [--shapes|--memory|--math|--compare] [--quiz]\n\n\
 Examples:\n  \
 mod-trace doctor\n  \
@@ -3205,6 +3492,22 @@ fn format_hex(value: u64) -> String {
 mod tests {
     use super::*;
 
+    #[test]
+    fn format_count_human_scales_units() {
+        assert_eq!(format_count_human(676), "676");
+        assert_eq!(format_count_human(19_204), "19.2K");
+        assert_eq!(format_count_human(110_000_000), "110.0M");
+        assert_eq!(format_count_human(2_200_000_000), "2.2B");
+    }
+
+    #[test]
+    fn growth_label_formats_changes() {
+        assert_eq!(growth_label(100, 200), "+100%");
+        assert_eq!(growth_label(200, 100), "-50%");
+        assert_eq!(growth_label(100, 100), "same");
+        assert_eq!(growth_label(0, 5), "n/a (from zero)");
+    }
+
     #[test]
     fn estimates_transformer_layers_from_attention_signals() {
         assert_eq!(estimate_transformer_layers(12, 24, 0), Some(12));

mod_trace-0.2.0/.claude/scheduled_tasks.lock

@@ -1 +0,0 @@
-{"sessionId":"a6f7a6f9-0897-4154-80fe-a91a5084903f","pid":34928,"procStart":"Thu Jun  4 15:37:09 2026","acquiredAt":1780606199550}

mod_trace-0.2.0/mt-demo/make_onnx_pair.py

@@ -1,27 +0,0 @@
-import numpy as np, onnx, os
-from onnx import helper, TensorProto, numpy_helper
-
-def build(path, seed, producer_ver, hidden=64, classes=4):
-    rng = np.random.default_rng(seed)
-    def arr(name, *shape):
-        return numpy_helper.from_array(rng.standard_normal(shape).astype(np.float32) * 0.1, name)
-    inp = helper.make_tensor_value_info("input",  TensorProto.FLOAT, [1, 16])
-    out = helper.make_tensor_value_info("logits", TensorProto.FLOAT, [1, classes])
-    inits = [arr("W1", 16, hidden), arr("b1", hidden), arr("W2", hidden, classes), arr("b2", classes)]
-    nodes = [
-        helper.make_node("Gemm", ["input", "W1", "b1"], ["h1"]),
-        helper.make_node("Relu", ["h1"], ["a1"]),
-        helper.make_node("Gemm", ["a1", "W2", "b2"], ["z"]),
-        helper.make_node("Identity", ["z"], ["logits"]),
-    ]
-    g = helper.make_graph(nodes, "classifier", [inp], [out], initializer=inits)
-    m = helper.make_model(g, producer_name="demo-trainer", producer_version=producer_ver,
-                          opset_imports=[helper.make_opsetid("", 13)])
-    onnx.checker.check_model(m)
-    onnx.save(m, path)
-    print("wrote", path)
-
-os.makedirs("/tmp/mt-demo", exist_ok=True)
-# same architecture & shapes; only the learned weights (and producer version) differ -> a "retrain"
-build("/tmp/mt-demo/model_a.onnx", seed=1, producer_ver="1.0")
-build("/tmp/mt-demo/model_b.onnx", seed=2, producer_ver="1.1")