Metadata-Version: 2.4
Name: metrik-core
Version: 0.1.1
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`.
