mod-trace 0.3.2__tar.gz → 0.4.1__tar.gz

{mod_trace-0.3.2 → mod_trace-0.4.1}/Cargo.lock

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

{mod_trace-0.3.2 → mod_trace-0.4.1}/Cargo.toml

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

{mod_trace-0.3.2 → mod_trace-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mod-trace
-Version: 0.3.2
+Version: 0.4.1
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
@@ -25,7 +25,7 @@ mod-trace is a small Rust CLI for answering a practical question:
 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).
+It can inspect real artifacts such as CatBoost `.cbm` files, LightGBM `.txt`/`.lgb` text models, ONNX `.onnx` graphs, and PyTorch `.pt`/`.pth` checkpoints, then report structure, size, parameters, operator mix, rough inference cost, and changes between versions. All formats are read natively — no Python, framework, or runtime needed (CatBoost `--deep` is the one optional exception). The PyTorch reader is static: it sizes/names tensors and fingerprints weights without decoding exact shapes.
 
 The most useful command is `explain-diff`, which says in plain English what changed between two model versions:
 
@@ -500,9 +500,27 @@ 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]`.
 
+## PyTorch
+
+mod-trace reads PyTorch `torch.save` files (`.pt`, `.pth`, `.bin`, `.ckpt`) **natively — no torch, no Python**:
+
+```sh
+mod-trace inspect      model.pt
+mod-trace diff         old.pt new.pt
+mod-trace explain-diff old.pt new.pt
+mod-trace check --max-parameter-growth 30% old.pt new.pt
+```
+
+It parses the `torch.save` zip (pickled structure + raw tensor storages) and reports file size, tensor count, **estimated parameter count** (storage bytes ÷ dtype), **dominant dtype**, **recovered parameter/layer names**, and a sampled weight fingerprint that changes on a retrain/finetune. ZIP64 is handled for models over 4 GB.
+
+Limits, by design:
+- **Tensor shapes are not decoded** (that needs a full pickle interpreter) — you get counts, names, and dtype, not per-tensor shapes.
+- **Legacy (pre-1.6) pickle `.pt`** and older Hugging Face `pytorch_model.bin` recover names + a fingerprint but not parameter sizes (tensors aren't stored as zip entries there). Modern zip-format saves get the full report.
+- **`.safetensors` is a different format** and is not read by mod-trace.
+
 ### Exporting any PyTorch model to ONNX
 
-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:
+For richer graph-level detail (operators, attention layers), or if you only have a `.safetensors`/legacy file, export to ONNX — the usual serving format — which mod-trace reads fully. For a plain `nn.Module` the export is a single call:
 
 ```python
 import torch

{mod_trace-0.3.2 → mod_trace-0.4.1}/README.md

@@ -8,7 +8,7 @@ mod-trace is a small Rust CLI for answering a practical question:
 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).
+It can inspect real artifacts such as CatBoost `.cbm` files, LightGBM `.txt`/`.lgb` text models, ONNX `.onnx` graphs, and PyTorch `.pt`/`.pth` checkpoints, then report structure, size, parameters, operator mix, rough inference cost, and changes between versions. All formats are read natively — no Python, framework, or runtime needed (CatBoost `--deep` is the one optional exception). The PyTorch reader is static: it sizes/names tensors and fingerprints weights without decoding exact shapes.
 
 The most useful command is `explain-diff`, which says in plain English what changed between two model versions:
 
