agentevolve-optimizer 0.5.0__py3-none-any.whl

agent_evolve/ports/finite_acquisition_batch_json.py

@@ -0,0 +1,164 @@
+"""Strict JSON codecs for finite acquisition slate scoring."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from agent_evolve.ports.finite_acquisition_batch import (
+    FiniteAcquisitionBatchScoreDecision,
+    FiniteAcquisitionBatchScoreRequest,
+    FiniteAcquisitionSlate,
+    FiniteAcquisitionSlateScore,
+)
+from agent_evolve.ports.finite_acquisition_json import (
+    finite_acquisition_request_from_record,
+)
+
+
+def _object(value: object, *, name: str, keys: set[str]) -> dict[str, Any]:
+    if type(value) is not dict or set(value) != keys:
+        raise ValueError(f"{name} must be an exact JSON object with canonical fields")
+    return value
+
+
+def _list(value: object, *, name: str) -> list[Any]:
+    if type(value) is not list:
+        raise TypeError(f"{name} must be an exact JSON array")
+    return value
+
+
+def _string(value: object, *, name: str) -> str:
+    if type(value) is not str:
+        raise TypeError(f"{name} must be an exact JSON string")
+    return value
+
+
+def _integer(value: object, *, name: str) -> int:
+    if type(value) is not int:
+        raise TypeError(f"{name} must be an exact JSON integer")
+    return value
+
+
+def _hex_float(value: object, *, name: str) -> float:
+    text = _string(value, name=name)
+    try:
+        parsed = float.fromhex(text)
+    except ValueError as error:
+        raise ValueError(f"{name} must be a canonical hexadecimal float") from error
+    if parsed.hex() != text:
+        raise ValueError(f"{name} must use Python's canonical float.hex form")
+    return parsed
+
+
+def _slate_from_record(value: object, *, name: str) -> FiniteAcquisitionSlate:
+    record = _object(value, name=name, keys={"candidate_ids"})
+    return FiniteAcquisitionSlate(
+        tuple(
+            _string(item, name=f"{name}.candidate_id")
+            for item in _list(record["candidate_ids"], name=f"{name}.candidate_ids")
+        )
+    )
+
+
+def finite_acquisition_batch_score_request_from_record(
+    value: object,
+) -> FiniteAcquisitionBatchScoreRequest:
+    record = _object(
+        value,
+        name="finite acquisition batch-score request",
+        keys={"schema_version", "base_request", "slates", "request_sha256"},
+    )
+    if record["schema_version"] != 1:
+        raise ValueError("unsupported finite acquisition batch-score request schema")
+    base = finite_acquisition_request_from_record(record["base_request"])
+    request = FiniteAcquisitionBatchScoreRequest(
+        campaign_scope_sha256=base.campaign_scope_sha256,
+        cutoff_index=base.cutoff_index,
+        seed=base.seed,
+        objectives=base.objectives,
+        observations=base.observations,
+        candidates=base.candidates,
+        slates=tuple(
+            _slate_from_record(raw, name=f"slate[{index}]")
+            for index, raw in enumerate(_list(record["slates"], name="slates"))
+        ),
+    )
+    if request.request_sha256 != _string(
+        record["request_sha256"], name="request_sha256"
+    ):
+        raise ValueError("finite acquisition batch-score request authentication failed")
+    return request
+
+
+def finite_acquisition_batch_score_decision_from_record(
+    value: object,
+) -> FiniteAcquisitionBatchScoreDecision:
+    record = _object(
+        value,
+        name="finite acquisition batch-score decision",
+        keys={
+            "schema_version",
+            "request_sha256",
+            "policy",
+            "scores",
+            "diagnostics",
+            "decision_sha256",
+        },
+    )
+    if record["schema_version"] != 1:
+        raise ValueError("unsupported finite acquisition batch-score decision schema")
+    policy = _object(
+        record["policy"],
+        name="policy",
+        keys={"policy_id", "policy_version", "definition_sha256"},
+    )
+    scores: list[FiniteAcquisitionSlateScore] = []
+    for index, raw in enumerate(_list(record["scores"], name="scores")):
+        row = _object(
+            raw,
+            name=f"score[{index}]",
+            keys={"slate", "log_acquisition_value_hex"},
+        )
+        scores.append(
+            FiniteAcquisitionSlateScore(
+                slate=_slate_from_record(row["slate"], name=f"score[{index}].slate"),
+                log_acquisition_value=_hex_float(
+                    row["log_acquisition_value_hex"],
+                    name=f"score[{index}].log_acquisition_value_hex",
+                ),
+            )
+        )
+    diagnostics: list[tuple[str, str]] = []
+    for index, raw in enumerate(_list(record["diagnostics"], name="diagnostics")):
+        row = _object(
+            raw,
+            name=f"diagnostic[{index}]",
+            keys={"key", "value"},
+        )
+        diagnostics.append(
+            (
+                _string(row["key"], name="diagnostic key"),
+                _string(row["value"], name="diagnostic value"),
+            )
+        )
+    decision = FiniteAcquisitionBatchScoreDecision(
+        request_sha256=_string(record["request_sha256"], name="request_sha256"),
+        policy_id=_string(policy["policy_id"], name="policy_id"),
+        policy_version=_integer(policy["policy_version"], name="policy_version"),
+        policy_definition_sha256=_string(
+            policy["definition_sha256"], name="definition_sha256"
+        ),
+        scores=tuple(scores),
+        diagnostics=tuple(diagnostics),
+    )
+    if decision.decision_sha256 != _string(
+        record["decision_sha256"], name="decision_sha256"
+    ):
+        raise ValueError("finite acquisition batch-score decision authentication failed")
+    return decision
+
+
+__all__ = [
+    "finite_acquisition_batch_score_decision_from_record",
+    "finite_acquisition_batch_score_request_from_record",
+]

agent_evolve/ports/finite_acquisition_json.py

@@ -0,0 +1,247 @@
+"""Strict JSON codecs for the finite-acquisition ask/tell boundary."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from agent_evolve.ports.finite_acquisition import (
+    FiniteAcquisitionCandidate,
+    FiniteAcquisitionDecision,
+    FiniteAcquisitionObjective,
+    FiniteAcquisitionObservation,
+    FiniteAcquisitionRequest,
+    FiniteAcquisitionSelection,
+)
+
+
+def _object(value: object, *, name: str, keys: set[str]) -> dict[str, Any]:
+    if type(value) is not dict or set(value) != keys:
+        raise ValueError(f"{name} must be an exact JSON object with canonical fields")
+    return value
+
+
+def _list(value: object, *, name: str) -> list[Any]:
+    if type(value) is not list:
+        raise TypeError(f"{name} must be an exact JSON array")
+    return value
+
+
+def _string(value: object, *, name: str) -> str:
+    if type(value) is not str:
+        raise TypeError(f"{name} must be an exact JSON string")
+    return value
+
+
+def _integer(value: object, *, name: str) -> int:
+    if type(value) is not int:
+        raise TypeError(f"{name} must be an exact JSON integer")
+    return value
+
+
+def _hex_float(value: object, *, name: str) -> float:
+    text = _string(value, name=name)
+    try:
+        parsed = float.fromhex(text)
+    except ValueError as error:
+        raise ValueError(f"{name} must be a canonical hexadecimal float") from error
+    if parsed.hex() != text:
+        raise ValueError(f"{name} must use Python's canonical float.hex form")
+    return parsed
+
+
+def finite_acquisition_request_from_record(
+    value: object,
+) -> FiniteAcquisitionRequest:
+    """Reconstruct and authenticate a request from its canonical JSON record."""
+
+    record = _object(
+        value,
+        name="finite acquisition request",
+        keys={
+            "schema_version",
+            "campaign_scope_sha256",
+            "cutoff_index",
+            "batch_size",
+            "seed",
+            "objectives",
+            "observations",
+            "candidates",
+            "request_sha256",
+        },
+    )
+    if record["schema_version"] != 1:
+        raise ValueError("unsupported finite acquisition request schema")
+    objectives = []
+    for index, raw in enumerate(_list(record["objectives"], name="objectives")):
+        row = _object(
+            raw,
+            name=f"objective[{index}]",
+            keys={"metric_id", "sense", "ideal_hex", "reference_hex"},
+        )
+        objectives.append(
+            FiniteAcquisitionObjective(
+                metric_id=_string(row["metric_id"], name="metric_id"),
+                sense=_string(row["sense"], name="sense"),
+                ideal=_hex_float(row["ideal_hex"], name="ideal_hex"),
+                reference=_hex_float(row["reference_hex"], name="reference_hex"),
+            )
+        )
+    observations = []
+    for index, raw in enumerate(
+        _list(record["observations"], name="observations")
+    ):
+        row = _object(
+            raw,
+            name=f"observation[{index}]",
+            keys={
+                "candidate_id",
+                "configuration_sha256",
+                "features_hex",
+                "objectives",
+            },
+        )
+        objective_values = []
+        for metric_index, raw_metric in enumerate(
+            _list(row["objectives"], name="observation objectives")
+        ):
+            metric = _object(
+                raw_metric,
+                name=f"observation[{index}].objective[{metric_index}]",
+                keys={"metric_id", "value_hex"},
+            )
+            objective_values.append(
+                (
+                    _string(metric["metric_id"], name="metric_id"),
+                    _hex_float(metric["value_hex"], name="value_hex"),
+                )
+            )
+        observations.append(
+            FiniteAcquisitionObservation(
+                candidate_id=_string(row["candidate_id"], name="candidate_id"),
+                configuration_sha256=_string(
+                    row["configuration_sha256"], name="configuration_sha256"
+                ),
+                features=tuple(
+                    _hex_float(item, name="feature")
+                    for item in _list(row["features_hex"], name="features_hex")
+                ),
+                objectives=tuple(objective_values),
+            )
+        )
+    candidates = []
+    for index, raw in enumerate(_list(record["candidates"], name="candidates")):
+        row = _object(
+            raw,
+            name=f"candidate[{index}]",
+            keys={"candidate_id", "configuration_sha256", "features_hex"},
+        )
+        candidates.append(
+            FiniteAcquisitionCandidate(
+                candidate_id=_string(row["candidate_id"], name="candidate_id"),
+                configuration_sha256=_string(
+                    row["configuration_sha256"], name="configuration_sha256"
+                ),
+                features=tuple(
+                    _hex_float(item, name="feature")
+                    for item in _list(row["features_hex"], name="features_hex")
+                ),
+            )
+        )
+    request = FiniteAcquisitionRequest(
+        campaign_scope_sha256=_string(
+            record["campaign_scope_sha256"], name="campaign_scope_sha256"
+        ),
+        cutoff_index=_integer(record["cutoff_index"], name="cutoff_index"),
+        batch_size=_integer(record["batch_size"], name="batch_size"),
+        seed=_integer(record["seed"], name="seed"),
+        objectives=tuple(objectives),
+        observations=tuple(observations),
+        candidates=tuple(candidates),
+    )
+    if request.request_sha256 != _string(
+        record["request_sha256"], name="request_sha256"
+    ):
+        raise ValueError("finite acquisition request authentication failed")
+    return request
+
+
+def finite_acquisition_decision_from_record(
+    value: object,
+) -> FiniteAcquisitionDecision:
+    """Reconstruct and authenticate a decision from its canonical JSON record."""
+
+    record = _object(
+        value,
+        name="finite acquisition decision",
+        keys={
+            "schema_version",
+            "request_sha256",
+            "policy",
+            "selected",
+            "diagnostics",
+            "decision_sha256",
+        },
+    )
+    if record["schema_version"] != 1:
+        raise ValueError("unsupported finite acquisition decision schema")
+    policy = _object(
+        record["policy"],
+        name="policy",
+        keys={"policy_id", "policy_version", "definition_sha256"},
+    )
+    selected = []
+    for index, raw in enumerate(_list(record["selected"], name="selected")):
+        row = _object(
+            raw,
+            name=f"selection[{index}]",
+            keys={
+                "candidate_id",
+                "configuration_sha256",
+                "acquisition_value_hex",
+            },
+        )
+        selected.append(
+            FiniteAcquisitionSelection(
+                candidate_id=_string(row["candidate_id"], name="candidate_id"),
+                configuration_sha256=_string(
+                    row["configuration_sha256"], name="configuration_sha256"
+                ),
+                acquisition_value=_hex_float(
+                    row["acquisition_value_hex"], name="acquisition_value_hex"
+                ),
+            )
+        )
+    diagnostics = []
+    for index, raw in enumerate(_list(record["diagnostics"], name="diagnostics")):
+        row = _object(
+            raw,
+            name=f"diagnostic[{index}]",
+            keys={"key", "value"},
+        )
+        diagnostics.append(
+            (
+                _string(row["key"], name="diagnostic key"),
+                _string(row["value"], name="diagnostic value"),
+            )
+        )
+    decision = FiniteAcquisitionDecision(
+        request_sha256=_string(record["request_sha256"], name="request_sha256"),
+        policy_id=_string(policy["policy_id"], name="policy_id"),
+        policy_version=_integer(policy["policy_version"], name="policy_version"),
+        policy_definition_sha256=_string(
+            policy["definition_sha256"], name="definition_sha256"
+        ),
+        selected=tuple(selected),
+        diagnostics=tuple(diagnostics),
+    )
+    if decision.decision_sha256 != _string(
+        record["decision_sha256"], name="decision_sha256"
+    ):
+        raise ValueError("finite acquisition decision authentication failed")
+    return decision
+
+
+__all__ = [
+    "finite_acquisition_decision_from_record",
+    "finite_acquisition_request_from_record",
+]

