agentevolve-optimizer 0.5.0__py3-none-any.whl

agent_evolve/application/treatment_assignment.py

@@ -0,0 +1,201 @@
+"""Deterministic prospective treatment-to-provider-slot assignment.
+
+The permutation is derived only from public committed material, an identified
+policy/domain, the occurrence count, and canonical input ordinals.  Treatment,
+occurrence, provider-slot, call, and request labels are intentionally excluded
+from permutation ranks.  They remain fully bound by the resulting receipt.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+import hashlib
+import json
+
+from agent_evolve.ports.treatment_assignment import (
+    ProspectiveTreatmentAssignmentReceipt,
+    TreatmentAssignment,
+    TreatmentAssignmentInput,
+    TreatmentAssignmentPolicyBinding,
+)
+
+
+HASH_RANKED_TREATMENT_ASSIGNMENT_POLICY_ID = (
+    "hash_ranked_treatment_occurrence_assignment"
+)
+HASH_RANKED_TREATMENT_ASSIGNMENT_POLICY_VERSION = 1
+HASH_RANKED_TREATMENT_ASSIGNMENT_PERMUTATION_DOMAIN = (
+    "agent-evolve:prospective-treatment-assignment-rank:v1"
+)
+HASH_RANKED_TREATMENT_ASSIGNMENT_POLICY_DEFINITION_SHA256 = hashlib.sha256(
+    b"agent-evolve:hash-ranked-treatment-occurrence-assignment:v1;"
+    b"rank=sha256(domain,policy_binding,experiment_commitment,public_seed_"
+    b"material,occurrence_count,occurrence_input_index);"
+    b"sort=rank_digest_then_occurrence_input_index;"
+    b"provider_slots=canonical_input_order;labels_excluded_from_rank;"
+    b"runtime_rng=forbidden"
+).hexdigest()
+
+
+class TreatmentAssignmentVerificationError(RuntimeError):
+    """A supplied receipt differs from deterministic prospective replay."""
+
+
+def _canonical_json(value: object) -> bytes:
+    return json.dumps(
+        value,
+        allow_nan=False,
+        ensure_ascii=True,
+        separators=(",", ":"),
+        sort_keys=True,
+    ).encode("ascii")
+
+
+def hash_ranked_treatment_assignment_policy() -> TreatmentAssignmentPolicyBinding:
+    """Return the identified domain-neutral public permutation policy."""
+
+    return TreatmentAssignmentPolicyBinding(
+        policy_id=HASH_RANKED_TREATMENT_ASSIGNMENT_POLICY_ID,
+        policy_version=HASH_RANKED_TREATMENT_ASSIGNMENT_POLICY_VERSION,
+        policy_definition_sha256=(
+            HASH_RANKED_TREATMENT_ASSIGNMENT_POLICY_DEFINITION_SHA256
+        ),
+        permutation_domain=HASH_RANKED_TREATMENT_ASSIGNMENT_PERMUTATION_DOMAIN,
+    )
+
+
+def treatment_assignment_ordinal_permutation(
+    assignment_input: TreatmentAssignmentInput,
+    *,
+    policy: TreatmentAssignmentPolicyBinding,
+) -> tuple[int, ...]:
+    """Derive the provider-slot-to-occurrence permutation without runtime RNG."""
+
+    if type(assignment_input) is not TreatmentAssignmentInput:
+        raise TypeError("assignment_input must be an exact TreatmentAssignmentInput")
+    assignment_input.__post_init__()
+    if type(policy) is not TreatmentAssignmentPolicyBinding:
+        raise TypeError("policy must be an exact TreatmentAssignmentPolicyBinding")
+    policy.__post_init__()
+
+    count = len(assignment_input.occurrences)
+    domain = policy.permutation_domain.encode("ascii") + b"\x00"
+    ranked: list[tuple[bytes, int]] = []
+    for occurrence_input_index in range(count):
+        rank_payload = {
+            "schema_version": 1,
+            "policy_binding_sha256": policy.binding_sha256,
+            "experiment_commitment_sha256": (
+                assignment_input.experiment_commitment_sha256
+            ),
+            "public_seed_material": assignment_input.public_seed_material,
+            "occurrence_count": count,
+            "occurrence_input_index": occurrence_input_index,
+        }
+        rank_digest = hashlib.sha256(
+            domain + _canonical_json(rank_payload)
+        ).digest()
+        ranked.append((rank_digest, occurrence_input_index))
+    return tuple(index for _, index in sorted(ranked))
+
+
+def assign_treatment_occurrences(
+    assignment_input: TreatmentAssignmentInput,
+    *,
+    policy: TreatmentAssignmentPolicyBinding | None = None,
+) -> ProspectiveTreatmentAssignmentReceipt:
+    """Create one prospective, replayable assignment and authenticated inverse."""
+
+    if type(assignment_input) is not TreatmentAssignmentInput:
+        raise TypeError("assignment_input must be an exact TreatmentAssignmentInput")
+    assignment_input.__post_init__()
+    effective_policy = (
+        hash_ranked_treatment_assignment_policy() if policy is None else policy
+    )
+    if type(effective_policy) is not TreatmentAssignmentPolicyBinding:
+        raise TypeError("policy must be an exact TreatmentAssignmentPolicyBinding")
+    effective_policy.__post_init__()
+
+    permutation = treatment_assignment_ordinal_permutation(
+        assignment_input,
+        policy=effective_policy,
+    )
+    inverse_values = [0] * len(permutation)
+    slot_assignments: list[TreatmentAssignment] = []
+    for provider_slot_input_index, occurrence_input_index in enumerate(permutation):
+        inverse_values[occurrence_input_index] = provider_slot_input_index
+        occurrence = assignment_input.occurrences[occurrence_input_index]
+        slot_assignments.append(
+            TreatmentAssignment(
+                occurrence_id=occurrence.occurrence_id,
+                treatment_id=occurrence.treatment_id,
+                opaque_provider_slot_id=(
+                    assignment_input.provider_slot_ids[provider_slot_input_index]
+                ),
+                occurrence_input_index=occurrence_input_index,
+                provider_slot_input_index=provider_slot_input_index,
+                call_identity=occurrence.call_identity,
+                request_identity_sha256=occurrence.request_identity_sha256,
+            )
+        )
+    inverse = tuple(inverse_values)
+    assignments_by_occurrence: list[TreatmentAssignment | None] = [
+        None
+    ] * len(permutation)
+    for assignment in slot_assignments:
+        assignments_by_occurrence[assignment.occurrence_input_index] = assignment
+    if any(value is None for value in assignments_by_occurrence):
+        raise RuntimeError("internal assignment construction lost an occurrence")
+
+    return ProspectiveTreatmentAssignmentReceipt(
+        policy=effective_policy,
+        assignment_input_sha256=assignment_input.input_sha256,
+        experiment_commitment_sha256=(
+            assignment_input.experiment_commitment_sha256
+        ),
+        public_seed_material=assignment_input.public_seed_material,
+        occurrence_input_order=assignment_input.occurrences,
+        provider_slot_input_order=assignment_input.provider_slot_ids,
+        ordinal_permutation=permutation,
+        inverse_ordinal_permutation=inverse,
+        slot_to_occurrence=tuple(slot_assignments),
+        occurrence_to_slot=tuple(
+            value for value in assignments_by_occurrence if value is not None
+        ),
+    )
+
+
+def verify_treatment_assignment_receipt(
+    assignment_input: TreatmentAssignmentInput,
+    receipt: ProspectiveTreatmentAssignmentReceipt | Mapping[str, object],
+    *,
+    policy: TreatmentAssignmentPolicyBinding | None = None,
+) -> ProspectiveTreatmentAssignmentReceipt:
+    """Fail closed unless an object or serialized record equals public replay."""
+
+    expected = assign_treatment_occurrences(assignment_input, policy=policy)
+    if type(receipt) is ProspectiveTreatmentAssignmentReceipt:
+        receipt.__post_init__()
+        matches = receipt == expected
+    elif isinstance(receipt, Mapping):
+        matches = type(receipt) is dict and receipt == expected.to_record()
+    else:
+        raise TypeError("receipt must be an exact receipt or canonical dict record")
+    if not matches:
+        raise TreatmentAssignmentVerificationError(
+            "treatment assignment receipt differs from deterministic replay"
+        )
+    return expected
+
+
+__all__ = [
+    "HASH_RANKED_TREATMENT_ASSIGNMENT_PERMUTATION_DOMAIN",
+    "HASH_RANKED_TREATMENT_ASSIGNMENT_POLICY_DEFINITION_SHA256",
+    "HASH_RANKED_TREATMENT_ASSIGNMENT_POLICY_ID",
+    "HASH_RANKED_TREATMENT_ASSIGNMENT_POLICY_VERSION",
+    "TreatmentAssignmentVerificationError",
+    "assign_treatment_occurrences",
+    "hash_ranked_treatment_assignment_policy",
+    "treatment_assignment_ordinal_permutation",
+    "verify_treatment_assignment_receipt",
+]

agent_evolve/application/trusted_objective_evidence.py

@@ -0,0 +1,217 @@
+"""Auditable binary64 objective evidence with LLM-readable decimal values.
+
+Persistent AgentEvolve receipts use ``float.hex`` strings because they are
+exact and replayable.  Those strings are a poor cognitive interface: an LLM
+can easily read a hexadecimal significand as an ordinary decimal number.
+This codec preserves the exact machine representation while providing a
+separate JSON numeric field and round-trip decimal text for reasoning.
+
+The codec is objective-, workload-, model-, provider-, and prompt-neutral.
+Adapters decide which already-observed values are disclosed; this module only
+prevents their representation from changing their meaning.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import math
+import re
+from dataclasses import dataclass, field
+from typing import Mapping
+
+from agent_evolve.domain.typed_json import (
+    FrozenJsonObject,
+    freeze_json,
+    thaw_json,
+)
+
+
+TRUSTED_OBJECTIVE_EVIDENCE_CODEC_ID = (
+    "binary64_decimal_objective_evidence"
+)
+TRUSTED_OBJECTIVE_EVIDENCE_CODEC_VERSION = 1
+TRUSTED_OBJECTIVE_EVIDENCE_CODEC_DEFINITION_SHA256 = hashlib.sha256(
+    b"agent-evolve:binary64-decimal-objective-evidence:v1;"
+    b"reasoning-value=json-finite-number;"
+    b"roundtrip-text=17-significant-decimal-digits;"
+    b"audit-value=python-binary64-hex;"
+    b"consistency=all-three-representations-must-roundtrip-identically;"
+    b"hex-is-explicitly-machine-audit-only;"
+    b"workload-objective-model-provider-branches=false"
+).hexdigest()
+
+_METRIC = re.compile(r"^[A-Za-z][A-Za-z0-9_.:/-]{0,255}$")
+
+
+def _finite_float(value: object, *, name: str) -> float:
+    if type(value) is not float or not math.isfinite(value):
+        raise TypeError(f"{name} must be a finite exact float")
+    return value
+
+
+def _metric_id(value: object) -> str:
+    if type(value) is not str or _METRIC.fullmatch(value) is None:
+        raise ValueError("metric_id must use the closed metric grammar")
+    return value
+
+
+@dataclass(frozen=True, slots=True)
+class TrustedObjectiveEvidenceCodec:
+    """Render known objective values without asking a model to parse hex."""
+
+    codec_id: str = field(
+        init=False,
+        default=TRUSTED_OBJECTIVE_EVIDENCE_CODEC_ID,
+    )
+    codec_version: int = field(
+        init=False,
+        default=TRUSTED_OBJECTIVE_EVIDENCE_CODEC_VERSION,
+    )
+    definition_sha256: str = field(
+        init=False,
+        default=TRUSTED_OBJECTIVE_EVIDENCE_CODEC_DEFINITION_SHA256,
+    )
+
+    def prompt_contract(self) -> FrozenJsonObject:
+        value = freeze_json(
+            {
+                "codec_id": self.codec_id,
+                "codec_version": self.codec_version,
+                "definition_sha256": self.definition_sha256,
+                "reasoning_field": "numeric_values",
+                "exact_audit_field": "exact_binary64_hex",
+                "instructions": [
+                    (
+                        "Use numeric_values for comparisons, arithmetic, "
+                        "forecasting, and optimization reasoning."
+                    ),
+                    (
+                        "decimal_text is a round-trip decimal rendering of "
+                        "the same binary64 values."
+                    ),
+                    (
+                        "exact_binary64_hex is machine-audit evidence only; "
+                        "never interpret its digits as a decimal magnitude."
+                    ),
+                ],
+                "representations_consistency_checked": True,
+                "candidate_outcomes_disclosed_by_codec": False,
+                "workload_objective_model_provider_branches": False,
+            }
+        )
+        if type(value) is not FrozenJsonObject:
+            raise TypeError("prompt contract must have an object root")
+        return value
+
+    def encode_point(
+        self,
+        objectives: Mapping[str, float],
+    ) -> FrozenJsonObject:
+        """Encode one already-authorized objective mapping."""
+
+        if not isinstance(objectives, Mapping) or not objectives:
+            raise ValueError("objectives must be a non-empty mapping")
+        ordered: list[tuple[str, float]] = []
+        for metric_id, raw_value in objectives.items():
+            ordered.append(
+                (
+                    _metric_id(metric_id),
+                    _finite_float(
+                        raw_value,
+                        name=f"objective[{metric_id!r}]",
+                    ),
+                )
+            )
+        ordered.sort(key=lambda value: value[0])
+        if len({name for name, _ in ordered}) != len(ordered):
+            raise ValueError("objectives repeat a metric")
+
+        value = freeze_json(
+            {
+                "numeric_values": {
+                    metric_id: metric_value
+                    for metric_id, metric_value in ordered
+                },
+                "decimal_text": {
+                    metric_id: format(metric_value, ".17g")
+                    for metric_id, metric_value in ordered
+                },
+                "exact_binary64_hex": {
+                    metric_id: metric_value.hex()
+                    for metric_id, metric_value in ordered
+                },
+                "reasoning_representation": "ordinary_json_numbers",
+                "exact_hex_is_machine_audit_only": True,
+            }
+        )
+        if type(value) is not FrozenJsonObject:
+            raise TypeError("objective evidence must have an object root")
+        self.verify_point(value)
+        return value
+
+    def verify_point(
+        self,
+        evidence: FrozenJsonObject,
+    ) -> tuple[tuple[str, float], ...]:
+        """Authenticate all public representations and return exact values."""
+
+        if (
+            type(evidence) is not FrozenJsonObject
+            or freeze_json(evidence) is not evidence
+        ):
+            raise TypeError("evidence must be an exact frozen object")
+        record = thaw_json(evidence)
+        numeric = record.get("numeric_values")
+        decimal = record.get("decimal_text")
+        exact = record.get("exact_binary64_hex")
+        if not all(
+            isinstance(value, dict)
+            for value in (numeric, decimal, exact)
+        ):
+            raise ValueError("objective evidence representations are absent")
+        assert isinstance(numeric, dict)
+        assert isinstance(decimal, dict)
+        assert isinstance(exact, dict)
+        if not numeric or set(numeric) != set(decimal) or set(numeric) != set(exact):
+            raise ValueError("objective evidence metric sets differ")
+        verified: list[tuple[str, float]] = []
+        for metric_id in sorted(numeric):
+            name = _metric_id(metric_id)
+            value = _finite_float(
+                numeric[metric_id],
+                name=f"numeric_values[{name!r}]",
+            )
+            text = decimal[metric_id]
+            hex_value = exact[metric_id]
+            if type(text) is not str or type(hex_value) is not str:
+                raise TypeError("objective text/hex evidence must be strings")
+            try:
+                from_decimal = float(text)
+                from_hex = float.fromhex(hex_value)
+            except ValueError as error:
+                raise ValueError(
+                    "objective evidence contains an invalid representation"
+                ) from error
+            if (
+                not math.isfinite(from_decimal)
+                or not math.isfinite(from_hex)
+                or from_decimal.hex() != value.hex()
+                or from_hex.hex() != value.hex()
+                or text != format(value, ".17g")
+                or hex_value != value.hex()
+            ):
+                raise ValueError(
+                    "objective evidence representations are inconsistent"
+                )
+            verified.append((name, value))
+        if record.get("exact_hex_is_machine_audit_only") is not True:
+            raise ValueError("objective evidence omitted the hex warning")
+        return tuple(verified)
+
+
+__all__ = [
+    "TRUSTED_OBJECTIVE_EVIDENCE_CODEC_DEFINITION_SHA256",
+    "TRUSTED_OBJECTIVE_EVIDENCE_CODEC_ID",
+    "TRUSTED_OBJECTIVE_EVIDENCE_CODEC_VERSION",
+    "TrustedObjectiveEvidenceCodec",
+]