metrik-core 0.1.0__tar.gz

metrik_core-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_core-0.1.0/PKG-INFO

@@ -0,0 +1,68 @@
+Metadata-Version: 2.4
+Name: metrik-core
+Version: 0.1.0
+Summary: Metrik core — artifact envelope, canonical serialization, content addressing.
+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
+Keywords: machine-learning,provenance,quantization,reproducibility
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Requires-Dist: blake3>=1.0
+Requires-Dist: packaging>=23.0
+Requires-Dist: pydantic>=2.7
+Description-Content-Type: text/markdown
+
+# metrik-core
+
+The vocabulary every other Metrik package agrees on: the artifact envelope, canonical
+serialization, and content addressing.
+
+**This package defines vocabulary, not behaviour** (`plan.md` §4). It has no ML dependencies —
+no torch, no transformers — which is enforced in CI by `import-linter`, not by convention. That
+constraint is what lets the artifact layer be installed and reasoned about without a multi-gigabyte
+ML stack.
+
+Not published yet. Phase 2 of [the roadmap](../../ROADMAP.md).
+
+## What is here so far
+
+| Module | Purpose |
+|---|---|
+| `metrik.core.hashing` | Canonical JSON, `Digest`, `content_hash`, `derivation_hash` |
+| `metrik.core.errors` | The error taxonomy plugins raise from |
+| `metrik.core.artifacts` | The envelope every artifact carries |
+
+## The two hashes
+
+The subtlest part of the design, and getting it wrong makes both caching and reproducibility
+silently unreliable. There are two questions, so there are two hashes:
+
+| Question | Answered by |
+|---|---|
+| *Is this the same result as that?* | `content_hash` — over the payload only |
+| *Have I already computed this, so can I skip the work?* | `derivation_hash` — over how it was asked for |
+
+A single hash cannot do both. Caching needs a key computable **before** running, so it must cover
+inputs and parameters rather than results. Dedup and citation need a key covering **only** the
+value, so two runs producing identical numbers are recognised as identical even if asked for
+differently.
+
+Because both are recorded, the store can *check* a producer's determinism claim rather than
+believe it: same `derivation_hash`, different `content_hash`, and a declared class of
+`deterministic` means the declaration is false.
+
+## Specification
+
+The full contract is [`docs/planning/artifacts.md`](../../docs/planning/artifacts.md). This
+package implements §2 (envelope), §3 (hashing and canonicalization), and §4 (blobs).
+
+Canonicalization rules are normative and tested as properties, not examples — see
+`tests/test_canonical_properties.py`.

metrik_core-0.1.0/README.md

@@ -0,0 +1,46 @@
+# metrik-core
+
+The vocabulary every other Metrik package agrees on: the artifact envelope, canonical
+serialization, and content addressing.
+
+**This package defines vocabulary, not behaviour** (`plan.md` §4). It has no ML dependencies —
+no torch, no transformers — which is enforced in CI by `import-linter`, not by convention. That
+constraint is what lets the artifact layer be installed and reasoned about without a multi-gigabyte
+ML stack.
+
+Not published yet. Phase 2 of [the roadmap](../../ROADMAP.md).
+
+## What is here so far
+
+| Module | Purpose |
+|---|---|
+| `metrik.core.hashing` | Canonical JSON, `Digest`, `content_hash`, `derivation_hash` |
+| `metrik.core.errors` | The error taxonomy plugins raise from |
+| `metrik.core.artifacts` | The envelope every artifact carries |
+
+## The two hashes
+
+The subtlest part of the design, and getting it wrong makes both caching and reproducibility
+silently unreliable. There are two questions, so there are two hashes:
+
+| Question | Answered by |
+|---|---|
+| *Is this the same result as that?* | `content_hash` — over the payload only |
+| *Have I already computed this, so can I skip the work?* | `derivation_hash` — over how it was asked for |
+
+A single hash cannot do both. Caching needs a key computable **before** running, so it must cover
+inputs and parameters rather than results. Dedup and citation need a key covering **only** the
+value, so two runs producing identical numbers are recognised as identical even if asked for
+differently.
+
+Because both are recorded, the store can *check* a producer's determinism claim rather than
+believe it: same `derivation_hash`, different `content_hash`, and a declared class of
+`deterministic` means the declaration is false.
+
+## Specification
+
+The full contract is [`docs/planning/artifacts.md`](../../docs/planning/artifacts.md). This
+package implements §2 (envelope), §3 (hashing and canonicalization), and §4 (blobs).
+
+Canonicalization rules are normative and tested as properties, not examples — see
+`tests/test_canonical_properties.py`.

