zeromodel-artifacts 1.1.0__tar.gz

zeromodel_artifacts-1.1.0/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.4
+Name: zeromodel-artifacts
+Version: 1.1.0
+Summary: ZeroModel canonical artifact reference, resolution, and content-addressed storage
+Author-email: Ernan Hughes <ernanhughes@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/ernanhughes/zeromodel
+Project-URL: Repository, https://github.com/ernanhughes/zeromodel
+Project-URL: Documentation, https://ernanhughes.github.io/zeromodel/
+Keywords: visual-policy-map,vpm,artifact-identity,content-addressed-storage
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.23
+Requires-Dist: zeromodel==1.1.0
+
+# zeromodel-artifacts
+
+Canonical artifact reference, resolution, and content-addressed storage for
+the ZeroModel workspace.
+
+This package defines the stable, cross-package `ArtifactRef` identity and the
+`ArtifactResolver` / `ArtifactStore` protocols other packages (such as
+`zeromodel-trust` and `zeromodel-navigation`) use to persist and resolve their
+own artifacts, without each package inventing its own storage layer.
+
+It reuses `zeromodel.core`'s existing canonicalization and digest primitives
+(`canonical_json_bytes`, `sha256_digest`) rather than redefining them.
+
+## Report compilation and the compiled-report aggregate
+
+On top of the storage kernel, this package also compiles typed external
+reports into deterministic, source-bound VPM artifacts (`ReportAdapter`,
+`AdaptedReportDTO`, `compile_report()`) and resolves the complete result as
+one coherent aggregate:
+
+```text
+AdaptedReportDTO (persisted, resolvable)
+ReportAdapterContractDTO (persisted, resolvable)
+    ↓
+CompiledReportArtifactDTO (aggregate root)
+    ├── adapted_report_ref    -> AdaptedReportDTO
+    ├── adapter_contract_ref  -> ReportAdapterContractDTO
+    ├── score_table_ref       -> ScoreTable
+    ├── layout_recipe_ref     -> LayoutRecipe
+    └── vpm_artifact_ref      -> VPMArtifact
+```
+
+`load_compiled_report_aggregate()` resolves all five referenced artifacts
+and runs `validate_compiled_report_aggregate()`, which proves the
+collection is semantically closed - not merely that each object's own
+digest is valid, and not merely that the resolved objects agree with each
+other. A compiled report can reference a `ScoreTable` from one report, a
+`LayoutRecipe` from another, and a `VPMArtifact` from a third, each
+individually digest-valid; a VPM can even embed the *correct* `ScoreTable`
+and `LayoutRecipe` while its normalized pixels or row/column ordering are
+fabricated. Aggregate validation proves: every resolved object's
+store-level digest actually matches the ref the compiled report declares
+for it (not merely assumed from how the caller obtained the object); the
+resolved adapter contract's declared fields agree with what the compiled
+and adapted reports copied from it; the VPM's `normalized_values`/
+`row_order`/`column_order`/`provenance` are exactly what `build_vpm()`
+would deterministically reproduce from the resolved `ScoreTable`/
+`LayoutRecipe`; and every VPM view coordinate, raw value, and source
+binding is exactly what the compiled report's cell bindings claim.
+`build_compiled_report_closure_receipt()` produces an auditable,
+content-addressed receipt only after every check passes - never a partial
+result.
+
+Compatibility between two compiled reports requires three independent
+identities to agree: `compatibility_id` (a human label), and two content
+digests: `compatibility_schema_id` (dimension ids, order, score semantics,
+and value/target ranges) and `report_semantics_id` (report kind, subject
+kind, dimension namespace, and duplicate-value policy - the layer that
+distinguishes, for example, a report over sentences from a structurally
+identical report over claims).
+
+`load_compiled_report_vpm(*, ref, resolver)` is the one safe public path
+to a compiled report's rendered `VPMArtifact` - it is a thin wrapper
+around `load_compiled_report_aggregate(...).vpm_artifact`, so it always
+runs the full closure (including the deterministic-reconstruction check
+above) before returning anything. `core_artifact_persistence.load_vpm_artifact`
+remains available as an explicitly low-level Core loader (digest-only, no
+compiled-report context to close an aggregate against) for callers who
+genuinely have no compiled report to check against - it is not itself a
+safe rendering path for a compiled report's VPM.
+
+A reference is the pair `(artifact_kind, artifact_id)`, not the digest
+alone: `CompiledReportArtifactDTO` rejects a nested ref whose declared
+kind doesn't match its expected artifact kind even when the `artifact_id`
+genuinely matches stored content, and `validate_compiled_report_aggregate`
+re-asserts the same check as defense in depth.
+`CompiledReportClosureReceiptDTO` similarly cannot be constructed with an
+incomplete `checks` tuple or non-empty `failure_codes`, even with a
+`receipt_id` that correctly hashes that content - the type's promise that
+"every check passed" is enforced structurally, not left to its one
+legitimate builder.
+
+**Claims boundary:** ZeroModel can persist and reload a complete adapted
+report, its governing adapter contract, and its compiled `ScoreTable`,
+`LayoutRecipe`, and `VPMArtifact` as one content-addressed aggregate, and
+verify that every subject, dimension, value, coordinate, source binding,
+declared contract semantic, and rendered pixel agrees across all five
+representations - including that the VPM's visible pixels were actually
+generated by its own embedded recipe, not merely digest-consistent with
+themselves. This does not include Trust-signed compiled reports (Trust
+integration is a call-site composition, not implemented here),
+cross-schema conversion, or automatic report repair.

