zeromodel-observation 1.1.0__tar.gz

zeromodel_observation-1.1.0/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: zeromodel-observation
+Version: 1.1.0
+Summary: ZeroModel observation package
+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,observation-contracts,provider-protocols
+Classifier: Development Status :: 5 - Production/Stable
+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-observation
+
+`zeromodel-observation` defines provider-neutral observation contracts for
+ZeroModel. It is the boundary between raw observations and deterministic policy
+addressing, exposed through `zeromodel.observation`.
+
+The package depends on the validated core distribution, `zeromodel==1.0.13`, and
+uses NumPy for immutable image-array contracts. It does not implement perception,
+visual recognition, video policy behavior, model inference, or persistence.
+
+## Install
+
+```powershell
+python -m pip install zeromodel==1.0.13 zeromodel-observation==1.0.13
+```
+
+## Provider-Neutral Contracts
+
+`ImageObservation` stores an owned, read-only `uint8` image array plus source,
+timestamp, and metadata. It accepts `HxW`, `HxWx3`, and `HxWx4` arrays and
+derives a deterministic raw digest from the canonical shape and bytes.
+
+`VisualAddressContract` describes what a provider promises before inference:
+provider identity, score polarity, replay semantics, representation identity,
+calibration identity, policy identity, and source scope.
+
+`VisualAddressDecision` records an accepted address or evidence-bearing
+rejection. It links the observation, representation, provider, address artifact,
+calibration artifact, and policy artifact without depending on any concrete
+vision implementation.
+
+`VisualAddressManifest` and `PrototypeBinding` bind representation rows to
+policy row IDs and link those rows to a content-addressed matrix blob. The
+manifest is an address contract artifact, not a visual reader.
+
+`DeploymentBinding` records an approved pairing of policy, address artifact,
+calibration, source scope, and optional encoder identity. It is not a
+cryptographic signature or authorization system.
+
+## Minimal Provider
+
+```python
+import numpy as np
+
+from zeromodel.observation import (
+    ImageObservation,
+    VisualAddressContract,
+    VisualAddressDecision,
+    VisualAddressProvider,
+)
+
+
+class TableProvider:
+    def contract(self) -> VisualAddressContract:
+        return VisualAddressContract(
+            provider_kind="table-provider",
+            provider_version="v1",
+            score_semantics="distance",
+            observation_spec_digest="obs-spec",
+            representation_spec_digest="rep-spec",
+            address_artifact_id="address-1",
+            calibration_artifact_id="calibration-1",
+            policy_artifact_id="policy-1",
+            source_scope="fixture:camera",
+            replay_contract="exact_decision",
+        )
+
+    def read(self, observation: ImageObservation) -> VisualAddressDecision:
+        return VisualAddressDecision(
+            accepted=True,
+            reason="accepted",
+            observation_digest=observation.raw_digest,
+            representation_digest="sha256:representation",
+            provider_kind="table-provider",
+            provider_version="v1",
+            score_semantics="distance",
+            address_artifact_id="address-1",
+            calibration_artifact_id="calibration-1",
+            policy_artifact_id="policy-1",
+            nearest_row_id="policy-row-1",
+            nearest_score=0.0,
+            second_row_id=None,
+            second_score=None,
+            ambiguity_measure=None,
+            matched_row_id="policy-row-1",
+            exact_match=True,
+            accepted_by=("fixture",),
+        )
+
+
+provider: VisualAddressProvider = TableProvider()
+decision = provider.read(ImageObservation(np.zeros((2, 2), dtype=np.uint8)))
+```
+
+## Exclusions
+
+Concrete deterministic visual addressing belongs to `zeromodel-vision`.
+Temporal policy and video-domain behavior belong to `zeromodel-video`.
+Durable SQL persistence belongs to `zeromodel-sqlalchemy`.
+
+This package does not import or require `zeromodel-analysis`, `zeromodel-vision`,
+`zeromodel-video`, SQLAlchemy, Torch, TorchVision, Transformers, or Pillow.

zeromodel_observation-1.1.0/README.md