metrik_core-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "metrik-core"
+version = "0.1.0"
+description = "Metrik core — artifact envelope, canonical serialization, content addressing."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "Apache-2.0"
+authors = [{ name = "The Metrik Authors" }]
+keywords = ["machine-learning", "quantization", "provenance", "reproducibility"]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+# Deliberately tiny. metrik-core defines vocabulary, not behaviour (plan.md §4), and
+# must be installable without a multi-GB ML stack:
+#   - NO torch, NO transformers — enforced by .importlinter (ADR 007).
+#   - blake3 is a compiled dependency, taken knowingly: buy native performance as a
+#     dependency rather than as a component (ADR 001, ADR 023).
+dependencies = [
+    "pydantic>=2.7",
+    "blake3>=1.0",
+    # Semver range parsing for plugin API compatibility. Pure Python, no transitive deps,
+    # already present in every build environment -- the alternative is hand-rolling version
+    # comparison, which is a well-known way to be subtly wrong about pre-releases.
+    "packaging>=23.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/Asmodeus14/Metrik"
+Repository = "https://github.com/Asmodeus14/Metrik"
+Issues = "https://github.com/Asmodeus14/Metrik/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/metrik"]

metrik_core-0.1.0/src/metrik/core/__init__.py

@@ -0,0 +1,239 @@
+"""Metrik core — the vocabulary every other package agrees on.
+
+This package defines vocabulary, not behaviour (``plan.md`` §4). It has **no ML
+dependencies** — no torch, no transformers — which is enforced in CI by ``import-linter``
+rather than by convention, and is what lets the artifact layer be installed and reasoned
+about without a multi-gigabyte stack.
+
+Specification: ``docs/planning/artifacts.md``.
+"""
+
+from __future__ import annotations
+
+from metrik.core.artifacts.artifact import MAX_PAYLOAD_BYTES, Artifact, build_artifact
+from metrik.core.artifacts.envelope import (
+    ROOT_ARTIFACT_TYPES,
+    BlobRef,
+    DeterminismClass,
+    Envelope,
+    InputRef,
+    Omission,
+    PartialInfo,
+    ProducerRef,
+    Provenance,
+    ReasonCode,
+)
+from metrik.core.bench import (
+    BaselineComparison,
+    BenchResult,
+    ContaminationCheck,
+    CostRecord,
+    GenerationSpec,
+    HarnessName,
+    HarnessRef,
+    Isolation,
+    Metric,
+    SandboxAttestation,
+    SandboxLimits,
+    TaskRef,
+)
+from metrik.core.errors import (
+    BackendError,
+    CancelledError,
+    FailureKind,
+    InsufficientResourcesError,
+    LineageError,
+    MetrikError,
+    UnsupportedError,
+    UserError,
+    ValidationError,
+)
+from metrik.core.hashing import (
+    CanonicalizationError,
+    Digest,
+    HashAlgo,
+    canonical_bytes,
+    canonical_json,
+    content_hash,
+    derivation_hash,
+    hash_bytes,
+    hash_stream,
+)
+from metrik.core.ir import (
+    IR_VERSION,
+    AttentionKind,
+    Block,
+    Edge,
+    ExtractionInfo,
+    ExtractionMethod,
+    FfnKind,
+    Fidelity,
+    ModelGraph,
+    MoEInfo,
+    Node,
+    NodeKind,
+    NormKind,
+    PositionKind,
+    RoleTag,
+    RopeInfo,
+    TensorDecl,
+    TensorKind,
+    Topology,
+    op_node_id,
+)
+from metrik.core.lineage import Lineage, LineageEdge, lineage_of
+from metrik.core.plugins import PluginManifest, PluginProblem, PluginRef, PluginRegistry
+from metrik.core.runs import (
+    RUN_ARTIFACT_TYPE,
+    CacheEvent,
+    FailureInfo,
+    RunRecorder,
+    RunStatus,
+    Step,
+    StepStatus,
+)
+from metrik.core.store import ArtifactStore, BlobStore, DeterminismViolationWarning
+from metrik.core.viz import (
+    APPROVED_COLOR_SCHEMES,
+    MAX_INLINE_POINTS,
+    VIZ_SPEC_VERSION,
+    A11yBlock,
+    ChannelType,
+    Downsample,
+    EncodingDef,
+    Fallbacks,
+    Interaction,
+    InteractionKind,
+    ProvenanceBlock,
+    RenderHints,
+    ScaleDef,
+    TableSpec,
+    TransformKind,
+    TransformStep,
+    ViewKind,
+    VizData,
+    VizSpec,
+)
+
+
+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-core")
+
+__all__ = [
+    "APPROVED_COLOR_SCHEMES",
+    "IR_VERSION",
+    "MAX_INLINE_POINTS",
+    "MAX_PAYLOAD_BYTES",
+    "ROOT_ARTIFACT_TYPES",
+    "RUN_ARTIFACT_TYPE",
+    "VIZ_SPEC_VERSION",
+    "A11yBlock",
+    "Artifact",
+    "ArtifactStore",
+    "AttentionKind",
+    "BackendError",
+    "BaselineComparison",
+    "BenchResult",
+    "BlobRef",
+    "BlobStore",
+    "Block",
+    "CacheEvent",
+    "CancelledError",
+    "CanonicalizationError",
+    "ChannelType",
+    "ContaminationCheck",
+    "CostRecord",
+    "DeterminismClass",
+    "DeterminismViolationWarning",
+    "Digest",
+    "Downsample",
+    "Edge",
+    "EncodingDef",
+    "Envelope",
+    "ExtractionInfo",
+    "ExtractionMethod",
+    "FailureInfo",
+    "FailureKind",
+    "Fallbacks",
+    "FfnKind",
+    "Fidelity",
+    "GenerationSpec",
+    "HarnessName",
+    "HarnessRef",
+    "HashAlgo",
+    "InputRef",
+    "InsufficientResourcesError",
+    "Interaction",
+    "InteractionKind",
+    "Isolation",
+    "Lineage",
+    "LineageEdge",
+    "LineageError",
+    "Metric",
+    "MetrikError",
+    "MoEInfo",
+    "ModelGraph",
+    "Node",
+    "NodeKind",
+    "NormKind",
+    "Omission",
+    "PartialInfo",
+    "PluginManifest",
+    "PluginProblem",
+    "PluginRef",
+    "PluginRegistry",
+    "PositionKind",
+    "ProducerRef",
+    "Provenance",
+    "ProvenanceBlock",
+    "ReasonCode",
+    "RenderHints",
+    "RoleTag",
+    "RopeInfo",
+    "RunRecorder",
+    "RunStatus",
+    "SandboxAttestation",
+    "SandboxLimits",
+    "ScaleDef",
+    "Step",
+    "StepStatus",
+    "TableSpec",
+    "TaskRef",
+    "TensorDecl",
+    "TensorKind",
+    "Topology",
+    "TransformKind",
+    "TransformStep",
+    "UnsupportedError",
+    "UserError",
+    "ValidationError",
+    "ViewKind",
+    "VizData",
+    "VizSpec",
+    "__version__",
+    "build_artifact",
+    "canonical_bytes",
+    "canonical_json",
+    "content_hash",
+    "derivation_hash",
+    "hash_bytes",
+    "hash_stream",
+    "lineage_of",
+    "op_node_id",
+]