agent_evolve/ports/finite_acquisition_space.py

@@ -0,0 +1,168 @@
+"""Outcome-blind workload boundary for a finite acquisition reservoir.
+
+The workload owns legality, materialization, and a normalized feature codec.
+The search controller supplies only cutoff identity, exclusions, pool size,
+and a deterministic seed.  Objective values never cross this boundary; they
+are joined later by the generic acquisition-envelope application service.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from dataclasses import dataclass, field
+from typing import Protocol, runtime_checkable
+
+from agent_evolve.domain.patch import require_sha256
+from agent_evolve.domain.typed_json import (
+    FrozenJsonObject,
+    freeze_json,
+    typed_json_sha256,
+)
+
+
+_TOKEN = re.compile(r"^[a-z][a-z0-9_.:-]{0,127}$")
+_REQUEST_DOMAIN = b"agent-evolve:finite-acquisition-space-request: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")
+
+
+@dataclass(frozen=True, slots=True)
+class FiniteAcquisitionSpaceRequest:
+    campaign_scope_sha256: str
+    cutoff_index: int
+    pool_size: int
+    seed: int
+    observed_configurations: tuple[FrozenJsonObject, ...]
+    excluded_configuration_sha256s: tuple[str, ...]
+    request_sha256: str = field(init=False, default="")
+
+    def __post_init__(self) -> None:
+        require_sha256(self.campaign_scope_sha256, "campaign_scope_sha256")
+        if type(self.cutoff_index) is not int or self.cutoff_index < 1:
+            raise ValueError("cutoff_index must be positive")
+        if type(self.pool_size) is not int or self.pool_size < 1:
+            raise ValueError("pool_size must be positive")
+        if type(self.seed) is not int or self.seed < 0:
+            raise ValueError("seed must be a non-negative exact integer")
+        if type(self.observed_configurations) is not tuple or not (
+            self.observed_configurations
+        ):
+            raise ValueError("observed_configurations must be a non-empty exact tuple")
+        observed_identities: list[str] = []
+        for value in self.observed_configurations:
+            if type(value) is not FrozenJsonObject or freeze_json(value) is not value:
+                raise TypeError(
+                    "observed configurations must be frozen typed-JSON objects"
+                )
+            observed_identities.append(typed_json_sha256(value))
+        if tuple(observed_identities) != tuple(sorted(set(observed_identities))):
+            raise ValueError("observed configurations must be unique and hash-sorted")
+        if type(self.excluded_configuration_sha256s) is not tuple:
+            raise TypeError("excluded configuration identities must be an exact tuple")
+        for value in self.excluded_configuration_sha256s:
+            require_sha256(value, "excluded_configuration_sha256")
+        if self.excluded_configuration_sha256s != tuple(
+            sorted(set(self.excluded_configuration_sha256s))
+        ):
+            raise ValueError("excluded configuration identities must be canonical")
+        if not set(observed_identities) <= set(
+            self.excluded_configuration_sha256s
+        ):
+            raise ValueError("observed configurations must be excluded from the pool")
+        record = self._unsigned_record()
+        computed = hashlib.sha256(
+            _REQUEST_DOMAIN + _canonical_json(record)
+        ).hexdigest()
+        if self.request_sha256 not in ("", computed):
+            raise ValueError("request_sha256 does not authenticate the request")
+        object.__setattr__(self, "request_sha256", computed)
+
+    def _unsigned_record(self) -> dict[str, object]:
+        return {
+            "schema_version": 1,
+            "campaign_scope_sha256": self.campaign_scope_sha256,
+            "cutoff_index": self.cutoff_index,
+            "pool_size": self.pool_size,
+            "seed": self.seed,
+            "observed_configuration_sha256s": [
+                typed_json_sha256(value) for value in self.observed_configurations
+            ],
+            "excluded_configuration_sha256s": list(
+                self.excluded_configuration_sha256s
+            ),
+            "outcome_access": False,
+        }
+
+    def to_record(self) -> dict[str, object]:
+        self.__post_init__()
+        return {**self._unsigned_record(), "request_sha256": self.request_sha256}
+
+
+@runtime_checkable
+class FiniteAcquisitionSpace(Protocol):
+    """Enumerate legal configurations and encode any legal configuration."""
+
+    space_id: str
+    space_version: int
+    definition_sha256: str
+
+    def candidates(
+        self,
+        request: FiniteAcquisitionSpaceRequest,
+    ) -> tuple[FrozenJsonObject, ...]: ...
+
+    def features(self, configuration: FrozenJsonObject) -> tuple[float, ...]: ...
+
+
+def validate_finite_acquisition_space_identity(
+    space: FiniteAcquisitionSpace,
+) -> tuple[str, int, str]:
+    if not isinstance(space, FiniteAcquisitionSpace):
+        raise TypeError("space must implement FiniteAcquisitionSpace")
+    if type(space.space_id) is not str or _TOKEN.fullmatch(space.space_id) is None:
+        raise ValueError("finite acquisition space_id has invalid syntax")
+    if type(space.space_version) is not int or space.space_version <= 0:
+        raise ValueError("finite acquisition space_version must be positive")
+    require_sha256(space.definition_sha256, "finite acquisition space definition")
+    return space.space_id, space.space_version, space.definition_sha256
+
+
+def validate_finite_acquisition_space_candidates(
+    *,
+    request: FiniteAcquisitionSpaceRequest,
+    candidates: tuple[FrozenJsonObject, ...],
+) -> None:
+    if type(request) is not FiniteAcquisitionSpaceRequest:
+        raise TypeError("request must be exact")
+    FiniteAcquisitionSpaceRequest.__post_init__(request)
+    if type(candidates) is not tuple or len(candidates) != request.pool_size:
+        raise ValueError("acquisition space must return the exact requested pool")
+    excluded = set(request.excluded_configuration_sha256s)
+    identities: list[str] = []
+    for value in candidates:
+        if type(value) is not FrozenJsonObject or freeze_json(value) is not value:
+            raise TypeError("acquisition candidates must be frozen typed-JSON objects")
+        identity = typed_json_sha256(value)
+        if identity in excluded:
+            raise ValueError("acquisition space returned an excluded configuration")
+        identities.append(identity)
+    if len(set(identities)) != len(identities):
+        raise ValueError("acquisition space returned duplicate configurations")
+
+
+__all__ = [
+    "FiniteAcquisitionSpace",
+    "FiniteAcquisitionSpaceRequest",
+    "validate_finite_acquisition_space_candidates",
+    "validate_finite_acquisition_space_identity",
+]