@@ -0,0 +1,102 @@
+# zeromodel-observation
+
+`zeromodel-observation` defines provider-neutral observation contracts for
+ZeroModel. It is the boundary between raw observations and deterministic policy
+addressing, exposed through `zeromodel.observation`.
+
+The package depends on the validated core distribution, `zeromodel==1.0.13`, and
+uses NumPy for immutable image-array contracts. It does not implement perception,
+visual recognition, video policy behavior, model inference, or persistence.
+
+## Install
+
+```powershell
+python -m pip install zeromodel==1.0.13 zeromodel-observation==1.0.13
+```
+
+## Provider-Neutral Contracts
+
+`ImageObservation` stores an owned, read-only `uint8` image array plus source,
+timestamp, and metadata. It accepts `HxW`, `HxWx3`, and `HxWx4` arrays and
+derives a deterministic raw digest from the canonical shape and bytes.
+
+`VisualAddressContract` describes what a provider promises before inference:
+provider identity, score polarity, replay semantics, representation identity,
+calibration identity, policy identity, and source scope.
+
+`VisualAddressDecision` records an accepted address or evidence-bearing
+rejection. It links the observation, representation, provider, address artifact,
+calibration artifact, and policy artifact without depending on any concrete
+vision implementation.
+
+`VisualAddressManifest` and `PrototypeBinding` bind representation rows to
+policy row IDs and link those rows to a content-addressed matrix blob. The
+manifest is an address contract artifact, not a visual reader.
+
+`DeploymentBinding` records an approved pairing of policy, address artifact,
+calibration, source scope, and optional encoder identity. It is not a
+cryptographic signature or authorization system.
+
+## Minimal Provider
+
+```python
+import numpy as np
+
+from zeromodel.observation import (
+    ImageObservation,
+    VisualAddressContract,
+    VisualAddressDecision,
+    VisualAddressProvider,
+)
+
+
+class TableProvider:
+    def contract(self) -> VisualAddressContract:
+        return VisualAddressContract(
+            provider_kind="table-provider",
+            provider_version="v1",
+            score_semantics="distance",
+            observation_spec_digest="obs-spec",
+            representation_spec_digest="rep-spec",
+            address_artifact_id="address-1",
+            calibration_artifact_id="calibration-1",
+            policy_artifact_id="policy-1",
+            source_scope="fixture:camera",
+            replay_contract="exact_decision",
+        )
+
+    def read(self, observation: ImageObservation) -> VisualAddressDecision:
+        return VisualAddressDecision(
+            accepted=True,
+            reason="accepted",
+            observation_digest=observation.raw_digest,
+            representation_digest="sha256:representation",
+            provider_kind="table-provider",
+            provider_version="v1",
+            score_semantics="distance",
+            address_artifact_id="address-1",
+            calibration_artifact_id="calibration-1",
+            policy_artifact_id="policy-1",
+            nearest_row_id="policy-row-1",
+            nearest_score=0.0,
+            second_row_id=None,
+            second_score=None,
+            ambiguity_measure=None,
+            matched_row_id="policy-row-1",
+            exact_match=True,
+            accepted_by=("fixture",),
+        )
+
+
+provider: VisualAddressProvider = TableProvider()
+decision = provider.read(ImageObservation(np.zeros((2, 2), dtype=np.uint8)))
+```
+
+## Exclusions
+
+Concrete deterministic visual addressing belongs to `zeromodel-vision`.
+Temporal policy and video-domain behavior belong to `zeromodel-video`.
+Durable SQL persistence belongs to `zeromodel-sqlalchemy`.
+
+This package does not import or require `zeromodel-analysis`, `zeromodel-vision`,
+`zeromodel-video`, SQLAlchemy, Torch, TorchVision, Transformers, or Pillow.

zeromodel_observation-1.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "zeromodel-observation"
+version = "1.1.0"
+description = "ZeroModel observation package"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+authors = [{name = "Ernan Hughes", email = "ernanhughes@gmail.com"}]
+keywords = [
+    "visual-policy-map",
+    "vpm",
+    "observation-contracts",
+    "provider-protocols",
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "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.observation*"]

zeromodel_observation-1.1.0/setup.cfg

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

zeromodel_observation-1.1.0/src/zeromodel/observation/__init__.py