@@ -483,9 +483,27 @@ 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]`.
 
+## PyTorch
+
+mod-trace reads PyTorch `torch.save` files (`.pt`, `.pth`, `.bin`, `.ckpt`) **natively — no torch, no Python**:
+
+```sh
+mod-trace inspect      model.pt
+mod-trace diff         old.pt new.pt
+mod-trace explain-diff old.pt new.pt
+mod-trace check --max-parameter-growth 30% old.pt new.pt
+```
+
+It parses the `torch.save` zip (pickled structure + raw tensor storages) and reports file size, tensor count, **estimated parameter count** (storage bytes ÷ dtype), **dominant dtype**, **recovered parameter/layer names**, and a sampled weight fingerprint that changes on a retrain/finetune. ZIP64 is handled for models over 4 GB.
+
+Limits, by design:
+- **Tensor shapes are not decoded** (that needs a full pickle interpreter) — you get counts, names, and dtype, not per-tensor shapes.
+- **Legacy (pre-1.6) pickle `.pt`** and older Hugging Face `pytorch_model.bin` recover names + a fingerprint but not parameter sizes (tensors aren't stored as zip entries there). Modern zip-format saves get the full report.
+- **`.safetensors` is a different format** and is not read by mod-trace.
+
 ### Exporting any PyTorch model to ONNX
 
-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:
+For richer graph-level detail (operators, attention layers), or if you only have a `.safetensors`/legacy file, export to ONNX — the usual serving format — which mod-trace reads fully. For a plain `nn.Module` the export is a single call:
 
 ```python
 import torch

mod_trace-0.4.1/examples/pytorch/README.md

@@ -0,0 +1,35 @@
+# PyTorch example models
+
+Synthetic `torch.save` artifacts for trying `mod-trace` on PyTorch with **no
+torch and no Python** — mod-trace reads the `.pt` zip (pickled structure + raw
+tensor storages) statically.
+
+| Files | What they show |
+|-------|----------------|
+| `mlp_v1.pt` vs `mlp_v2.pt` | Same 2-layer MLP, hidden size 32 → 64 (parameter count ~doubles, same layer names). |
+
+## Try it
+
+```bash
+mod-trace inspect      examples/pytorch/mlp_v1.pt
+mod-trace explain-diff examples/pytorch/mlp_v1.pt examples/pytorch/mlp_v2.pt
+mod-trace check --max-parameter-growth 30% examples/pytorch/mlp_v1.pt examples/pytorch/mlp_v2.pt
+mod-trace inspect --json examples/pytorch/mlp_v1.pt
+```
+
+## What it reads (and what it doesn't)
+
+Reads, statically: file size, tensor/storage count, **estimated parameter count**
+(from storage bytes ÷ dtype), **dominant dtype**, **recovered parameter/layer
+names** (`fc1.weight`, …), and fingerprints (a sampled weight fingerprint that
+changes on a retrain/finetune).
+
+Does **not** decode exact per-tensor shapes — that would need a full pickle
+interpreter. Same static/heuristic philosophy as the CatBoost and ONNX readers.
+
+## Regenerate
+
+```bash
+python -m pip install torch
+python examples/pytorch/generate_demo_models.py
+```

mod_trace-0.4.1/examples/pytorch/generate_demo_models.py

@@ -0,0 +1,35 @@
+"""Generate the synthetic PyTorch demo models used by the README examples.
+
+Fully synthetic (no real data). Run:
+
+    python -m pip install torch
+    python examples/pytorch/generate_demo_models.py
+
+Produces, in this directory:
+  mlp_v1.pt / mlp_v2.pt  -> same 2-layer MLP, different hidden size (32 vs 64)
+"""
+
+import os
+
+import torch
+import torch.nn as nn
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+
+
+class Net(nn.Module):
+    def __init__(self, hidden):
+        super().__init__()
+        self.fc1 = nn.Linear(16, hidden)
+        self.fc2 = nn.Linear(hidden, 4)
+
+    def forward(self, x):
+        return self.fc2(torch.relu(self.fc1(x)))
+
+
+if __name__ == "__main__":
+    torch.manual_seed(0)
+    torch.save(Net(32).state_dict(), os.path.join(HERE, "mlp_v1.pt"))
+    torch.manual_seed(1)
+    torch.save(Net(64).state_dict(), os.path.join(HERE, "mlp_v2.pt"))
+    print("wrote mlp_v1.pt and mlp_v2.pt")

{mod_trace-0.3.2 → mod_trace-0.4.1}/pyproject.toml

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