zeromodel_artifacts-1.1.0/README.md

@@ -0,0 +1,92 @@
+# zeromodel-artifacts
+
+Canonical artifact reference, resolution, and content-addressed storage for
+the ZeroModel workspace.
+
+This package defines the stable, cross-package `ArtifactRef` identity and the
+`ArtifactResolver` / `ArtifactStore` protocols other packages (such as
+`zeromodel-trust` and `zeromodel-navigation`) use to persist and resolve their
+own artifacts, without each package inventing its own storage layer.
+
+It reuses `zeromodel.core`'s existing canonicalization and digest primitives
+(`canonical_json_bytes`, `sha256_digest`) rather than redefining them.
+
+## Report compilation and the compiled-report aggregate
+
+On top of the storage kernel, this package also compiles typed external
+reports into deterministic, source-bound VPM artifacts (`ReportAdapter`,
+`AdaptedReportDTO`, `compile_report()`) and resolves the complete result as
+one coherent aggregate:
+
+```text
+AdaptedReportDTO (persisted, resolvable)
+ReportAdapterContractDTO (persisted, resolvable)
+    ↓
+CompiledReportArtifactDTO (aggregate root)
+    ├── adapted_report_ref    -> AdaptedReportDTO
+    ├── adapter_contract_ref  -> ReportAdapterContractDTO
+    ├── score_table_ref       -> ScoreTable
+    ├── layout_recipe_ref     -> LayoutRecipe
+    └── vpm_artifact_ref      -> VPMArtifact
+```
+
+`load_compiled_report_aggregate()` resolves all five referenced artifacts
+and runs `validate_compiled_report_aggregate()`, which proves the
+collection is semantically closed - not merely that each object's own
+digest is valid, and not merely that the resolved objects agree with each
+other. A compiled report can reference a `ScoreTable` from one report, a
+`LayoutRecipe` from another, and a `VPMArtifact` from a third, each
+individually digest-valid; a VPM can even embed the *correct* `ScoreTable`
+and `LayoutRecipe` while its normalized pixels or row/column ordering are
+fabricated. Aggregate validation proves: every resolved object's
+store-level digest actually matches the ref the compiled report declares
+for it (not merely assumed from how the caller obtained the object); the
+resolved adapter contract's declared fields agree with what the compiled
+and adapted reports copied from it; the VPM's `normalized_values`/
+`row_order`/`column_order`/`provenance` are exactly what `build_vpm()`
+would deterministically reproduce from the resolved `ScoreTable`/
+`LayoutRecipe`; and every VPM view coordinate, raw value, and source
+binding is exactly what the compiled report's cell bindings claim.
+`build_compiled_report_closure_receipt()` produces an auditable,
+content-addressed receipt only after every check passes - never a partial
+result.
+
+Compatibility between two compiled reports requires three independent
+identities to agree: `compatibility_id` (a human label), and two content
+digests: `compatibility_schema_id` (dimension ids, order, score semantics,
+and value/target ranges) and `report_semantics_id` (report kind, subject
+kind, dimension namespace, and duplicate-value policy - the layer that
+distinguishes, for example, a report over sentences from a structurally
+identical report over claims).
+
+`load_compiled_report_vpm(*, ref, resolver)` is the one safe public path
+to a compiled report's rendered `VPMArtifact` - it is a thin wrapper
+around `load_compiled_report_aggregate(...).vpm_artifact`, so it always
+runs the full closure (including the deterministic-reconstruction check
+above) before returning anything. `core_artifact_persistence.load_vpm_artifact`
+remains available as an explicitly low-level Core loader (digest-only, no
+compiled-report context to close an aggregate against) for callers who
+genuinely have no compiled report to check against - it is not itself a
+safe rendering path for a compiled report's VPM.
+
+A reference is the pair `(artifact_kind, artifact_id)`, not the digest
+alone: `CompiledReportArtifactDTO` rejects a nested ref whose declared
+kind doesn't match its expected artifact kind even when the `artifact_id`
+genuinely matches stored content, and `validate_compiled_report_aggregate`
+re-asserts the same check as defense in depth.
+`CompiledReportClosureReceiptDTO` similarly cannot be constructed with an
+incomplete `checks` tuple or non-empty `failure_codes`, even with a
+`receipt_id` that correctly hashes that content - the type's promise that
+"every check passed" is enforced structurally, not left to its one
+legitimate builder.
+
+**Claims boundary:** ZeroModel can persist and reload a complete adapted
+report, its governing adapter contract, and its compiled `ScoreTable`,
+`LayoutRecipe`, and `VPMArtifact` as one content-addressed aggregate, and
+verify that every subject, dimension, value, coordinate, source binding,
+declared contract semantic, and rendered pixel agrees across all five
+representations - including that the VPM's visible pixels were actually
+generated by its own embedded recipe, not merely digest-consistent with
+themselves. This does not include Trust-signed compiled reports (Trust
+integration is a call-site composition, not implemented here),
+cross-schema conversion, or automatic report repair.

