agentevolve-optimizer 0.5.0__py3-none-any.whl

agent_evolve/policies/selection/full_support_slate.py

@@ -0,0 +1,91 @@
+"""Quality-first allocation that evaluates an entire calibrated slate.
+
+The model-facing proposal contract and the evaluator-facing portfolio width
+are deliberately separate concerns.  This policy closes that gap by selecting
+every authenticated proposal in model order.  It is useful while a campaign is
+still collecting enough outcome evidence to justify a narrower learned
+allocator, and it avoids silently converting proposal quality into an
+allocation failure.
+
+The policy is workload neutral: it sees only :class:`SlateAllocationRequest`
+and never inspects option names, workload identifiers, configurations, or
+outcomes.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass
+
+from agent_evolve.policies.selection.calibrated_slate import (
+    SlateAllocationDecision,
+    SlateAllocationMode,
+    SlateAllocationRequest,
+    TraceCalibratedSlatePolicy,
+)
+
+
+POLICY_ID = "full_support_calibrated_slate"
+POLICY_VERSION = 1
+POLICY_DEFINITION_SHA256 = hashlib.sha256(
+    b"agent-evolve:full-support-calibrated-slate:v1;"
+    b"select-entire-authenticated-slate=true;model-order-preserved=true;"
+    b"outcome-blind=true;workload-identifiers-unused=true;"
+    b"quality-first-evidence-acquisition=true"
+).hexdigest()
+CONFIGURATION_SHA256 = hashlib.sha256(
+    b"agent-evolve:full-support-calibrated-slate-configuration:v1;"
+    b"selection-scope=entire-authenticated-slate;"
+    b"outcome-access=false;workload-identifier-access=false"
+).hexdigest()
+
+
+@dataclass(frozen=True, slots=True)
+class FullSupportSlatePolicy:
+    """Select every member of a finite calibrated slate in model order."""
+
+    policy_id = POLICY_ID
+    policy_version = POLICY_VERSION
+    definition_sha256 = POLICY_DEFINITION_SHA256
+    configuration_sha256 = CONFIGURATION_SHA256
+
+    def __post_init__(self) -> None:
+        if type(self) is not FullSupportSlatePolicy:
+            raise TypeError("full-support policy must be exact")
+
+    def revalidate(self) -> None:
+        self.__post_init__()
+
+    def select(self, request: SlateAllocationRequest) -> SlateAllocationDecision:
+        self.__post_init__()
+        if type(request) is not SlateAllocationRequest:
+            raise TypeError("request must be exact SlateAllocationRequest")
+        request.revalidate()
+        if request.portfolio_size != len(request.slate.members):
+            raise ValueError(
+                "full-support allocation requires portfolio_size equal to slate size"
+            )
+        return TraceCalibratedSlatePolicy(
+            SlateAllocationMode.DIRECT_MODEL_TOP_K
+        ).select(request)
+
+    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,
+            "configuration_sha256": self.configuration_sha256,
+            "selection_scope": "entire_authenticated_slate",
+            "outcome_access": False,
+            "workload_identifier_access": False,
+        }
+
+
+__all__ = [
+    "CONFIGURATION_SHA256",
+    "POLICY_DEFINITION_SHA256",
+    "POLICY_ID",
+    "POLICY_VERSION",
+    "FullSupportSlatePolicy",
+]

agent_evolve/policies/selection/meaningful_direction.py

@@ -0,0 +1,240 @@
+"""Workload-neutral adjudication of meaningful metric directions.
+
+Benchmarks publish one explicit absolute resolution per metric. The policy
+turns an exact parent/child contrast into the categorical vocabulary used by
+forecast calibration. This is an identified scientific policy, not a
+universal floating-point epsilon.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import math
+import re
+from dataclasses import dataclass, field
+
+from agent_evolve.core.optimization_semantics import OptimizationSemantics
+from agent_evolve.domain.patch import require_sha256
+from agent_evolve.policies.selection.forecast_calibration import (
+    MeaningfulDirectionAdjudicationReceipt,
+    MeaningfulDirectionRequest,
+)
+from agent_evolve.ports.agentic_generator import MetricEffectDirection
+from agent_evolve.ports.decision_metric_projection import DecisionMetricProjection
+
+
+_METRIC = re.compile(r"^[a-z][a-z0-9_.:-]{0,191}$")
+_DEFINITION_DOMAIN = b"agent-evolve:absolute-metric-direction:def:v1\x00"
+POLICY_ID = "absolute_tolerance_metric_direction"
+POLICY_VERSION = 1
+
+
+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 MetricDirectionResolution:
+    """One metric's prospectively declared indistinguishable change band."""
+
+    metric_id: str
+    absolute_tolerance: float
+
+    def __post_init__(self) -> None:
+        if type(self.metric_id) is not str or _METRIC.fullmatch(self.metric_id) is None:
+            raise ValueError("metric_id must use the closed metric grammar")
+        if (
+            type(self.absolute_tolerance) is not float
+            or not math.isfinite(self.absolute_tolerance)
+            or self.absolute_tolerance < 0.0
+        ):
+            raise ValueError("absolute_tolerance must be a finite non-negative float")
+
+    def to_record(self) -> dict[str, str]:
+        self.__post_init__()
+        return {
+            "metric_id": self.metric_id,
+            "absolute_tolerance_hex": self.absolute_tolerance.hex(),
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class AbsoluteToleranceDirectionAdjudicator:
+    """Classify exact parent/child deltas under declared metric resolutions."""
+
+    benchmark_sha256: str
+    session_sha256: str
+    resolutions: tuple[MetricDirectionResolution, ...]
+    policy_id: str = field(init=False, default=POLICY_ID)
+    policy_version: int = field(init=False, default=POLICY_VERSION)
+    definition_sha256: str = field(init=False, default="")
+
+    def __post_init__(self) -> None:
+        require_sha256(self.benchmark_sha256, "benchmark_sha256")
+        require_sha256(self.session_sha256, "session_sha256")
+        if (
+            type(self.resolutions) is not tuple
+            or not self.resolutions
+            or any(
+                type(value) is not MetricDirectionResolution
+                for value in self.resolutions
+            )
+        ):
+            raise ValueError("resolutions must contain exact metric resolutions")
+        for value in self.resolutions:
+            value.__post_init__()
+        if self.resolutions != tuple(
+            sorted(self.resolutions, key=lambda value: value.metric_id)
+        ):
+            raise ValueError("resolutions must use canonical metric order")
+        if len({value.metric_id for value in self.resolutions}) != len(
+            self.resolutions
+        ):
+            raise ValueError("resolutions cannot repeat a metric")
+        definition = {
+            "schema_version": 1,
+            "policy_id": self.policy_id,
+            "policy_version": self.policy_version,
+            "comparison": "absolute_child_minus_parent",
+            "unchanged_rule": "absolute_delta_lte_declared_tolerance",
+            "resolutions": [value.to_record() for value in self.resolutions],
+        }
+        computed = hashlib.sha256(
+            _DEFINITION_DOMAIN + _canonical_json(definition)
+        ).hexdigest()
+        if self.definition_sha256 not in ("", computed):
+            raise ValueError("definition_sha256 differs from the resolution policy")
+        object.__setattr__(self, "definition_sha256", computed)
+
+    @classmethod
+    def from_optimization_semantics(
+        cls,
+        *,
+        benchmark_sha256: str,
+        session_sha256: str,
+        semantics: OptimizationSemantics,
+    ) -> "AbsoluteToleranceDirectionAdjudicator":
+        """Bind every projected decision metric with an explicit tolerance.
+
+        Objective-only semantics retain the historical unprefixed objective
+        names. Mixed objective/violation/constraint semantics use their exact
+        role-prefixed IDs through :class:`DecisionMetricProjection`.
+        """
+
+        if type(semantics) is not OptimizationSemantics:
+            raise TypeError("semantics must be exact OptimizationSemantics")
+        semantics.__post_init__()
+        return cls.from_decision_metric_projection(
+            benchmark_sha256=benchmark_sha256,
+            session_sha256=session_sha256,
+            projection=DecisionMetricProjection.from_optimization_semantics(semantics),
+        )
+
+    @classmethod
+    def from_decision_metric_projection(
+        cls,
+        *,
+        benchmark_sha256: str,
+        session_sha256: str,
+        projection: DecisionMetricProjection,
+    ) -> "AbsoluteToleranceDirectionAdjudicator":
+        """Construct the adjudicator from the same projection used at feedback."""
+
+        if type(projection) is not DecisionMetricProjection:
+            raise TypeError("projection must be exact DecisionMetricProjection")
+        projection.__post_init__()
+        missing = tuple(
+            metric.metric_id
+            for metric in projection.metrics
+            if metric.absolute_tolerance is None
+        )
+        if missing:
+            raise ValueError(
+                "decision metrics require explicit direction tolerances: "
+                + ", ".join(sorted(missing))
+            )
+        return cls(
+            benchmark_sha256=benchmark_sha256,
+            session_sha256=session_sha256,
+            resolutions=tuple(
+                sorted(
+                    (
+                        MetricDirectionResolution(
+                            metric_id=metric.metric_id,
+                            absolute_tolerance=float(metric.absolute_tolerance),
+                        )
+                        for metric in projection.metrics
+                    ),
+                    key=lambda value: value.metric_id,
+                )
+            ),
+        )
+
+    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,
+            "benchmark_sha256": self.benchmark_sha256,
+            "session_sha256": self.session_sha256,
+            "resolutions": [value.to_record() for value in self.resolutions],
+        }
+
+    def adjudicate(
+        self,
+        request: MeaningfulDirectionRequest,
+    ) -> MeaningfulDirectionAdjudicationReceipt:
+        self.__post_init__()
+        if type(request) is not MeaningfulDirectionRequest:
+            raise TypeError("request must be exact MeaningfulDirectionRequest")
+        request.revalidate()
+        if (
+            request.benchmark_sha256 != self.benchmark_sha256
+            or request.session_sha256 != self.session_sha256
+        ):
+            raise ValueError("direction request belongs to a foreign benchmark session")
+        tolerance_by_metric = {
+            value.metric_id: value.absolute_tolerance for value in self.resolutions
+        }
+        if request.metric_id not in tolerance_by_metric:
+            raise ValueError("direction request names an undeclared metric")
+        delta = request.child_metric_value - request.parent_metric_value
+        tolerance = tolerance_by_metric[request.metric_id]
+        if abs(delta) <= tolerance:
+            direction = MetricEffectDirection.UNCHANGED
+        elif delta < 0.0:
+            direction = MetricEffectDirection.DECREASE
+        else:
+            direction = MetricEffectDirection.INCREASE
+        return MeaningfulDirectionAdjudicationReceipt(
+            request_sha256=request.request_sha256,
+            benchmark_sha256=request.benchmark_sha256,
+            session_sha256=request.session_sha256,
+            wave_index=request.wave_index,
+            parent_candidate_identity_sha256=(request.parent_candidate_identity_sha256),
+            option_id=request.option_id,
+            option_identity_sha256=request.option_identity_sha256,
+            metric_id=request.metric_id,
+            parent_outcome_sha256=request.parent_outcome_sha256,
+            child_outcome_sha256=request.child_outcome_sha256,
+            actual_direction=direction,
+            adjudicator_policy_id=self.policy_id,
+            adjudicator_policy_version=self.policy_version,
+            adjudicator_definition_sha256=self.definition_sha256,
+        )
+
+
+__all__ = [
+    "AbsoluteToleranceDirectionAdjudicator",
+    "MetricDirectionResolution",
+    "POLICY_ID",
+    "POLICY_VERSION",
+]

