agentevolve-optimizer 0.5.0__py3-none-any.whl

agent_evolve/ports/archive_context.py

@@ -0,0 +1,136 @@
+"""Workload-neutral projection port for authenticated archive geometry.
+
+The campaign runtime owns when a projection is attached.  Implementations own
+how an already-frozen archive utility and an already-evaluated parent are
+translated into a bounded model-visible payload.  The port cannot inspect a
+model/provider profile or any current/future candidate outcome.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+from agent_evolve.domain.typed_json import (
+    FrozenJsonObject,
+    freeze_json,
+    thaw_json,
+    typed_json_sha256,
+)
+
+if TYPE_CHECKING:
+    from agent_evolve.application.agentic_evolution import EvolutionCandidate
+    from agent_evolve.application.evolution_campaign import ArchiveUtilitySnapshot
+
+
+_TOKEN = re.compile(r"^[a-z][a-z0-9_.-]{0,127}$")
+_PROJECTION_DOMAIN = b"agent-evolve:campaign-archive-context-projection:v1\x00"
+
+
+def _canonical_json(value: object) -> bytes:
+    return json.dumps(
+        value,
+        allow_nan=False,
+        ensure_ascii=True,
+        separators=(",", ":"),
+        sort_keys=True,
+    ).encode("ascii", errors="strict")
+
+
+def _require_sha256(value: str, name: str) -> None:
+    if (
+        type(value) is not str
+        or len(value) != 64
+        or any(character not in "0123456789abcdef" for character in value)
+    ):
+        raise ValueError(f"{name} must be a lowercase SHA-256 digest")
+
+
+@dataclass(frozen=True, slots=True)
+class CampaignPortfolioArchiveContextProjection:
+    """One exact cutoff-valid archive projection for one parent decision."""
+
+    projector_id: str
+    projector_version: int
+    definition_sha256: str
+    archive_utility_snapshot_sha256: str
+    parent_configuration_sha256: str
+    payload: FrozenJsonObject
+    projection_sha256: str = field(init=False)
+
+    def __post_init__(self) -> None:
+        if type(self.projector_id) is not str or _TOKEN.fullmatch(
+            self.projector_id
+        ) is None:
+            raise ValueError("projector_id must use the closed token grammar")
+        if type(self.projector_version) is not int or self.projector_version <= 0:
+            raise ValueError("projector_version must be a positive exact integer")
+        _require_sha256(self.definition_sha256, "definition_sha256")
+        _require_sha256(
+            self.archive_utility_snapshot_sha256,
+            "archive_utility_snapshot_sha256",
+        )
+        _require_sha256(
+            self.parent_configuration_sha256,
+            "parent_configuration_sha256",
+        )
+        if (
+            type(self.payload) is not FrozenJsonObject
+            or freeze_json(self.payload) is not self.payload
+        ):
+            raise TypeError("payload must be an exact frozen typed-JSON object")
+        object.__setattr__(
+            self,
+            "projection_sha256",
+            hashlib.sha256(
+                _PROJECTION_DOMAIN + _canonical_json(self._unsigned_record())
+            ).hexdigest(),
+        )
+
+    def _unsigned_record(self) -> dict[str, object]:
+        return {
+            "schema_version": 1,
+            "projector": {
+                "projector_id": self.projector_id,
+                "projector_version": self.projector_version,
+                "definition_sha256": self.definition_sha256,
+            },
+            "archive_utility_snapshot_sha256": (
+                self.archive_utility_snapshot_sha256
+            ),
+            "parent_configuration_sha256": self.parent_configuration_sha256,
+            "payload_sha256": typed_json_sha256(self.payload),
+            "payload": thaw_json(self.payload),
+        }
+
+    def to_record(self) -> dict[str, object]:
+        self.__post_init__()
+        return {
+            **self._unsigned_record(),
+            "projection_sha256": self.projection_sha256,
+        }
+
+
+@runtime_checkable
+class CampaignPortfolioArchiveContextProjector(Protocol):
+    """Project only frozen archive state and one evaluated parent."""
+
+    projector_id: str
+    projector_version: int
+    definition_sha256: str
+
+    def project(
+        self,
+        *,
+        archive_utility: ArchiveUtilitySnapshot,
+        parent: EvolutionCandidate,
+    ) -> CampaignPortfolioArchiveContextProjection: ...
+
+
+__all__ = [
+    "CampaignPortfolioArchiveContextProjection",
+    "CampaignPortfolioArchiveContextProjector",
+]

agent_evolve/ports/artifact_sanitizer.py

@@ -0,0 +1,44 @@
+"""Ports for artifact minimization and deterministic secret sanitization."""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+from agent_evolve.domain.artifact import ArtifactRole
+
+
+class ArtifactMinimizationError(ValueError):
+    """A value cannot be minimized under the selected role policy."""
+
+
+class ArtifactSanitizationError(ValueError):
+    """A value cannot be made safe under the selected sanitization policy."""
+
+
+@runtime_checkable
+class ArtifactMinimizer(Protocol):
+    """Remove fields that are unnecessary for a role before redaction."""
+
+    @property
+    def policy_id(self) -> str: ...
+
+    @property
+    def policy_version(self) -> str: ...
+
+    @property
+    def policy_config_sha256(self) -> str: ...
+
+    def minimize_json(self, value: Any, *, role: ArtifactRole) -> Any: ...
+
+
+@runtime_checkable
+class ArtifactSanitizer(Protocol):
+    """Return a detached JSON value safe to pass to canonical encoding."""
+
+    @property
+    def policy_id(self) -> str: ...
+
+    @property
+    def policy_version(self) -> str: ...
+
+    def sanitize_json(self, value: Any, *, role: ArtifactRole) -> Any: ...

agent_evolve/ports/artifact_store.py

@@ -0,0 +1,225 @@
+"""Content-addressed artifact-store port, errors, and strict codecs."""
+
+from __future__ import annotations
+
+import json
+import math
+from typing import Any, Protocol, runtime_checkable
+
+from agent_evolve.domain.artifact import ArtifactRef
+from agent_evolve.domain.ids import ArtifactId
+
+JSON_MEDIA_TYPE = "application/json"
+UTF8_TEXT_MEDIA_TYPE = "text/plain; charset=utf-8"
+
+
+class ArtifactStoreError(RuntimeError):
+    """Base error for artifact persistence and retrieval failures."""
+
+
+class ArtifactNotFoundError(ArtifactStoreError):
+    """The requested artifact ID is not present."""
+
+
+class CorruptArtifactError(ArtifactStoreError):
+    """Stored bytes or metadata do not verify against their artifact ID."""
+
+
+class ArtifactCollisionError(ArtifactStoreError):
+    """Different typed payloads resolved to the same artifact identity."""
+
+
+class ArtifactTypeError(TypeError, ArtifactStoreError):
+    """A value or stored media type does not match the requested representation."""
+
+
+class ArtifactSerializationError(ArtifactStoreError):
+    """A text or JSON value cannot be encoded or decoded strictly."""
+
+
+@runtime_checkable
+class ArtifactStore(Protocol):
+    """Persist and verify immutable typed byte payloads by content address."""
+
+    def put_bytes(self, content: bytes, *, media_type: str) -> ArtifactRef: ...
+
+    def stat(self, artifact_id: ArtifactId) -> ArtifactRef: ...
+
+    def read_bytes(
+        self,
+        artifact_id: ArtifactId,
+        *,
+        expected_media_type: str | None = None,
+    ) -> bytes: ...
+
+
+def _validate_json_value(
+    value: Any,
+    *,
+    path: str = "$",
+    ancestors: set[int] | None = None,
+) -> None:
+    if value is None or isinstance(value, (bool, int)):
+        return
+    if isinstance(value, str):
+        _validate_utf8_string(value, path=path)
+        return
+    if isinstance(value, float):
+        if not math.isfinite(value):
+            raise ArtifactSerializationError(f"Non-finite JSON number at {path}")
+        return
+    if isinstance(value, (list, tuple)):
+        ancestors = set() if ancestors is None else ancestors
+        identity = id(value)
+        if identity in ancestors:
+            raise ArtifactSerializationError(f"Cyclic JSON container at {path}")
+        ancestors.add(identity)
+        try:
+            for index, item in enumerate(value):
+                _validate_json_value(
+                    item,
+                    path=f"{path}[{index}]",
+                    ancestors=ancestors,
+                )
+        finally:
+            ancestors.remove(identity)
+        return
+    if isinstance(value, dict):
+        ancestors = set() if ancestors is None else ancestors
+        identity = id(value)
+        if identity in ancestors:
+            raise ArtifactSerializationError(f"Cyclic JSON container at {path}")
+        ancestors.add(identity)
+        try:
+            for key, item in value.items():
+                if not isinstance(key, str):
+                    raise ArtifactSerializationError(
+                        f"JSON object key at {path} must be a string"
+                    )
+                _validate_utf8_string(key, path=f"{path} object key")
+                _validate_json_value(
+                    item,
+                    path=f"{path}[{key!r}]",
+                    ancestors=ancestors,
+                )
+        finally:
+            ancestors.remove(identity)
+        return
+    raise ArtifactSerializationError(
+        f"Value at {path} has unsupported JSON type {type(value).__name__}"
+    )
+
+
+def _validate_utf8_string(value: str, *, path: str) -> None:
+    try:
+        value.encode("utf-8", errors="strict")
+    except UnicodeEncodeError as exc:
+        raise ArtifactSerializationError(
+            f"JSON string at {path} is not strict UTF-8 encodable"
+        ) from exc
+
+
+def canonical_json_bytes(value: Any) -> bytes:
+    """Encode the supported JSON value domain deterministically as UTF-8."""
+
+    try:
+        _validate_json_value(value)
+        encoded = json.dumps(
+            value,
+            allow_nan=False,
+            ensure_ascii=False,
+            separators=(",", ":"),
+            sort_keys=True,
+        )
+        return encoded.encode("utf-8", errors="strict")
+    except ArtifactSerializationError:
+        raise
+    except (TypeError, ValueError, UnicodeEncodeError, RecursionError) as exc:
+        raise ArtifactSerializationError(f"JSON encoding failed: {exc}") from exc
+
+
+def _reject_duplicate_keys(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
+    result: dict[str, Any] = {}
+    for key, value in pairs:
+        if key in result:
+            raise ArtifactSerializationError(f"Duplicate JSON object key {key!r}")
+        result[key] = value
+    return result
+
+
+def _reject_nonstandard_number(value: str) -> None:
+    raise ArtifactSerializationError(f"Non-standard JSON number {value!r}")
+
+
+def decode_json_bytes(content: bytes) -> Any:
+    """Decode strict UTF-8 JSON, rejecting duplicates and non-standard numbers."""
+
+    if not isinstance(content, bytes):
+        raise ArtifactTypeError("JSON artifact content must be bytes")
+    try:
+        text = content.decode("utf-8", errors="strict")
+        value = json.loads(
+            text,
+            object_pairs_hook=_reject_duplicate_keys,
+            parse_constant=_reject_nonstandard_number,
+        )
+    except ArtifactSerializationError:
+        raise
+    except (UnicodeDecodeError, json.JSONDecodeError, RecursionError) as exc:
+        raise ArtifactSerializationError(f"JSON decoding failed: {exc}") from exc
+    try:
+        _validate_json_value(value)
+    except RecursionError as exc:
+        raise ArtifactSerializationError("JSON value exceeds the nesting limit") from exc
+    return value
+
+
+def put_json(
+    store: ArtifactStore,
+    value: Any,
+    *,
+    media_type: str = JSON_MEDIA_TYPE,
+) -> ArtifactRef:
+    return store.put_bytes(canonical_json_bytes(value), media_type=media_type)
+
+
+def read_json(
+    store: ArtifactStore,
+    artifact_id: ArtifactId,
+    *,
+    expected_media_type: str = JSON_MEDIA_TYPE,
+) -> Any:
+    return decode_json_bytes(
+        store.read_bytes(artifact_id, expected_media_type=expected_media_type)
+    )
+
+
+def put_text(
+    store: ArtifactStore,
+    value: str,
+    *,
+    media_type: str = UTF8_TEXT_MEDIA_TYPE,
+) -> ArtifactRef:
+    if not isinstance(value, str):
+        raise ArtifactTypeError("text artifact value must be a string")
+    try:
+        content = value.encode("utf-8", errors="strict")
+    except UnicodeEncodeError as exc:
+        raise ArtifactSerializationError(f"UTF-8 encoding failed: {exc}") from exc
+    return store.put_bytes(content, media_type=media_type)
+
+
+def read_text(
+    store: ArtifactStore,
+    artifact_id: ArtifactId,
+    *,
+    expected_media_type: str = UTF8_TEXT_MEDIA_TYPE,
+) -> str:
+    content = store.read_bytes(
+        artifact_id,
+        expected_media_type=expected_media_type,
+    )
+    try:
+        return content.decode("utf-8", errors="strict")
+    except UnicodeDecodeError as exc:
+        raise ArtifactSerializationError(f"UTF-8 decoding failed: {exc}") from exc

agent_evolve/ports/clock.py

@@ -0,0 +1,13 @@
+"""Wall/monotonic clock port."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class Clock(Protocol):
+    def utc_now(self) -> datetime: ...
+    def monotonic_ns(self) -> int: ...
+