zeromodel_artifacts-1.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "zeromodel-artifacts"
+version = "1.1.0"
+description = "ZeroModel canonical artifact reference, resolution, and content-addressed storage"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+authors = [{name = "Ernan Hughes", email = "ernanhughes@gmail.com"}]
+keywords = [
+    "visual-policy-map",
+    "vpm",
+    "artifact-identity",
+    "content-addressed-storage",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "numpy>=1.23",
+    "zeromodel==1.1.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/ernanhughes/zeromodel"
+Repository = "https://github.com/ernanhughes/zeromodel"
+Documentation = "https://ernanhughes.github.io/zeromodel/"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["zeromodel.artifacts*"]

zeromodel_artifacts-1.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

zeromodel_artifacts-1.1.0/src/zeromodel/artifacts/__init__.py

@@ -0,0 +1,120 @@
+from __future__ import annotations
+
+from zeromodel.artifacts.adapted_report_persistence import (
+    ADAPTED_REPORT_ARTIFACT_KIND,
+    load_adapted_report,
+    store_adapted_report,
+)
+from zeromodel.artifacts.adapter import ReportAdapter
+from zeromodel.artifacts.aggregate import (
+    CompiledReportClosureReceiptDTO,
+    ResolvedCompiledReportAggregateDTO,
+    build_compiled_report_closure_receipt,
+    load_compiled_report_aggregate,
+    load_compiled_report_vpm,
+    validate_compiled_report_aggregate,
+)
+from zeromodel.artifacts.canonicalization import canonical_json_bytes, sha256_digest
+from zeromodel.artifacts.compatibility_schema import (
+    compute_compatibility_schema_id,
+    compute_report_semantics_id,
+)
+from zeromodel.artifacts.compiled_artifact import (
+    CellBindingDTO,
+    CompiledReportArtifactDTO,
+    CoreArtifactRefs,
+)
+from zeromodel.artifacts.core_artifact_persistence import (
+    LAYOUT_RECIPE_ARTIFACT_KIND,
+    SCORE_TABLE_ARTIFACT_KIND,
+    VPM_ARTIFACT_ARTIFACT_KIND,
+    load_layout_recipe,
+    load_score_table,
+    load_vpm_artifact,
+    store_layout_recipe,
+    store_score_table,
+    store_vpm_artifact,
+)
+from zeromodel.artifacts.ref import ARTIFACT_REF_VERSION, ArtifactRef, is_sha256_digest
+from zeromodel.artifacts.report_adapter_contract_persistence import (
+    REPORT_ADAPTER_CONTRACT_ARTIFACT_KIND,
+    load_report_adapter_contract,
+    store_report_adapter_contract,
+)
+from zeromodel.artifacts.report_compiler import compile_report
+from zeromodel.artifacts.report_dto import (
+    AdaptedDimensionDTO,
+    AdaptedReportDTO,
+    AdaptedSubjectDTO,
+    AdaptedValueDTO,
+    ReportAdapterContractDTO,
+    ReportFindingRefDTO,
+    SourceBindingDTO,
+)
+from zeromodel.artifacts.report_errors import (
+    ReportAdaptationError,
+    ReportCompilationError,
+)
+from zeromodel.artifacts.report_loading import load_compiled_report_artifact
+from zeromodel.artifacts.score_semantics import ScoreSemantics
+from zeromodel.artifacts.store import (
+    ArtifactIntegrityError,
+    ArtifactManifestConflictError,
+    ArtifactNotFoundError,
+    ArtifactResolver,
+    ArtifactStore,
+    InMemoryArtifactStore,
+)
+
+__all__ = [
+    "ADAPTED_REPORT_ARTIFACT_KIND",
+    "ARTIFACT_REF_VERSION",
+    "LAYOUT_RECIPE_ARTIFACT_KIND",
+    "REPORT_ADAPTER_CONTRACT_ARTIFACT_KIND",
+    "SCORE_TABLE_ARTIFACT_KIND",
+    "VPM_ARTIFACT_ARTIFACT_KIND",
+    "AdaptedDimensionDTO",
+    "AdaptedReportDTO",
+    "AdaptedSubjectDTO",
+    "AdaptedValueDTO",
+    "ArtifactIntegrityError",
+    "ArtifactManifestConflictError",
+    "ArtifactNotFoundError",
+    "ArtifactRef",
+    "ArtifactResolver",
+    "ArtifactStore",
+    "CellBindingDTO",
+    "CompiledReportArtifactDTO",
+    "CompiledReportClosureReceiptDTO",
+    "CoreArtifactRefs",
+    "InMemoryArtifactStore",
+    "ReportAdaptationError",
+    "ReportAdapter",
+    "ReportAdapterContractDTO",
+    "ReportCompilationError",
+    "ReportFindingRefDTO",
+    "ResolvedCompiledReportAggregateDTO",
+    "ScoreSemantics",
+    "SourceBindingDTO",
+    "build_compiled_report_closure_receipt",
+    "canonical_json_bytes",
+    "compile_report",
+    "compute_compatibility_schema_id",
+    "compute_report_semantics_id",
+    "is_sha256_digest",
+    "load_adapted_report",
+    "load_compiled_report_aggregate",
+    "load_compiled_report_artifact",
+    "load_compiled_report_vpm",
+    "load_layout_recipe",
+    "load_report_adapter_contract",
+    "load_score_table",
+    "load_vpm_artifact",
+    "sha256_digest",
+    "store_adapted_report",
+    "store_layout_recipe",
+    "store_report_adapter_contract",
+    "store_score_table",
+    "store_vpm_artifact",
+    "validate_compiled_report_aggregate",
+]

zeromodel_artifacts-1.1.0/src/zeromodel/artifacts/adapted_report_persistence.py

@@ -0,0 +1,91 @@
+"""Persist and reload `AdaptedReportDTO` as a first-class artifact.
+
+Before this module, `AdaptedReportDTO` only ever existed as a discarded
+local Python object inside `compile_report()`: the compiled report named it
+by digest (`adapted_report_id`) but nothing made that digest resolvable
+after the process exited. Raw values, per-value confidence, per-value
+importance, source bindings, and parent-report lineage - none of which the
+VPM matrix preserves completely - were unrecoverable once compilation
+finished. This module closes that gap using the same decode-and-verify
+pattern as `core_artifact_persistence.py`: resolve canonical bytes,
+recompute the digest, require it to equal the requested ref's
+`artifact_id`, decode, and reconstruct via `AdaptedReportDTO.__post_init__`
+- never trusting a store's manifest as authoritative.
+
+Canonical format: the stored payload is exactly
+`adapted_report_signing_payload(adapted_report)` - the same payload
+`AdaptedReportDTO.adapted_report_id` is computed over, with the
+self-referential id field excluded. Because `ArtifactStore.put()` computes
+`ref.artifact_id` as `sha256_digest(canonical_bytes)` over that same
+payload, `ref.artifact_id == adapted_report.adapted_report_id` always
+holds - the artifact-store identity and the DTO's own content identity are
+the same digest, not two independent layers that happen to agree.
+"""
+
+from __future__ import annotations
+
+import json
+
+from zeromodel.artifacts.canonicalization import canonical_json_bytes, sha256_digest
+from zeromodel.artifacts.ref import ArtifactRef
+from zeromodel.artifacts.report_decode import (
+    decode_attributes,
+    decode_dimension,
+    decode_subject,
+    decode_value,
+)
+from zeromodel.artifacts.report_dto import (
+    AdaptedReportDTO,
+    adapted_report_signing_payload,
+)
+from zeromodel.artifacts.report_errors import ReportCompilationError
+from zeromodel.artifacts.store import ArtifactResolver, ArtifactStore
+
+ADAPTED_REPORT_ARTIFACT_KIND = "zeromodel.artifacts.adapted-report/v1"
+
+
+def store_adapted_report(
+    adapted_report: AdaptedReportDTO, *, store: ArtifactStore
+) -> ArtifactRef:
+    canonical_bytes = canonical_json_bytes(
+        adapted_report_signing_payload(adapted_report)
+    )
+    ref = store.put(ADAPTED_REPORT_ARTIFACT_KIND, canonical_bytes, manifest=None)
+    if ref.artifact_id != adapted_report.adapted_report_id:
+        raise ReportCompilationError(
+            "stored adapted-report digest does not match adapted_report_id "
+            f"(stored={ref.artifact_id}, adapted_report_id={adapted_report.adapted_report_id})"
+        )
+    return ref
+
+
+def load_adapted_report(
+    ref: ArtifactRef, *, resolver: ArtifactResolver
+) -> AdaptedReportDTO:
+    if ref.artifact_kind != ADAPTED_REPORT_ARTIFACT_KIND:
+        raise ReportCompilationError(
+            f"load_adapted_report requires artifact_kind={ADAPTED_REPORT_ARTIFACT_KIND!r}, "
+            f"got {ref.artifact_kind!r}"
+        )
+    canonical_bytes = resolver.resolve_canonical_bytes(ref)
+    actual_digest = sha256_digest(canonical_bytes)
+    if actual_digest != ref.artifact_id:
+        raise ReportCompilationError(
+            f"resolved canonical bytes for {ref.artifact_id} do not hash to the requested id "
+            f"(got {actual_digest})"
+        )
+    payload = json.loads(canonical_bytes)
+
+    return AdaptedReportDTO(
+        adapted_report_id=ref.artifact_id,
+        report_id=payload["report_id"],
+        report_kind=payload["report_kind"],
+        adapter_contract_id=payload["adapter_contract_id"],
+        compatibility_id=payload["compatibility_id"],
+        subjects=tuple(decode_subject(item) for item in payload["subjects"]),
+        dimensions=tuple(decode_dimension(item) for item in payload["dimensions"]),
+        values=tuple(decode_value(item) for item in payload["values"]),
+        parent_report_ids=tuple(payload["parent_report_ids"]),
+        attributes=decode_attributes(payload["attributes"]),
+        spec_version=payload["spec_version"],
+    )

zeromodel_artifacts-1.1.0/src/zeromodel/artifacts/adapter.py

@@ -0,0 +1,30 @@
+"""The adapter protocol - the ingress boundary for domain reports.
+
+Concrete adapters live in the external application (e.g.
+`writer.integrations.zeromodel.AIArtifactReportAdapter`), never in this
+package. An adapter must not write directly to an `ArtifactStore`,
+construct rendered images, or calculate artifact identity itself - it only
+translates one typed domain report into a neutral `AdaptedReportDTO`;
+`compile_report` (see `report_compiler.py`) owns validation and identity.
+"""
+
+from __future__ import annotations
+
+from typing import Generic, Protocol, TypeVar, runtime_checkable
+
+from zeromodel.artifacts.report_dto import AdaptedReportDTO, ReportAdapterContractDTO
+
+ReportT = TypeVar("ReportT", contravariant=True)
+
+
+@runtime_checkable
+class ReportAdapter(Protocol, Generic[ReportT]):
+    """Domain-owned translation from one typed report into neutral ZeroModel form."""
+
+    def contract(self) -> ReportAdapterContractDTO:
+        """Return the stable contract governing this adapter's translation."""
+        ...
+
+    def adapt(self, report: ReportT) -> AdaptedReportDTO:
+        """Convert one domain report into the neutral ZeroModel report form."""
+        ...