agent_evolve/policies/selection/memory_dose_feasibility.py

@@ -0,0 +1,259 @@
+"""Workload-neutral exact feasibility for bounded memory-dose attribution.
+
+The portfolio reconciler must know whether a structural evaluation subset can
+also carry the prospectively declared card dose.  This module answers only
+that finite constraint question.  It never sees objective values, workload
+identifiers, model/provider metadata, or natural-language card content.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass, field
+from itertools import combinations
+
+from agent_evolve.domain.patch import require_sha256
+from agent_evolve.ports.portfolio_memory_dose import (
+    BoundedPortfolioMemoryDoseContract,
+    PortfolioMemoryDoseStage,
+)
+
+
+POLICY_ID = "exact_bounded_memory_dose_attribution_feasibility"
+POLICY_VERSION = 1
+POLICY_DEFINITION_SHA256 = hashlib.sha256(
+    b"agent-evolve:exact-bounded-memory-dose-attribution-feasibility:v1;"
+    b"input=finite-option-identities,bounded-card-support-contract,stage;"
+    b"constraints=compatibility,member-bounds,unattributed-floor,max-cards,card-cover;"
+    b"objective=first-canonical-minimum-dose-witness;"
+    b"objective-values=false;workload-model-provider-identifiers=false"
+).hexdigest()
+_DOMAIN = b"agent-evolve:memory-dose-attribution-feasibility-witness: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 MemoryDoseAttributionFeasibilityWitness:
+    """One exact card assignment for a fixed finite member subset."""
+
+    contract_sha256: str
+    stage: PortfolioMemoryDoseStage
+    member_option_identities: tuple[tuple[str, str], ...]
+    attributions: tuple[tuple[str, tuple[str, ...]], ...]
+    witness_sha256: str = field(init=False)
+
+    def __post_init__(self) -> None:
+        require_sha256(self.contract_sha256, "contract_sha256")
+        if type(self.stage) is not PortfolioMemoryDoseStage:
+            raise TypeError("stage must be exact PortfolioMemoryDoseStage")
+        if type(self.member_option_identities) is not tuple or any(
+            type(value) is not tuple
+            or len(value) != 2
+            or type(value[0]) is not str
+            or not value[0]
+            or type(value[1]) is not str
+            for value in self.member_option_identities
+        ):
+            raise TypeError("member_option_identities must contain exact pairs")
+        for _, identity_sha256 in self.member_option_identities:
+            require_sha256(identity_sha256, "option_identity_sha256")
+        if self.member_option_identities != tuple(
+            sorted(set(self.member_option_identities))
+        ):
+            raise ValueError(
+                "member_option_identities must be unique and canonical"
+            )
+        option_ids = tuple(value[0] for value in self.member_option_identities)
+        identity_sha256s = tuple(
+            value[1] for value in self.member_option_identities
+        )
+        if len(set(option_ids)) != len(option_ids):
+            raise ValueError("member option IDs must be unique")
+        if len(set(identity_sha256s)) != len(identity_sha256s):
+            raise ValueError("member option identities must be unique")
+        if type(self.attributions) is not tuple or any(
+            type(value) is not tuple
+            or len(value) != 2
+            or type(value[0]) is not str
+            or not value[0]
+            or type(value[1]) is not tuple
+            or any(type(card) is not str or not card for card in value[1])
+            or value[1] != tuple(sorted(set(value[1])))
+            for value in self.attributions
+        ):
+            raise TypeError("attributions must contain canonical exact values")
+        if tuple(value[0] for value in self.attributions) != tuple(
+            value[0] for value in self.member_option_identities
+        ):
+            raise ValueError("attributions differ from the witnessed members")
+        object.__setattr__(
+            self,
+            "witness_sha256",
+            hashlib.sha256(_DOMAIN + _canonical_json(self._unsigned_record())).hexdigest(),
+        )
+
+    @property
+    def supported_member_count(self) -> int:
+        return sum(bool(cards) for _, cards in self.attributions)
+
+    @property
+    def unattributed_member_count(self) -> int:
+        return len(self.attributions) - self.supported_member_count
+
+    @property
+    def covered_card_keys(self) -> tuple[str, ...]:
+        return tuple(
+            sorted({card for _, cards in self.attributions for card in cards})
+        )
+
+    def _unsigned_record(self) -> dict[str, object]:
+        return {
+            "schema_version": 1,
+            "policy": {
+                "policy_id": POLICY_ID,
+                "policy_version": POLICY_VERSION,
+                "definition_sha256": POLICY_DEFINITION_SHA256,
+            },
+            "contract_sha256": self.contract_sha256,
+            "stage": self.stage.value,
+            "members": [
+                {
+                    "option_id": option_id,
+                    "option_identity_sha256": identity_sha256,
+                    "supporting_card_keys": list(cards),
+                }
+                for (option_id, identity_sha256), (_, cards) in zip(
+                    self.member_option_identities,
+                    self.attributions,
+                    strict=True,
+                )
+            ],
+            "supported_member_count": self.supported_member_count,
+            "unattributed_member_count": self.unattributed_member_count,
+            "covered_card_keys": list(self.covered_card_keys),
+            "objective_values_consulted": False,
+            "workload_model_provider_identifiers_consulted": False,
+        }
+
+    def to_record(self) -> dict[str, object]:
+        self.__post_init__()
+        return {**self._unsigned_record(), "witness_sha256": self.witness_sha256}
+
+
+def find_memory_dose_attribution_feasibility_witness(
+    contract: BoundedPortfolioMemoryDoseContract,
+    *,
+    stage: PortfolioMemoryDoseStage,
+    member_option_identities: tuple[tuple[str, str], ...],
+) -> MemoryDoseAttributionFeasibilityWitness | None:
+    """Return the first canonical exact attribution, or ``None`` if impossible."""
+
+    if type(contract) is not BoundedPortfolioMemoryDoseContract:
+        raise TypeError("contract must be exact BoundedPortfolioMemoryDoseContract")
+    contract.__post_init__()
+    if type(stage) is not PortfolioMemoryDoseStage:
+        raise TypeError("stage must be exact PortfolioMemoryDoseStage")
+    if type(member_option_identities) is not tuple or any(
+        type(value) is not tuple or len(value) != 2 for value in member_option_identities
+    ):
+        raise TypeError("member_option_identities must contain exact pairs")
+    members = tuple(sorted(member_option_identities))
+    # Construction performs the complete boundary validation once.
+    provisional = MemoryDoseAttributionFeasibilityWitness(
+        contract_sha256=contract.contract_sha256,
+        stage=stage,
+        member_option_identities=members,
+        attributions=tuple((option_id, ()) for option_id, _ in members),
+    )
+    del provisional
+
+    lower, upper = contract.bounds_for(stage)
+    maximum_supported = min(
+        upper,
+        len(members) - contract.minimum_unattributed_for(stage),
+    )
+    if lower > maximum_supported:
+        return None
+    assigned_cards = contract.assigned_card_keys
+    support_by_card = {value.card_key: value for value in contract.card_supports}
+    choices: list[tuple[tuple[str, ...], ...]] = []
+    for option_id, identity_sha256 in members:
+        compatible = tuple(
+            card_key
+            for card_key in assigned_cards
+            if support_by_card[card_key].supports(option_id, identity_sha256)
+        )
+        option_choices: list[tuple[str, ...]] = [()]
+        for count in range(
+            1,
+            min(len(compatible), contract.maximum_cards_per_member) + 1,
+        ):
+            option_choices.extend(combinations(compatible, count))
+        choices.append(tuple(option_choices))
+
+    selected: list[tuple[str, ...]] = []
+    result: MemoryDoseAttributionFeasibilityWitness | None = None
+
+    def search(index: int, supported_count: int, covered: frozenset[str]) -> bool:
+        nonlocal result
+        remaining = len(members) - index
+        if supported_count > maximum_supported:
+            return False
+        if supported_count + remaining < lower:
+            return False
+        if contract.require_every_assigned_card:
+            future_cover = set(covered)
+            for future_choices in choices[index:]:
+                for candidate in future_choices:
+                    future_cover.update(candidate)
+            if not set(assigned_cards).issubset(future_cover):
+                return False
+        if index == len(members):
+            if not lower <= supported_count <= maximum_supported:
+                return False
+            if contract.require_every_assigned_card and set(covered) != set(
+                assigned_cards
+            ):
+                return False
+            result = MemoryDoseAttributionFeasibilityWitness(
+                contract_sha256=contract.contract_sha256,
+                stage=stage,
+                member_option_identities=members,
+                attributions=tuple(
+                    (option_id, cards)
+                    for (option_id, _), cards in zip(members, selected, strict=True)
+                ),
+            )
+            return True
+        for candidate in choices[index]:
+            selected.append(candidate)
+            if search(
+                index + 1,
+                supported_count + bool(candidate),
+                covered.union(candidate),
+            ):
+                return True
+            selected.pop()
+        return False
+
+    search(0, 0, frozenset())
+    return result
+
+
+__all__ = [
+    "MemoryDoseAttributionFeasibilityWitness",
+    "POLICY_DEFINITION_SHA256",
+    "POLICY_ID",
+    "POLICY_VERSION",
+    "find_memory_dose_attribution_feasibility_witness",
+]