agentevolve-optimizer 0.5.0__py3-none-any.whl

agent_evolve/policies/selection/proposal_support.py

@@ -0,0 +1,368 @@
+"""Outcome-blind structural reservations inside a model-proposed slate.
+
+The model normally chooses a K-member proposal from a larger finite action
+contract.  Complete K8 outcome panels show that this truncation can remove the
+useful action before the evaluator allocator ever sees it.  This policy
+reserves two *proposal* positions for archive novelty and structural coverage.
+The reservations do not force an evaluator slot and are not quality rankings;
+the downstream allocator retains authority over the evaluated subset.
+
+All inputs are sealed before provider dispatch.  The policy reads no objective
+value, evaluator outcome, workload identifier, model profile, action name, or
+free-form memory text.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import math
+from dataclasses import dataclass, field
+from enum import Enum
+
+from agent_evolve.domain.patch import require_sha256
+
+
+POLICY_ID = "structural_proposal_support_reservation"
+POLICY_VERSION = 1
+POLICY_DEFINITION_SHA256 = hashlib.sha256(
+    b"agent-evolve:structural-proposal-support-reservation:v1;"
+    b"reservation-count=2;roles=archive-novelty,structural-coverage;"
+    b"first=lexicographic(novelty,coverage);"
+    b"second=prefer-distinct-family-and-locus-then-family-then-locus;"
+    b"proposal-reservation-only=true;evaluator-slot-authority=false;"
+    b"objective-values=false;outcomes=false;workload-and-model-fields=false"
+).hexdigest()
+
+_DECISION_DOMAIN = b"agent-evolve:proposal-support-reservation:decision:v1\x00"
+_RESERVATION_COUNT = 2
+
+
+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 _finite_unit(value: float, *, name: str) -> None:
+    if type(value) is not float or not math.isfinite(value):
+        raise TypeError(f"{name} must be a finite canonical float")
+    if not 0.0 <= value <= 1.0:
+        raise ValueError(f"{name} must lie in [0, 1]")
+
+
+@dataclass(frozen=True, slots=True)
+class ProposalSupportCandidate:
+    """One pre-provider structural row from the common candidate universe."""
+
+    option_id: str
+    option_identity_sha256: str
+    family: str
+    locus_key: str
+    phenotype_identity_sha256: str
+    frozen_archive_snapshot_sha256: str
+    structural_evidence_receipt_sha256: str
+    archive_novelty_score: float
+    structural_coverage_score: float
+
+    def __post_init__(self) -> None:
+        for name in ("option_id", "family", "locus_key"):
+            value = getattr(self, name)
+            if type(value) is not str or not value:
+                raise ValueError(f"{name} must be a non-empty string")
+        for name in (
+            "option_identity_sha256",
+            "phenotype_identity_sha256",
+            "frozen_archive_snapshot_sha256",
+            "structural_evidence_receipt_sha256",
+        ):
+            require_sha256(getattr(self, name), name)
+        _finite_unit(self.archive_novelty_score, name="archive_novelty_score")
+        _finite_unit(
+            self.structural_coverage_score,
+            name="structural_coverage_score",
+        )
+
+    def to_record(self) -> dict[str, object]:
+        self.__post_init__()
+        return {
+            "option_id": self.option_id,
+            "option_identity_sha256": self.option_identity_sha256,
+            "family": self.family,
+            "locus_key": self.locus_key,
+            "phenotype_identity_sha256": self.phenotype_identity_sha256,
+            "frozen_archive_snapshot_sha256": (
+                self.frozen_archive_snapshot_sha256
+            ),
+            "structural_evidence_receipt_sha256": (
+                self.structural_evidence_receipt_sha256
+            ),
+            "archive_novelty_score_hex": self.archive_novelty_score.hex(),
+            "structural_coverage_score_hex": (
+                self.structural_coverage_score.hex()
+            ),
+        }
+
+
+class ProposalSupportRole(str, Enum):
+    """Why one action is protected in the proposal rather than the evaluator."""
+
+    ARCHIVE_NOVELTY = "archive_novelty"
+    STRUCTURAL_COVERAGE = "structural_coverage"
+
+
+@dataclass(frozen=True, slots=True)
+class ProposalSupportReservation:
+    """One selected proposal-only reservation and its exact structural row."""
+
+    role: ProposalSupportRole
+    candidate: ProposalSupportCandidate
+
+    def __post_init__(self) -> None:
+        if type(self.role) is not ProposalSupportRole:
+            raise TypeError("role must be an exact ProposalSupportRole")
+        if type(self.candidate) is not ProposalSupportCandidate:
+            raise TypeError("candidate must be an exact ProposalSupportCandidate")
+        self.candidate.__post_init__()
+
+    def to_record(self) -> dict[str, object]:
+        self.__post_init__()
+        return {"role": self.role.value, "candidate": self.candidate.to_record()}
+
+
+def _select_reservations(
+    candidates: tuple[ProposalSupportCandidate, ...],
+) -> tuple[ProposalSupportReservation, ProposalSupportReservation]:
+    first = min(
+        candidates,
+        key=lambda value: (
+            -value.archive_novelty_score,
+            -value.structural_coverage_score,
+            value.option_id,
+        ),
+    )
+    remaining = tuple(value for value in candidates if value != first)
+    preference_pools = (
+        tuple(
+            value
+            for value in remaining
+            if value.family != first.family and value.locus_key != first.locus_key
+        ),
+        tuple(value for value in remaining if value.family != first.family),
+        tuple(value for value in remaining if value.locus_key != first.locus_key),
+        remaining,
+    )
+    second_pool = next(value for value in preference_pools if value)
+    second = min(
+        second_pool,
+        key=lambda value: (
+            -value.structural_coverage_score,
+            -value.archive_novelty_score,
+            value.option_id,
+        ),
+    )
+    return (
+        ProposalSupportReservation(ProposalSupportRole.ARCHIVE_NOVELTY, first),
+        ProposalSupportReservation(ProposalSupportRole.STRUCTURAL_COVERAGE, second),
+    )
+
+
+@dataclass(frozen=True, slots=True, eq=False)
+class ProposalSupportDecision:
+    """Replayable proposal-reservation decision over one exact common pool."""
+
+    request_sha256: str
+    common_candidate_pool_decision_sha256: str
+    model_selection_size: int
+    candidates: tuple[ProposalSupportCandidate, ...]
+    reservations: tuple[ProposalSupportReservation, ...]
+    policy_id: str = POLICY_ID
+    policy_version: int = POLICY_VERSION
+    policy_definition_sha256: str = POLICY_DEFINITION_SHA256
+    decision_sha256: str = field(init=False, default="")
+
+    def __post_init__(self) -> None:
+        require_sha256(self.request_sha256, "request_sha256")
+        require_sha256(
+            self.common_candidate_pool_decision_sha256,
+            "common_candidate_pool_decision_sha256",
+        )
+        require_sha256(self.policy_definition_sha256, "policy_definition_sha256")
+        if (
+            self.policy_id != POLICY_ID
+            or self.policy_version != POLICY_VERSION
+            or self.policy_definition_sha256 != POLICY_DEFINITION_SHA256
+        ):
+            raise ValueError("proposal-support policy identity drifted")
+        if type(self.model_selection_size) is not int or self.model_selection_size < 4:
+            raise ValueError("model_selection_size must be an exact integer >= 4")
+        if type(self.candidates) is not tuple or len(self.candidates) < (
+            _RESERVATION_COUNT
+        ):
+            raise ValueError("candidates must contain at least two exact rows")
+        if any(type(value) is not ProposalSupportCandidate for value in self.candidates):
+            raise TypeError("candidates must contain exact structural rows")
+        for value in self.candidates:
+            value.__post_init__()
+        if self.candidates != tuple(
+            sorted(self.candidates, key=lambda value: value.option_id)
+        ):
+            raise ValueError("candidates must preserve canonical option order")
+        if len({value.option_id for value in self.candidates}) != len(self.candidates):
+            raise ValueError("candidates cannot repeat an option")
+        if len(self.candidates) < self.model_selection_size:
+            raise ValueError("model selection exceeds the candidate universe")
+        snapshots = {
+            value.frozen_archive_snapshot_sha256 for value in self.candidates
+        }
+        if len(snapshots) != 1:
+            raise ValueError("proposal-support candidates must share one archive cutoff")
+        if type(self.reservations) is not tuple or len(self.reservations) != (
+            _RESERVATION_COUNT
+        ):
+            raise ValueError("reservations must contain the exact two roles")
+        if any(
+            type(value) is not ProposalSupportReservation
+            for value in self.reservations
+        ):
+            raise TypeError("reservations must contain exact reservation rows")
+        for value in self.reservations:
+            value.__post_init__()
+        if tuple(value.role for value in self.reservations) != tuple(
+            ProposalSupportRole
+        ):
+            raise ValueError("reservations must preserve the closed role order")
+        if len({value.candidate.option_id for value in self.reservations}) != (
+            _RESERVATION_COUNT
+        ):
+            raise ValueError("proposal-support reservations must be distinct")
+        if self.reservations != _select_reservations(self.candidates):
+            raise ValueError("reservations differ from the structural policy")
+        computed = hashlib.sha256(
+            _DECISION_DOMAIN + _canonical_json(self._unsigned_record())
+        ).hexdigest()
+        if self.decision_sha256 not in ("", computed):
+            raise ValueError("decision_sha256 does not authenticate the decision")
+        object.__setattr__(self, "decision_sha256", computed)
+
+    @property
+    def required_option_ids(self) -> tuple[str, ...]:
+        self.__post_init__()
+        return tuple(
+            sorted(value.candidate.option_id for value in self.reservations)
+        )
+
+    @property
+    def membership_constraint_effective(self) -> bool:
+        self.__post_init__()
+        return len(self.candidates) > self.model_selection_size
+
+    def _unsigned_record(self) -> dict[str, object]:
+        return {
+            "schema_version": 1,
+            "request_sha256": self.request_sha256,
+            "common_candidate_pool_decision_sha256": (
+                self.common_candidate_pool_decision_sha256
+            ),
+            "model_selection_size": self.model_selection_size,
+            "candidates": [value.to_record() for value in self.candidates],
+            "reservations": [value.to_record() for value in self.reservations],
+            "required_option_ids": [
+                value.candidate.option_id for value in self.reservations
+            ],
+            "policy": {
+                "policy_id": self.policy_id,
+                "policy_version": self.policy_version,
+                "definition_sha256": self.policy_definition_sha256,
+            },
+            "evaluator_slot_authority": False,
+            "objective_or_outcome_values_consulted": False,
+            "workload_or_model_fields_consulted": False,
+        }
+
+    def to_record(self) -> dict[str, object]:
+        self.__post_init__()
+        return {**self._unsigned_record(), "decision_sha256": self.decision_sha256}
+
+    def to_prompt_record(self) -> dict[str, object]:
+        self.__post_init__()
+        return {
+            "schema_version": 1,
+            "decision_sha256": self.decision_sha256,
+            "required_option_ids": list(self.required_option_ids),
+            "reservation_roles": [value.role.value for value in self.reservations],
+            "reservations_are_quality_rankings": False,
+            "reservations_force_evaluator_slots": False,
+            "model_may_rank_reserved_options_anywhere": True,
+        }
+
+    def __eq__(self, other: object) -> bool:
+        return (
+            type(other) is ProposalSupportDecision
+            and self.decision_sha256 == other.decision_sha256
+        )
+
+    __hash__ = None
+
+
+@dataclass(frozen=True, slots=True)
+class StructuralProposalSupportPolicy:
+    """Reserve two structurally complementary candidates in the model slate."""
+
+    policy_id: str = POLICY_ID
+    policy_version: int = POLICY_VERSION
+    definition_sha256: str = POLICY_DEFINITION_SHA256
+
+    def __post_init__(self) -> None:
+        if (
+            self.policy_id != POLICY_ID
+            or self.policy_version != POLICY_VERSION
+            or self.definition_sha256 != POLICY_DEFINITION_SHA256
+        ):
+            raise ValueError("proposal-support policy identity drifted")
+
+    def select(
+        self,
+        *,
+        request_sha256: str,
+        common_candidate_pool_decision_sha256: str,
+        model_selection_size: int,
+        candidates: tuple[ProposalSupportCandidate, ...],
+    ) -> ProposalSupportDecision:
+        self.__post_init__()
+        canonical = tuple(sorted(candidates, key=lambda value: value.option_id))
+        return ProposalSupportDecision(
+            request_sha256=request_sha256,
+            common_candidate_pool_decision_sha256=(
+                common_candidate_pool_decision_sha256
+            ),
+            model_selection_size=model_selection_size,
+            candidates=canonical,
+            reservations=_select_reservations(canonical),
+        )
+
+    def to_record(self) -> dict[str, object]:
+        self.__post_init__()
+        return {
+            "policy_id": self.policy_id,
+            "policy_version": self.policy_version,
+            "definition_sha256": self.definition_sha256,
+            "reservation_count": _RESERVATION_COUNT,
+            "evaluator_slot_authority": False,
+        }
+
+
+__all__ = [
+    "POLICY_DEFINITION_SHA256",
+    "POLICY_ID",
+    "POLICY_VERSION",
+    "ProposalSupportCandidate",
+    "ProposalSupportDecision",
+    "ProposalSupportReservation",
+    "ProposalSupportRole",
+    "StructuralProposalSupportPolicy",
+]

agent_evolve/policies/selection/random_portfolio.py

@@ -0,0 +1,254 @@
+"""Outcome-blind, replayable random portfolios over sealed finite options.
+
+The policy is a reusable scientific control for ranked portfolio evolution.  It
+uses only the request identity, option families, and exact parent-relative
+patch paths.  It never reads objective values, option prose, card payloads, or
+previous outcomes.  A task-keyed deterministic shuffle plus bounded
+backtracking finds a portfolio whose member patches are pairwise disjoint and
+whose family count satisfies the request contract.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import random
+from dataclasses import dataclass, field
+from decimal import Decimal
+
+from agent_evolve.domain.ids import CandidateId
+from agent_evolve.domain.patch import ArrayIndex, JsonPath, ObjectKey, require_sha256
+from agent_evolve.policies.variation.typed_patch import derive_patch
+from agent_evolve.ports.agentic_generator import (
+    AgenticCallTelemetry,
+    MetricEffectDirection,
+    MetricEffectPrediction,
+)
+from agent_evolve.ports.portfolio_selection import (
+    PortfolioMemberDraft,
+    PortfolioSelectionRequest,
+    PortfolioSelectionResult,
+    resolve_ranked_portfolio_decision,
+)
+
+
+POLICY_ID = "deterministic_random_feasible_portfolio"
+POLICY_VERSION = 1
+_POLICY_DEFINITION = {
+    "schema_id": "agent_evolve_random_feasible_portfolio_v1",
+    "entropy": "sha256(base_seed, call_id, finite_contract_identity_sha256)",
+    "ordering": "python_random_shuffle_then_bounded_depth_first_search",
+    "admitted_option_fields": ["family", "child_configuration"],
+    "admitted_request_fields": [
+        "portfolio_size",
+        "min_distinct_families",
+        "required_metric_ids",
+        "require_supporting_cards",
+        "card_keys",
+        "call_id",
+        "finite_contract_identity_sha256",
+    ],
+    "path_constraint": "all_member_patch_paths_pairwise_nonoverlapping",
+    "predictions": "all_unknown",
+    "forbidden_inputs": [
+        "objective_values",
+        "prior_outcomes",
+        "option_descriptions",
+        "option_metadata",
+        "card_payloads",
+        "card_scores",
+    ],
+}
+POLICY_DEFINITION_SHA256 = hashlib.sha256(
+    b"agent-evolve:random-feasible-portfolio-policy:v1\x00"
+    + json.dumps(
+        _POLICY_DEFINITION,
+        ensure_ascii=True,
+        allow_nan=False,
+        separators=(",", ":"),
+        sort_keys=True,
+    ).encode("ascii")
+).hexdigest()
+_PARENT_ID = CandidateId("candidate_0000000000000001")
+_CHILD_ID = CandidateId("candidate_0000000000000002")
+
+
+def _paths_overlap(first: JsonPath, second: JsonPath) -> bool:
+    return first.is_prefix_of(second) or second.is_prefix_of(first)
+
+
+def _path_text(path: JsonPath) -> str:
+    parts = ["$"]
+    for segment in path.segments:
+        if type(segment) is ObjectKey:
+            parts.append(f".{segment.value}")
+        elif type(segment) is ArrayIndex:
+            parts.append(f"[{segment.value}]")
+        else:  # pragma: no cover - JsonPath validates the closed segment union.
+            raise AssertionError("unsupported JSON-path segment")
+    return "".join(parts)
+
+
+@dataclass(frozen=True, slots=True)
+class _OptionRow:
+    option_id: str
+    family: str
+    paths: tuple[JsonPath, ...]
+
+
+def _option_rows(request: PortfolioSelectionRequest) -> tuple[_OptionRow, ...]:
+    parent = request.finite_variation_contract.parent_configuration
+    rows: list[_OptionRow] = []
+    for option in request.finite_variation_contract.options:
+        patch = derive_patch(
+            parent,
+            option.child_configuration,
+            base_candidate_id=_PARENT_ID,
+            target_candidate_id=_CHILD_ID,
+        )
+        paths = tuple(
+            sorted(
+                {operation.path for operation in patch.operations},
+                key=_path_text,
+            )
+        )
+        if not paths:
+            raise ValueError("finite option materialized no parent-relative path")
+        rows.append(_OptionRow(option.option_id, option.family, paths))
+    return tuple(rows)
+
+
+def _disjoint(paths: tuple[JsonPath, ...], selected: tuple[_OptionRow, ...]) -> bool:
+    return not any(
+        _paths_overlap(path, previous)
+        for row in selected
+        for path in paths
+        for previous in row.paths
+    )
+
+
+def _select_rows(
+    request: PortfolioSelectionRequest,
+    *,
+    seed: int,
+) -> tuple[_OptionRow, ...]:
+    rows = list(_option_rows(request))
+    entropy = hashlib.sha256(
+        b"agent-evolve:random-feasible-portfolio-entropy:v1\x00"
+        + seed.to_bytes(16, "big", signed=True)
+        + request.call_id.value.encode("ascii", errors="strict")
+        + bytes.fromhex(request.finite_variation_contract.identity_sha256)
+    ).digest()
+    random.Random(int.from_bytes(entropy, "big", signed=False)).shuffle(rows)
+    required_families = request.min_distinct_families or 1
+    target_size = request.portfolio_size
+
+    def search(
+        start: int,
+        selected: tuple[_OptionRow, ...],
+        families: frozenset[str],
+    ) -> tuple[_OptionRow, ...] | None:
+        if len(selected) == target_size:
+            return selected if len(families) >= required_families else None
+        remaining_slots = target_size - len(selected)
+        if len(rows) - start < remaining_slots:
+            return None
+        possible_families = families | frozenset(row.family for row in rows[start:])
+        if len(possible_families) < required_families:
+            return None
+        for index in range(start, len(rows)):
+            row = rows[index]
+            if not _disjoint(row.paths, selected):
+                continue
+            result = search(
+                index + 1,
+                (*selected, row),
+                families | {row.family},
+            )
+            if result is not None:
+                return result
+        return None
+
+    selected = search(0, (), frozenset())
+    if selected is None:
+        raise ValueError(
+            "sealed finite contract has no path-disjoint portfolio satisfying "
+            "the requested size and family constraints"
+        )
+    return selected
+
+
+@dataclass(frozen=True, slots=True)
+class DeterministicRandomFeasiblePortfolioPolicy:
+    """Select a path-disjoint random portfolio without observing outcomes."""
+
+    seed: int
+    policy_id: str = field(init=False, default=POLICY_ID)
+    policy_version: int = field(init=False, default=POLICY_VERSION)
+    policy_definition_sha256: str = field(
+        init=False,
+        default=POLICY_DEFINITION_SHA256,
+    )
+
+    def __post_init__(self) -> None:
+        if type(self.seed) is not int or not -(1 << 127) <= self.seed < (1 << 127):
+            raise ValueError("seed must be an exact signed int128")
+        require_sha256(self.policy_definition_sha256, "policy_definition_sha256")
+
+    async def select(
+        self,
+        request: PortfolioSelectionRequest,
+    ) -> PortfolioSelectionResult:
+        if type(request) is not PortfolioSelectionRequest:
+            raise TypeError("request must be an exact PortfolioSelectionRequest")
+        request.__post_init__()
+        rows = _select_rows(request, seed=self.seed)
+        card_keys = tuple(card.card_key for card in request.cards)
+        supporting = (card_keys[0],) if request.require_supporting_cards else ()
+        predictions = tuple(
+            MetricEffectPrediction(metric_id, MetricEffectDirection.UNKNOWN)
+            for metric_id in request.required_metric_ids
+        )
+        drafts = tuple(
+            PortfolioMemberDraft(
+                option_id=row.option_id,
+                supporting_card_keys=supporting,
+                effect_predictions=predictions,
+                design_rationale=(
+                    "Outcome-blind deterministic random control selected this "
+                    "sealed option under exact family and path constraints."
+                ),
+            )
+            for row in rows
+        )
+        decision = resolve_ranked_portfolio_decision(
+            request,
+            drafts,
+            policy_id=self.policy_id,
+            policy_version=self.policy_version,
+            policy_definition_sha256=self.policy_definition_sha256,
+        )
+        telemetry = AgenticCallTelemetry(
+            requested_model="provider-free-random-policy",
+            resolved_model="provider-free-random-policy",
+            resolved_provider="local-deterministic-control",
+            provider_response_id=None,
+            finish_reason="policy_completed",
+            input_tokens=0,
+            output_tokens=0,
+            reasoning_tokens=0,
+            cache_read_tokens=0,
+            cache_write_tokens=0,
+            cost_usd=Decimal("0"),
+            latency_ns=0,
+            attempt_count=1,
+        )
+        return PortfolioSelectionResult(decision=decision, telemetry=telemetry)
+
+
+__all__ = [
+    "DeterministicRandomFeasiblePortfolioPolicy",
+    "POLICY_DEFINITION_SHA256",
+    "POLICY_ID",
+    "POLICY_VERSION",
+]