@@ -0,0 +1,37 @@
+"""ZeroModel observation public API."""
+
+from __future__ import annotations
+
+from .deployment_binding import (
+    DEPLOYMENT_BINDING_VERSION,
+    DeploymentBinding,
+)
+from .visual_address import (
+    IMAGE_OBSERVATION_VERSION,
+    ImageObservation,
+    VISUAL_ADDRESS_CONTRACT_VERSION,
+    VISUAL_ADDRESS_DECISION_VERSION,
+    VISUAL_ADDRESS_MANIFEST_VERSION,
+    VisualAddressContract,
+    VisualAddressDecision,
+    VisualAddressProvider,
+)
+from .visual_address_manifest import (
+    PrototypeBinding,
+    VisualAddressManifest,
+)
+
+__all__ = [
+    "DEPLOYMENT_BINDING_VERSION",
+    "DeploymentBinding",
+    "IMAGE_OBSERVATION_VERSION",
+    "ImageObservation",
+    "PrototypeBinding",
+    "VISUAL_ADDRESS_CONTRACT_VERSION",
+    "VISUAL_ADDRESS_DECISION_VERSION",
+    "VISUAL_ADDRESS_MANIFEST_VERSION",
+    "VisualAddressContract",
+    "VisualAddressDecision",
+    "VisualAddressManifest",
+    "VisualAddressProvider",
+]

zeromodel_observation-1.1.0/src/zeromodel/observation/deployment_binding.py

