metrik-explorer 0.1.0__tar.gz

metrik_explorer-0.1.0/.gitignore

@@ -0,0 +1,89 @@
+# Metrik — .gitignore
+#
+# NOTE: the previous version of this file contained `docs/*`, `.gitignore`, and `.claude`,
+# which excluded the entire documentation tree — i.e. every Phase 0/1 deliverable — from
+# version control. Replaced deliberately. docs/ is the project's primary output right now.
+
+# --- Build output that must never be committed ---
+# ADR 016: diagram sources live in docs/diagrams/*.mmd; rendered images are build output.
+docs/static/diagrams/
+# ADR 015: generated reference docs are committed on purpose (drift detection), so they
+# are NOT ignored here — see docs/reference/.
+
+# --- Python ---
+__pycache__/
+*.py[cod]
+*.so
+.Python
+build/
+dist/
+*.egg-info/
+.eggs/
+.venv/
+venv/
+env/
+
+# Tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.hypothesis/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+.benchmarks/
+.tox/
+.nox/
+
+# uv (ADR 013) — uv.lock IS committed; the cache is not.
+.uv/
+
+# --- Node / web (ADR 009) ---
+node_modules/
+.next/
+out/
+.turbo/
+*.tsbuildinfo
+.pnpm-store/
+
+# --- Tauri (ADR 010) ---
+apps/desktop/src-tauri/target/
+apps/desktop/src-tauri/gen/
+
+# --- Docs site (ADR 015) ---
+docs/.docusaurus/
+docs/build/
+
+# --- Metrik runtime data ---
+# The artifact store and blob store (ADR 006). Content-addressed, machine-generated,
+# gigabytes. Never in git.
+.metrik/
+*.metrik-store/
+# Local config may hold API keys (ADR 018).
+metrik.local.toml
+.env
+.env.*
+!.env.example
+
+# Model weights and checkpoints — always too large, often license-encumbered (plan.md §5.7).
+*.safetensors
+*.gguf
+*.onnx
+*.pt
+*.pth
+*.bin
+# ...except the tiny-random fixtures, which are committed on purpose (ADR 017).
+!tests/fixtures/**
+
+# --- Editors and OS ---
+.vscode/
+!.vscode/extensions.json
+.idea/
+*.swp
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# --- Local agent/tooling settings ---
+.claude/settings.local.json

metrik_explorer-0.1.0/PKG-INFO

@@ -0,0 +1,56 @@
+Metadata-Version: 2.4
+Name: metrik-explorer
+Version: 0.1.0
+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.1.0
+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.

metrik_explorer-0.1.0/README.md

@@ -0,0 +1,40 @@
+# 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.

metrik_explorer-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "metrik-explorer"
+version = "0.1.0"
+description = "Metrik Model Explorer — architecture, parameter, and memory analysis without a forward pass."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "Apache-2.0"
+authors = [{ name = "The Metrik Authors" }]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+# metrik-sdk ONLY. Not metrik-core: the Explorer is a plugin with no privileged access, and
+# the `sdk-dogfooding` contract in .importlinter fails the build if that stops being true.
+#
+# No torch and no safetensors library either. A safetensors header is a length-prefixed JSON
+# blob, so the whole metadata path is stdlib -- which is what lets `metrik explore` run on a
+# laptop with no ML stack installed, and makes it honest that no forward pass occurred.
+dependencies = [
+    "metrik-sdk==0.1.0",
+]
+
+# The Explorer is discovered exactly the way a third-party plugin is: an entry point plus a
+# manifest shipped as package data. It gets no privileged path into the registry, which is
+# how we find out in Phase 2 whether plugin discovery actually works (plan.md Verification #2).
+[project.entry-points."metrik.loaders"]
+explorer = "metrik.explorer:Explorer"
+
+[project.urls]
+Homepage = "https://github.com/Asmodeus14/Metrik"
+Repository = "https://github.com/Asmodeus14/Metrik"
+Issues = "https://github.com/Asmodeus14/Metrik/issues"
+
+[tool.uv.sources]
+metrik-sdk = { workspace = true }
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/metrik"]

metrik_explorer-0.1.0/src/metrik/explorer/__init__.py

@@ -0,0 +1,44 @@
+"""Model Explorer — architecture, parameter, and memory analysis with no forward pass.
+
+``plan.md`` §5.1. Reads safetensors headers and ``config.json`` and nothing else, which is why
+it needs neither torch nor a GPU, and why the claim "no forward pass occurred" is checkable
+rather than asserted.
+
+Imports ``metrik.sdk`` and nothing else from Metrik. That is the dogfooding contract
+(``sdk-contracts.md`` §1): the built-in Explorer is a plugin with no privileged access, so if
+it ever needs something the SDK does not expose, the SDK is broken and gets fixed.
+"""
+
+from __future__ import annotations
+
+from metrik.explorer.producer import INFO, ExploreParams, Explorer
+from metrik.explorer.run import ExploreResult, explore
+
+
+def _distribution_version(name: str) -> str:
+    from importlib.metadata import PackageNotFoundError, version
+
+    try:
+        return version(name)
+    except PackageNotFoundError:  # pragma: no cover - only in an uninstalled source tree
+        return "0+unknown"
+
+
+#: Read from the installed distribution rather than hardcoded.
+#:
+#: Both existed for a while and drifted: a 0.1.0 build reported 0.0.1 from `metrik --version`,
+#: found by installing the actual wheel rather than by any test. A version string is exactly
+#: the kind of duplicate that stays wrong quietly, because nothing imports it in anger.
+#:
+#: The fallback covers a source checkout with nothing installed, where there is no metadata to
+#: read and no released version to name.
+__version__ = _distribution_version("metrik-explorer")
+
+__all__ = [
+    "INFO",
+    "ExploreParams",
+    "ExploreResult",
+    "Explorer",
+    "__version__",
+    "explore",
+]

metrik_explorer-0.1.0/src/metrik/explorer/metrik_plugin.json

@@ -0,0 +1,20 @@
+{
+  "explorer": {
+    "name": "explorer",
+    "kind": "model_loader",
+    "version": "0.0.1",
+    "metrik_api": ">=1.0,<2.0",
+    "summary": "Architecture, parameter, and memory analysis from safetensors headers. No forward pass.",
+    "homepage": "https://github.com/Asmodeus14/Metrik",
+    "license": "Apache-2.0",
+    "requires_device": [],
+    "requires_gradients": false,
+    "requires_calibration": false,
+    "requires_container": false,
+    "determinism": "deterministic",
+    "device_sensitive": false,
+    "writes_files": false,
+    "needs_network": false,
+    "executes_untrusted_code": false
+  }
+}

metrik_explorer-0.1.0/src/metrik/explorer/model_dir.py

@@ -0,0 +1,132 @@
+"""Locating and digesting the files that make up a model on disk."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from metrik.explorer.safetensors import SafetensorsHeader, read_header
+from metrik.sdk import Digest, HashAlgo, UserError, content_hash, hash_stream
+
+__all__ = ["ModelDir", "config_digest_of", "digest_file", "discover", "merkle_of"]
+
+WEIGHT_SUFFIXES = (".safetensors",)
+#: Formats we can see but not yet read. Named explicitly so the error can say which one.
+UNSUPPORTED_SUFFIXES = {
+    ".bin": "PyTorch pickle",
+    ".pt": "PyTorch pickle",
+    ".pth": "PyTorch pickle",
+    ".gguf": "GGUF",
+    ".onnx": "ONNX",
+}
+
+
+@dataclass(frozen=True)
+class ModelDir:
+    """A model directory, resolved and read."""
+
+    root: Path
+    headers: tuple[SafetensorsHeader, ...]
+    config: dict[str, Any]
+    config_path: Path | None
+    tokenizer_path: Path | None
+
+    @property
+    def weight_files(self) -> tuple[Path, ...]:
+        return tuple(h.path for h in self.headers)
+
+    def source_stamp(self) -> tuple[tuple[str, int, int], ...]:
+        """Cheap identity of the bytes on disk: (name, size, mtime_ns) per file, sorted.
+
+        Deliberately not a content digest. This feeds ``derivation_hash``, which must be
+        computable *before* running -- digesting gigabytes to decide whether to skip digesting
+        gigabytes is not a cache.
+        """
+        paths = [*self.weight_files]
+        if self.config_path:
+            paths.append(self.config_path)
+        return tuple(sorted((p.name, p.stat().st_size, p.stat().st_mtime_ns) for p in paths))
+
+
+def discover(uri: str) -> ModelDir:
+    """Resolve a local path to a model directory and read every safetensors header.
+
+    Only local paths in v0.1. Hugging Face resolution is a separate loader behind the same
+    contract; keeping it out means this path has no network dependency and no cache semantics
+    to reason about.
+    """
+    root = Path(uri).expanduser()
+    files: tuple[Path, ...]
+    if root.is_file() and root.suffix in WEIGHT_SUFFIXES:
+        root, files = root.parent, (root,)
+    elif root.is_dir():
+        files = tuple(sorted(p for p in root.iterdir() if p.suffix in WEIGHT_SUFFIXES))
+    else:
+        raise UserError(
+            f"{uri} is not a file or directory",
+            remediation="Pass a path to a model directory containing .safetensors files.",
+        )
+
+    if not files:
+        found = {p.suffix for p in root.iterdir() if p.is_file()} & set(UNSUPPORTED_SUFFIXES)
+        if found:
+            names = ", ".join(sorted(UNSUPPORTED_SUFFIXES[s] for s in found))
+            raise UserError(
+                f"{root} contains {names} weights, which this loader cannot read",
+                remediation=(
+                    "Convert to safetensors, or wait for the format-specific loader. Metrik "
+                    "reads safetensors headers without torch, which is why it is the one "
+                    "supported format in v0.1."
+                ),
+            )
+        raise UserError(
+            f"no .safetensors files in {root}",
+            remediation="Check the path points at a model directory.",
+        )
+
+    config_path = root / "config.json"
+    config: dict[str, Any] = {}
+    if config_path.is_file():
+        try:
+            config = json.loads(config_path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError) as exc:
+            raise UserError(
+                f"config.json in {root} is not readable JSON: {exc}",
+                remediation="Re-download the model, or remove the file to analyse weights only.",
+            ) from exc
+
+    tokenizer = root / "tokenizer.json"
+    return ModelDir(
+        root=root,
+        headers=tuple(read_header(p) for p in files),
+        config=config,
+        config_path=config_path if config_path.is_file() else None,
+        tokenizer_path=tokenizer if tokenizer.is_file() else None,
+    )
+
+
+def digest_file(path: Path) -> Digest:
+    with path.open("rb") as handle:
+        return hash_stream(handle)
+
+
+def merkle_of(digests: list[tuple[str, Digest]]) -> Digest:
+    """Combine per-file digests into one identity.
+
+    Sorted by path so the result does not depend on directory iteration order, and computed
+    over the *canonical form* of the (name, digest) pairs so it inherits the canonicalization
+    rules rather than inventing a second, subtly different, serialization.
+    """
+    return content_hash([{"path": name, "digest": str(digest)} for name, digest in sorted(digests)])
+
+
+def config_digest_of(config: dict[str, Any]) -> Digest:
+    """Hash a parsed config.
+
+    Over the parsed object rather than the raw bytes, so that reformatting ``config.json``
+    (whitespace, key order) does not invalidate every cached analysis -- while a real change
+    to a value still does.
+    """
+    return content_hash(config, algo=HashAlgo.BLAKE3)