Metadata-Version: 2.4
Name: metrik-explorer
Version: 0.3.1
Summary: Metrik Model Explorer — architecture, parameter, and memory analysis without a forward pass.
Project-URL: Homepage, https://github.com/Asmodeus14/Metrik
Project-URL: Repository, https://github.com/Asmodeus14/Metrik
Project-URL: Issues, https://github.com/Asmodeus14/Metrik/issues
Author: The Metrik Authors
License-Expression: Apache-2.0
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Requires-Dist: metrik-sdk==0.3.1
Description-Content-Type: text/markdown

# metrik-explorer

Architecture, parameter, and memory analysis — **without a forward pass, without torch, and
without a GPU**.

```console
$ metrik explore ./models/TinyLlama-1.1B
```

Reads safetensors headers (a length-prefixed JSON blob) and `config.json`. **No tensor is ever
deserialized**, no torch is imported, and no forward pass happens.

One honest caveat: `ModelFingerprint.weight_digest` is a merkle over the weight files, because
identity has to be content-based — a benchmark result attached to a *name* rather than a digest
is unfalsifiable ([`artifacts.md`](../../docs/planning/artifacts.md) §6.1). So the command does
stream every weight byte through BLAKE3 once. It is I/O-bound, not compute-bound, and nothing
is held in memory, but it is not free on a 140 GB directory. Header parsing alone *is* free,
and that is what the structural analysis uses.

Emits four artifacts:

| Artifact | What it carries |
|---|---|
| `ModelFingerprint` | identity: merkle over weight files, config digest, param split |
| `ModelGraph` | one node per tensor — **no edges**, declared as an omission |
| `GraphSummary` | role/dtype/depth breakdown plus evidenced observations |
| `MemoryEstimate` | analytic weights + KV cache, with stated assumptions |

## What it deliberately does not do

- **No `ParamStats`.** Per-tensor statistics need the weight data and a blob format that is
  still an open question ([`artifacts.md`](../../docs/planning/artifacts.md) §8, question 1).
- **No graph edges.** Headers describe storage, not dataflow. A topology needs torch and a
  forward pass, which is a different loader behind the same contract.
- **No measured numbers.** `MemoryEstimate` is analytic by type and can never contain one
  ([`artifacts.md`](../../docs/planning/artifacts.md) §5).

Role classification is name-based pattern matching, so `GraphSummary.classification_confidence`
always reports what fraction of parameters it could not classify. A confident breakdown of a
model the heuristic did not understand is worse than no breakdown.
