metrik-sdk 0.1.0__tar.gz

metrik_sdk-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_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,35 @@
+Metadata-Version: 2.4
+Name: metrik-sdk
+Version: 0.1.0
+Summary: Metrik plugin SDK — the public contracts every producer and consumer is written against.
+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 :: Developers
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Requires-Dist: metrik-core==0.1.0
+Requires-Dist: pydantic>=2.7
+Description-Content-Type: text/markdown
+
+# metrik-sdk
+
+The public contracts. Every first-party module is written against this package and nothing
+else — if a built-in producer needs something the SDK does not expose, that is a **bug in the
+SDK**, and the fix is to expose it publicly rather than to reach through into `metrik.core`.
+
+That rule is enforced in CI by the `sdk-dogfooding` contract in
+[`.importlinter`](../../.importlinter), from Phase 2 — seven phases before the SDK is
+nominally "delivered". It is how the SDK gets to be real instead of aspirational.
+
+See [`sdk-contracts.md`](../../docs/planning/sdk-contracts.md) for the full specification.
+
+## Status
+
+Phase 2. Of the ten contracts in the spec, `ModelLoader` and `Producer` exist because the
+Explorer needs them. The rest arrive with the modules that implement them; adding a contract
+before there is an implementation to check it against is how SDKs end up with methods nobody
+can call.

metrik_sdk-0.1.0/README.md

@@ -0,0 +1,18 @@
+# metrik-sdk
+
+The public contracts. Every first-party module is written against this package and nothing
+else — if a built-in producer needs something the SDK does not expose, that is a **bug in the
+SDK**, and the fix is to expose it publicly rather than to reach through into `metrik.core`.
+
+That rule is enforced in CI by the `sdk-dogfooding` contract in
+[`.importlinter`](../../.importlinter), from Phase 2 — seven phases before the SDK is
+nominally "delivered". It is how the SDK gets to be real instead of aspirational.
+
+See [`sdk-contracts.md`](../../docs/planning/sdk-contracts.md) for the full specification.
+
+## Status
+
+Phase 2. Of the ten contracts in the spec, `ModelLoader` and `Producer` exist because the
+Explorer needs them. The rest arrive with the modules that implement them; adding a contract
+before there is an implementation to check it against is how SDKs end up with methods nobody
+can call.