@@ -0,0 +1,203 @@
+"""Approved binding between a visual address contract and a VPM policy."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import hashlib
+import json
+from typing import Any, Dict, Mapping, Optional
+
+from zeromodel.core.artifact import VPMValidationError
+from zeromodel.observation.visual_address import VisualAddressContract
+
+
+DEPLOYMENT_BINDING_VERSION = "zeromodel-deployment-binding/v1"
+_DEPLOYMENT_STATUSES = {"validated", "research"}
+
+
+def _canonical_json_bytes(value: Any) -> bytes:
+    try:
+        return json.dumps(
+            value,
+            sort_keys=True,
+            separators=(",", ":"),
+            ensure_ascii=False,
+            allow_nan=False,
+        ).encode("utf-8")
+    except (TypeError, ValueError) as exc:
+        raise VPMValidationError(
+            "deployment binding must be JSON-serializable"
+        ) from exc
+
+
+@dataclass(frozen=True)
+class DeploymentBinding:
+    """Identity-bearing approval of one perception-policy pairing.
+
+    A binding is not a cryptographic signature.  It records exactly which
+    address, calibration, encoder, policy, and source scope were approved
+    together so the runtime can reject accidental cross-pairing.
+    """
+
+    policy_artifact_id: str
+    address_artifact_id: str
+    calibration_artifact_id: str
+    source_scope: str
+    encoder_manifest_id: Optional[str] = None
+    deployment_status: str = "validated"
+    version: str = DEPLOYMENT_BINDING_VERSION
+    binding_id: str = ""
+
+    def __init__(
+        self,
+        *,
+        policy_artifact_id: str,
+        address_artifact_id: str,
+        calibration_artifact_id: str,
+        source_scope: str,
+        encoder_manifest_id: Optional[str] = None,
+        deployment_status: str = "validated",
+        version: str = DEPLOYMENT_BINDING_VERSION,
+        binding_id: Optional[str] = None,
+    ) -> None:
+        object.__setattr__(self, "policy_artifact_id", str(policy_artifact_id))
+        object.__setattr__(self, "address_artifact_id", str(address_artifact_id))
+        object.__setattr__(
+            self,
+            "calibration_artifact_id",
+            str(calibration_artifact_id),
+        )
+        object.__setattr__(self, "source_scope", str(source_scope))
+        object.__setattr__(
+            self,
+            "encoder_manifest_id",
+            None if encoder_manifest_id is None else str(encoder_manifest_id),
+        )
+        object.__setattr__(self, "deployment_status", str(deployment_status))
+        object.__setattr__(self, "version", str(version))
+        computed = self.compute_binding_id()
+        object.__setattr__(self, "binding_id", str(binding_id or computed))
+        self.validate()
+
+    @property
+    def deployment_permitted(self) -> bool:
+        return self.deployment_status == "validated"
+
+    def validate(self) -> None:
+        if self.version != DEPLOYMENT_BINDING_VERSION:
+            raise VPMValidationError(
+                "unsupported deployment binding version: %r" % self.version
+            )
+        for name, value in (
+            ("policy_artifact_id", self.policy_artifact_id),
+            ("address_artifact_id", self.address_artifact_id),
+            ("calibration_artifact_id", self.calibration_artifact_id),
+            ("source_scope", self.source_scope),
+        ):
+            if not value:
+                raise VPMValidationError("%s cannot be empty" % name)
+        if self.deployment_status not in _DEPLOYMENT_STATUSES:
+            raise VPMValidationError(
+                "deployment_status must be 'validated' or 'research'"
+            )
+        expected = self.compute_binding_id()
+        if self.binding_id != expected:
+            raise VPMValidationError(
+                "deployment binding id mismatch: expected %s, got %s"
+                % (expected, self.binding_id)
+            )
+
+    def identity_payload(self) -> Dict[str, Any]:
+        return {
+            "version": self.version,
+            "policy_artifact_id": self.policy_artifact_id,
+            "address_artifact_id": self.address_artifact_id,
+            "calibration_artifact_id": self.calibration_artifact_id,
+            "encoder_manifest_id": self.encoder_manifest_id,
+            "source_scope": self.source_scope,
+            "deployment_status": self.deployment_status,
+        }
+
+    def compute_binding_id(self) -> str:
+        return hashlib.sha256(
+            b"zeromodel.deployment-binding.identity.v1\0"
+            + _canonical_json_bytes(self.identity_payload())
+        ).hexdigest()
+
+    def to_dict(self) -> Dict[str, Any]:
+        payload = self.identity_payload()
+        payload["binding_id"] = self.binding_id
+        payload["deployment_permitted"] = self.deployment_permitted
+        return payload
+
+    @classmethod
+    def from_dict(cls, data: Mapping[str, Any]) -> "DeploymentBinding":
+        return cls(
+            policy_artifact_id=str(data["policy_artifact_id"]),
+            address_artifact_id=str(data["address_artifact_id"]),
+            calibration_artifact_id=str(data["calibration_artifact_id"]),
+            encoder_manifest_id=data.get("encoder_manifest_id"),
+            source_scope=str(data["source_scope"]),
+            deployment_status=str(data.get("deployment_status", "validated")),
+            version=str(data.get("version", DEPLOYMENT_BINDING_VERSION)),
+            binding_id=data.get("binding_id"),
+        )
+
+    @classmethod
+    def from_contract(
+        cls,
+        contract: VisualAddressContract,
+        *,
+        deployment_status: str = "validated",
+        encoder_manifest_id: Optional[str] = None,
+    ) -> "DeploymentBinding":
+        if contract.source_scope is None or not contract.source_scope:
+            raise VPMValidationError(
+                "deployment binding requires contract source_scope"
+            )
+        return cls(
+            policy_artifact_id=contract.policy_artifact_id,
+            address_artifact_id=contract.address_artifact_id,
+            calibration_artifact_id=contract.calibration_artifact_id,
+            encoder_manifest_id=encoder_manifest_id,
+            source_scope=contract.source_scope,
+            deployment_status=deployment_status,
+        )
+
+    def verify_contract(
+        self,
+        contract: VisualAddressContract,
+        *,
+        allow_research: bool = False,
+    ) -> None:
+        contract.validate()
+        mismatches = []
+        for name, expected, actual in (
+            (
+                "policy_artifact_id",
+                self.policy_artifact_id,
+                contract.policy_artifact_id,
+            ),
+            (
+                "address_artifact_id",
+                self.address_artifact_id,
+                contract.address_artifact_id,
+            ),
+            (
+                "calibration_artifact_id",
+                self.calibration_artifact_id,
+                contract.calibration_artifact_id,
+            ),
+            ("source_scope", self.source_scope, contract.source_scope),
+        ):
+            if expected != actual:
+                mismatches.append("%s=%r (expected %r)" % (name, actual, expected))
+        if mismatches:
+            raise VPMValidationError(
+                "deployment binding does not match visual address contract: %s"
+                % "; ".join(mismatches)
+            )
+        if not self.deployment_permitted and not allow_research:
+            raise VPMValidationError(
+                "research deployment binding is not permitted in validated runtime"
+            )