metrik_core-0.1.0/src/metrik/core/artifacts/__init__.py

@@ -0,0 +1,38 @@
+"""Artifact schemas.
+
+The envelope lives here. Concrete artifact types (``ModelFingerprint``, ``ModelGraph``,
+``ProfileRecord``, …) arrive alongside the producers that emit them; the catalogue is
+specified in ``docs/planning/artifacts.md`` §6.
+"""
+
+from __future__ import annotations
+
+from metrik.core.artifacts.artifact import MAX_PAYLOAD_BYTES, Artifact, build_artifact
+from metrik.core.artifacts.envelope import (
+    ROOT_ARTIFACT_TYPES,
+    BlobRef,
+    DeterminismClass,
+    Envelope,
+    InputRef,
+    Omission,
+    PartialInfo,
+    ProducerRef,
+    Provenance,
+    ReasonCode,
+)
+
+__all__ = [
+    "MAX_PAYLOAD_BYTES",
+    "ROOT_ARTIFACT_TYPES",
+    "Artifact",
+    "BlobRef",
+    "DeterminismClass",
+    "Envelope",
+    "InputRef",
+    "Omission",
+    "PartialInfo",
+    "ProducerRef",
+    "Provenance",
+    "ReasonCode",
+    "build_artifact",
+]