metrik_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "metrik-sdk"
+version = "0.1.0"
+description = "Metrik plugin SDK — the public contracts every producer and consumer is written against."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "Apache-2.0"
+authors = [{ name = "The Metrik Authors" }]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Developers",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+# Separately versioned from metrik-core on purpose (sdk-contracts.md §7): a plugin author
+# pins the SDK, not the engine. NO torch here either -- implementing an interface must not
+# cost a multi-GB dependency.
+dependencies = [
+    "metrik-core==0.1.0",
+    "pydantic>=2.7",
+]
+
+[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-core = { workspace = true }
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/metrik"]

metrik_sdk-0.1.0/src/metrik/sdk/__init__.py

@@ -0,0 +1,225 @@
+"""The Metrik plugin SDK — the only Metrik package a producer or consumer imports.
+
+Everything a module needs is re-exported here, including the parts that originate in
+``metrik.core``. That is the point: the `sdk-dogfooding` contract in ``.importlinter`` forbids
+first-party modules from importing ``metrik.core`` at all, so anything missing from this
+namespace is a **bug in the SDK** and gets fixed by exporting it, never by reaching through.
+
+Because the built-in Explorer is written against this and nothing else, the SDK is exercised
+from Phase 2 rather than being designed in the abstract and discovered to be wrong in Phase 9.
+"""
+
+from __future__ import annotations
+
+from metrik.core.artifacts import (
+    Artifact,
+    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,
+    MetrikError,
+    UnsupportedError,
+    UserError,
+    ValidationError,
+)
+from metrik.core.hashing import (
+    Digest,
+    HashAlgo,
+    canonical_bytes,
+    content_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.plugins import CONTRACT_GROUPS, PluginManifest
+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,
+)
+from metrik.sdk.contracts import (
+    Emission,
+    ModelLoader,
+    Params,
+    Producer,
+    ProducerInfo,
+    Spine,
+)
+from metrik.sdk.runner import LocalSpine, emit
+
+#: The SDK's own version, which is what a plugin declares compatibility against
+#: (``sdk-contracts.md`` §7). Deliberately not tied to ``metrik-core``'s version: the engine
+#: may move without the contract moving, and a plugin author pins the contract.
+API_VERSION = "1.0.0"
+
+
+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-sdk")
+
+__all__ = [
+    "API_VERSION",
+    "APPROVED_COLOR_SCHEMES",
+    "CONTRACT_GROUPS",
+    "IR_VERSION",
+    "MAX_INLINE_POINTS",
+    "VIZ_SPEC_VERSION",
+    "A11yBlock",
+    "Artifact",
+    "AttentionKind",
+    "BackendError",
+    "BaselineComparison",
+    "BenchResult",
+    "BlobRef",
+    "Block",
+    "CancelledError",
+    "ChannelType",
+    "ContaminationCheck",
+    "CostRecord",
+    "DeterminismClass",
+    "Digest",
+    "Downsample",
+    "Edge",
+    "Emission",
+    "EncodingDef",
+    "Envelope",
+    "ExtractionInfo",
+    "ExtractionMethod",
+    "FailureKind",
+    "Fallbacks",
+    "FfnKind",
+    "Fidelity",
+    "GenerationSpec",
+    "HarnessName",
+    "HarnessRef",
+    "HashAlgo",
+    "InputRef",
+    "InsufficientResourcesError",
+    "Interaction",
+    "InteractionKind",
+    "Isolation",
+    "LocalSpine",
+    "Metric",
+    "MetrikError",
+    "MoEInfo",
+    "ModelGraph",
+    "ModelLoader",
+    "Node",
+    "NodeKind",
+    "NormKind",
+    "Omission",
+    "Params",
+    "PartialInfo",
+    "PluginManifest",
+    "PositionKind",
+    "Producer",
+    "ProducerInfo",
+    "ProducerRef",
+    "Provenance",
+    "ProvenanceBlock",
+    "ReasonCode",
+    "RenderHints",
+    "RoleTag",
+    "RopeInfo",
+    "SandboxAttestation",
+    "SandboxLimits",
+    "ScaleDef",
+    "Spine",
+    "TableSpec",
+    "TaskRef",
+    "TensorDecl",
+    "TensorKind",
+    "Topology",
+    "TransformKind",
+    "TransformStep",
+    "UnsupportedError",
+    "UserError",
+    "ValidationError",
+    "ViewKind",
+    "VizData",
+    "VizSpec",
+    "__version__",
+    "canonical_bytes",
+    "content_hash",
+    "emit",
+    "hash_bytes",
+    "hash_stream",
+    "op_node_id",
+]

metrik_sdk-0.1.0/src/metrik/sdk/contracts.py

@@ -0,0 +1,139 @@
+"""The producer contract and the spine handle.
+
+``sdk-contracts.md`` §4 and §5. Two rules shape everything here:
+
+**Parameters are typed, always.** ``derivation_hash`` -- the cache key -- is computed over the
+parameter object, so a producer accepting ``**kwargs`` cannot be cached correctly: two callers
+passing logically identical arguments would miss each other's cache, and a parameter that
+silently changes behaviour would produce a false cache *hit*.
+
+**Producers do not write.** A producer returns an :class:`Emission`; the spine builds the
+envelope and stores it. A producer that could write would be a producer that could store an
+artifact with no lineage, and then the graph is a suggestion again.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any, BinaryIO, Protocol, runtime_checkable
+
+from pydantic import BaseModel, ConfigDict
+
+from metrik.core.artifacts import Artifact, BlobRef, DeterminismClass, PartialInfo
+from metrik.core.hashing import Digest
+
+__all__ = [
+    "Emission",
+    "ModelLoader",
+    "Params",
+    "Producer",
+    "ProducerInfo",
+    "Spine",
+]
+
+
+class Params(BaseModel):
+    """Base for a producer's declared parameters.
+
+    Frozen and ``extra="forbid"`` so the object has one canonical form. An unknown key must be
+    an error rather than an ignored field: silently dropping ``n_sample`` (for ``n_samples``)
+    would produce a *valid* cache key for the wrong computation, and the result would look
+    correct forever.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+
+class ProducerInfo(BaseModel):
+    """Identity of a producer, as it will appear in every artifact it emits."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    name: str
+    version: str
+    #: SDK version this producer was written against. The registry refuses to load a plugin
+    #: whose declared range excludes the running version (``sdk-contracts.md`` §7).
+    api_version: str
+    #: "builtin" for in-tree modules, "plugin" for third-party. Recorded so that a traceback
+    #: from someone else's probe is never rendered as a Metrik bug.
+    kind: str = "plugin"
+
+
+class Emission(BaseModel):
+    """What a producer returns: a payload and a claim about it.
+
+    Note what is *absent*: no hashes, no timestamps, no envelope, no path. The producer states
+    what it computed and what it read; the spine decides how that is identified and stored.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    artifact_type: str
+    schema_version: int
+    payload: dict[str, Any]
+    determinism: DeterminismClass
+    #: Roles mapped to the ``content_hash`` of each input actually used. Checked against what
+    #: the spine observed the producer resolve -- under-declaring is detectable, not merely
+    #: discouraged (``artifacts.md`` §2.2).
+    inputs: Mapping[str, Digest] = {}
+    #: Present when the producer finished with gaps. A field it could not determine is null
+    #: *and* named here -- never 0, never interpolated (``artifacts.md`` §2.3).
+    partial: PartialInfo | None = None
+    #: Required whenever ``determinism`` is not ``DETERMINISTIC``.
+    env: dict[str, object] | None = None
+
+
+@runtime_checkable
+class Spine(Protocol):
+    """A producer's entire connection to the platform.
+
+    Producers do not open the store, do not touch the database, and do not import each other.
+    ``require()`` is how one producer gets another's output: it resolves cache-or-compute
+    through the spine, which is what keeps the DAG acyclic and every intermediate reusable
+    (``plan.md`` §3.4).
+    """
+
+    def get(self, digest: Digest) -> Artifact: ...
+
+    def open_blob(self, ref: BlobRef) -> BinaryIO: ...
+
+    def put_blob(self, data: BinaryIO | bytes, *, media_type: str) -> BlobRef: ...
+
+    def scratch_dir(self) -> Path: ...
+
+    def progress(self, fraction: float, message: str = "") -> None: ...
+
+    def check_cancelled(self) -> None: ...
+
+    def log(self, level: str, message: str, **fields: object) -> None: ...
+
+
+@runtime_checkable
+class Producer(Protocol):
+    """Anything that reads artifacts and emits one.
+
+    The base of every contract in ``sdk-contracts.md`` §8. Specific contracts narrow what goes
+    in and what comes out; the shape is always the same.
+    """
+
+    info: ProducerInfo
+
+    def produce(self, spine: Spine, params: Params) -> Emission: ...
+
+
+@runtime_checkable
+class ModelLoader(Protocol):
+    """URI -> ``ModelFingerprint``. ``sdk-contracts.md`` §8, contract 1.
+
+    A loader is the only component permitted to touch model files on disk, which is why it is
+    also where ``trust_remote_code`` is decided and recorded.
+    """
+
+    info: ProducerInfo
+
+    def can_load(self, uri: str) -> bool:
+        """Cheap check. Must not read the model, must not hit the network."""
+        ...
+
+    def load(self, spine: Spine, uri: str, params: Params) -> Emission: ...

metrik_sdk-0.1.0/src/metrik/sdk/runner.py

@@ -0,0 +1,158 @@
+"""Running a producer, and writing what it returns.
+
+This is the half of ``sdk-contracts.md`` §5 that makes lineage a guarantee: the spine handed
+to a producer *observes every resolution it performs*, and the write compares that observation
+against what the producer declared. A producer cannot forget to record lineage and cannot
+under-declare it, because the check does not depend on the producer's cooperation.
+"""
+
+from __future__ import annotations
+
+import tempfile
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any, BinaryIO
+
+from metrik.core.artifacts import Artifact, BlobRef, InputRef, ProducerRef, build_artifact
+from metrik.core.errors import LineageError
+from metrik.core.hashing import Digest
+from metrik.core.store import ArtifactStore
+from metrik.sdk.contracts import Emission, Params, ProducerInfo
+
+__all__ = ["LocalSpine", "emit"]
+
+
+class LocalSpine:
+    """In-process spine over a local store.
+
+    The direct, single-process implementation. A remote spine speaking to ``metrikd`` arrives
+    in Phase 10 and satisfies the same protocol, which is the point of the protocol.
+    """
+
+    def __init__(self, store: ArtifactStore, *, scratch: Path | None = None) -> None:
+        self._store = store
+        self._scratch = scratch
+        #: Every artifact this producer resolved, in resolution order. The producer cannot see
+        #: or clear this, which is precisely what makes it evidence rather than a self-report.
+        self._resolved: dict[Digest, Artifact] = {}
+        self._cancelled = False
+
+    # -- Spine protocol ------------------------------------------------------------------
+
+    def get(self, digest: Digest) -> Artifact:
+        artifact = self._store.get(digest)
+        self._resolved[artifact.envelope.content_hash] = artifact
+        return artifact
+
+    def open_blob(self, ref: BlobRef) -> BinaryIO:
+        return self._store.blobs.open(ref.digest)
+
+    def put_blob(self, data: BinaryIO | bytes, *, media_type: str) -> BlobRef:
+        if isinstance(data, bytes):
+            digest = self._store.blobs.put_bytes(data)
+            size = len(data)
+        else:
+            digest = self._store.blobs.put_stream(data)
+            size = self._store.blobs.path_of(digest).stat().st_size
+        return BlobRef(digest=digest, size_bytes=size, media_type=media_type)
+
+    def scratch_dir(self) -> Path:
+        if self._scratch is None:
+            self._scratch = Path(tempfile.mkdtemp(prefix="metrik-scratch-"))
+        self._scratch.mkdir(parents=True, exist_ok=True)
+        return self._scratch
+
+    def progress(self, fraction: float, message: str = "") -> None:
+        """Best-effort and unversioned. Nothing downstream may depend on it."""
+
+    def check_cancelled(self) -> None:
+        if self._cancelled:
+            from metrik.core.errors import CancelledError
+
+            raise CancelledError("run cancelled")
+
+    def log(self, level: str, message: str, **fields: object) -> None:
+        """Deliberately inert until the run registry exists (Phase 2 remainder)."""
+
+    # -- Writing -------------------------------------------------------------------------
+
+    @property
+    def resolved(self) -> Mapping[Digest, Artifact]:
+        return dict(self._resolved)
+
+    def commit(
+        self, emission: Emission, info: ProducerInfo, params: Params | None = None
+    ) -> Artifact:
+        """Turn an :class:`Emission` into a stored artifact.
+
+        Raises:
+            LineageError: if the producer declared an input it never resolved, or resolved one
+                it did not declare. Both directions matter. Under-declaring hides a dependency,
+                which is the failure ``artifacts.md`` §2.2 exists to prevent. Over-declaring is
+                subtler and just as bad: it claims a derivation that did not happen, so a user
+                tracing the number is told it depends on something it does not.
+        """
+        declared = dict(emission.inputs)
+        self._check_declaration_matches_reality(declared, emission.artifact_type)
+
+        inputs = tuple(
+            InputRef(
+                role=role,
+                content_hash=digest,
+                artifact_type=self._resolved[digest].envelope.artifact_type,
+            )
+            for role, digest in sorted(declared.items())
+        )
+        artifact = build_artifact(
+            artifact_type=emission.artifact_type,
+            schema_version=emission.schema_version,
+            payload=emission.payload,
+            determinism=emission.determinism,
+            produced_by=ProducerRef(
+                kind=info.kind, name=info.name, version=info.version, api_version=info.api_version
+            ),
+            inputs=inputs,
+            params=params.model_dump() if params is not None else None,
+            env=emission.env,
+            partial=emission.partial,
+        )
+        self._store.put(artifact)
+        return artifact
+
+    def _check_declaration_matches_reality(
+        self, declared: dict[str, Digest], artifact_type: str
+    ) -> None:
+        declared_hashes = set(declared.values())
+        observed = set(self._resolved)
+
+        missing = declared_hashes - observed
+        if missing:
+            roles = sorted(r for r, d in declared.items() if d in missing)
+            raise LineageError(
+                f"{artifact_type} declares input(s) {roles} that were never resolved through "
+                f"the spine",
+                remediation="Resolve inputs with spine.get(), or drop them from the declaration.",
+            )
+
+        undeclared = observed - declared_hashes
+        if undeclared:
+            types = sorted(self._resolved[d].envelope.artifact_type for d in undeclared)
+            raise LineageError(
+                f"{artifact_type} read {types} through the spine but did not declare them as "
+                f"inputs",
+                remediation=(
+                    "Add them to Emission.inputs. Lineage completeness is checked, not trusted "
+                    "(artifacts.md sec. 2.2)."
+                ),
+            )
+
+
+def emit(
+    store: ArtifactStore,
+    info: ProducerInfo,
+    build: Any,
+    params: Params | None = None,
+) -> Artifact:
+    """Run ``build(spine)`` and commit whatever it emits. A convenience for callers and tests."""
+    spine = LocalSpine(store)
+    return spine.commit(build(spine), info, params)