metrik_core-0.1.0/src/metrik/core/artifacts/artifact.py

@@ -0,0 +1,177 @@
+"""An artifact: envelope plus payload.
+
+The envelope is described in :mod:`metrik.core.artifacts.envelope`. This module is the pair,
+plus the one constructor producers should use — :func:`build_artifact`, which computes
+``content_hash`` from the payload rather than accepting it.
+
+That is deliberate. A producer that can *pass in* a content hash can pass in a wrong one, and
+a wrong content hash is undetectable by inspection and fatal to every citation that quotes it.
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import UTC, datetime
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, field_validator, model_validator
+
+from metrik.core.artifacts.envelope import (
+    DeterminismClass,
+    Envelope,
+    InputRef,
+    PartialInfo,
+    ProducerRef,
+)
+from metrik.core.hashing import (
+    Digest,
+    canonical_bytes,
+    canonical_json,
+    content_hash,
+    derivation_hash,
+)
+
+__all__ = ["MAX_PAYLOAD_BYTES", "Artifact", "build_artifact"]
+
+#: ``artifacts.md`` §4. A payload you cannot open in an editor is one nobody will review, and
+#: unreviewed artifacts are how a schema quietly starts carrying per-tensor arrays that scale
+#: with model size. Anything that scales goes to a blob and the payload keeps aggregates.
+MAX_PAYLOAD_BYTES = 1024 * 1024
+
+
+class Artifact(BaseModel):
+    """A stored fact: what was computed, and everything needed to trace it."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    envelope: Envelope
+    payload: dict[str, Any]
+
+    @field_validator("payload", mode="before")
+    @classmethod
+    def _canonicalize(cls, value: Any) -> Any:
+        """Replace the payload with its canonical form at construction.
+
+        Without this, an artifact does not survive a round trip through its own store. Rule 6
+        omits null fields on write (``artifacts.md`` §3.1), so ``{"license_id": None}`` is
+        stored as ``{}`` and read back with the key *missing* -- and a consumer written against
+        the schema gets ``KeyError`` where it expected ``None``. The hashes agree either way,
+        which is exactly what makes the discrepancy easy to miss.
+
+        Normalizing here means ``artifact.payload`` is always precisely what is on disk.
+        Canonicalization is idempotent (asserted as a property test), so doing it early cannot
+        change any hash.
+        """
+        if isinstance(value, dict):
+            return json.loads(canonical_json(value))
+        return value
+
+    @model_validator(mode="after")
+    def _check_self_consistent(self) -> Artifact:
+        actual = content_hash(self.payload, algo=self.envelope.content_hash.algo)
+        if actual != self.envelope.content_hash:
+            raise ValueError(
+                f"content_hash does not match payload: envelope claims "
+                f"{self.envelope.content_hash.short()}, payload hashes to {actual.short()}"
+            )
+        size = len(canonical_bytes(self.payload))
+        if size > MAX_PAYLOAD_BYTES:
+            raise ValueError(
+                f"payload is {size} bytes, over the {MAX_PAYLOAD_BYTES}-byte limit "
+                f"(artifacts.md sec. 4). Move the field that scales with model size into a blob "
+                f"and keep aggregates in the payload."
+            )
+        return self
+
+    @property
+    def artifact_id(self) -> Digest:
+        """The storage key: a digest over the envelope, **excluding ``created_at``**.
+
+        Not a third semantic hash. ``content_hash`` and ``derivation_hash`` answer the two
+        questions in ``artifacts.md`` §3; this one answers neither, it just names a file.
+
+        It has to exist because neither of the other two can serve as a primary key:
+
+        * ``content_hash`` cannot, because two producers can compute the same value by
+          different routes, and keying on it would silently discard the second one's
+          provenance — the exact information the spine exists to keep.
+        * ``derivation_hash`` cannot, because ``artifacts.md`` §3.3 requires the store to
+          hold two artifacts that share one and *differ* in ``content_hash``. That is how a
+          producer falsely claiming ``deterministic`` gets caught. Keying on it would
+          overwrite the evidence.
+
+        Git makes the same split for the same reason: a commit is not its tree.
+
+        Why ``created_at`` is excluded
+        ------------------------------
+
+        It records when we *noticed* a fact, not the fact. Including it meant re-running a
+        deterministic producer wrote a brand-new record every time, identical in every respect
+        that matters. Two real costs: the store grew without bound on repeated runs, and --
+        because ``InputRef`` resolves by ``content_hash`` -- each duplicate added another
+        candidate parent, so lineage went ambiguous on the second run and N-way ambiguous
+        after N. ``metrik explore`` run twice already showed it.
+
+        Everything distinguishing two genuine facts is still in the key: producer, version,
+        derivation, content, ``env``, ``labels``, ``partial``. Only the clock is dropped.
+        """
+        envelope = self.envelope.model_dump(exclude={"created_at"})
+        return content_hash(envelope, algo=self.envelope.content_hash.algo)
+
+
+def build_artifact(
+    *,
+    artifact_type: str,
+    schema_version: int,
+    payload: dict[str, Any],
+    determinism: DeterminismClass,
+    produced_by: ProducerRef,
+    inputs: tuple[InputRef, ...] = (),
+    params: Any = None,
+    seed: int | None = None,
+    device_class: str | None = None,
+    env: dict[str, object] | None = None,
+    labels: dict[str, str] | None = None,
+    supersedes: Digest | None = None,
+    partial: PartialInfo | None = None,
+    created_at: datetime | None = None,
+) -> Artifact:
+    """Assemble an artifact, computing both hashes from the inputs given.
+
+    Neither hash is a parameter, so neither can be wrong. ``derivation_hash`` is built from
+    the same ``params``/``inputs``/``seed`` the producer actually used, which is what makes a
+    later cache probe on those values meaningful.
+
+    Args:
+        params: The producer's typed parameter object. Untyped ``**kwargs`` have no canonical
+            form and therefore cannot be cached correctly (``sdk-contracts.md`` §4).
+        device_class: Pass only for producers declaring themselves device-sensitive.
+            Including it elsewhere fragments the cache for nothing.
+    """
+    ch = content_hash(payload)
+    dh = derivation_hash(
+        artifact_type=artifact_type,
+        schema_version=schema_version,
+        producer_name=produced_by.name,
+        producer_version=produced_by.version,
+        api_version=produced_by.api_version,
+        params=params,
+        inputs=[(ref.role, ref.content_hash) for ref in inputs],
+        seed=seed,
+        device_class=device_class,
+    )
+    envelope = Envelope(
+        artifact_type=artifact_type,
+        schema_version=schema_version,
+        content_hash=ch,
+        derivation_hash=dh,
+        determinism=determinism,
+        created_at=created_at or datetime.now(UTC),
+        produced_by=produced_by,
+        inputs=inputs,
+        env=env,
+        labels=labels or {},
+        supersedes=supersedes,
+        partial=partial,
+    )
+    return Artifact(envelope=envelope, payload=payload)