agentevolve-optimizer 0.5.0__py3-none-any.whl

agent_evolve/application/action_allocation_frame_commit_v3.py

@@ -0,0 +1,184 @@
+"""Durable fail-closed phase commits for operational allocator-v3 waves."""
+
+from __future__ import annotations
+
+from agent_evolve.application.two_stage_action_evolution import (
+    TwoStageActionPhase,
+    TwoStageActionPhaseCommit,
+    TwoStageActionPhaseReceipt,
+)
+from agent_evolve.domain.patch import require_sha256
+from agent_evolve.domain.typed_json import (
+    FrozenJsonObject,
+    freeze_json,
+    thaw_json,
+    typed_json_sha256,
+)
+from agent_evolve.ports.action_allocation_frame_commit_v3 import (
+    OperationalFrameActionAllocationCommitInput,
+    OperationalFrameActionAllocationTreatmentExecution,
+)
+from agent_evolve.ports.treatment_assignment import (
+    ProspectiveTreatmentAssignmentReceipt,
+)
+
+
+_COMMIT_KIND = "operational_tie_frame_action_allocation_v3"
+
+
+class OperationalFrameActionAllocationCommitRejected(RuntimeError):
+    """No evaluator authority may open from these allocator-v3 executions."""
+
+
+def _validated_execution_tuple(
+    executions: tuple[OperationalFrameActionAllocationTreatmentExecution, ...],
+    *,
+    require_all_pass: bool,
+) -> ProspectiveTreatmentAssignmentReceipt:
+    if type(executions) is not tuple or not executions or any(
+        type(value) is not OperationalFrameActionAllocationTreatmentExecution
+        for value in executions
+    ):
+        raise ValueError("executions must be a non-empty exact allocator-v3 tuple")
+    for value in executions:
+        value.__post_init__()
+    assignment = executions[0].treatment_assignment
+    if any(
+        value.treatment_assignment.receipt_sha256 != assignment.receipt_sha256
+        for value in executions
+    ):
+        raise ValueError("v3 executions name different treatment assignments")
+    observed_order = tuple(value.treatment_occurrence for value in executions)
+    if observed_order != assignment.occurrence_input_order:
+        raise ValueError("v3 executions must use treatment occurrence input order")
+    configuration = executions[0].request.allocator_configuration_sha256
+    if any(
+        value.request.allocator_configuration_sha256 != configuration
+        for value in executions
+    ):
+        raise ValueError(
+            "v3 treatment arms must share resolution, mode, public seed, and "
+            "allocation-unit key"
+        )
+    if require_all_pass and any(not value.result.audit.passes for value in executions):
+        raise OperationalFrameActionAllocationCommitRejected(
+            "every operational allocation audit must pass before evaluator authority"
+        )
+    return assignment
+
+
+def _frozen_payload(value: dict[str, object]) -> FrozenJsonObject:
+    result = freeze_json(value)
+    if type(result) is not FrozenJsonObject:
+        raise AssertionError("allocator-v3 phase payload must freeze as an object")
+    return result
+
+
+def build_operational_frame_action_allocation_phase_commit(
+    *,
+    upstream_input_sha256: str,
+    terminal_provider_ledger_commitment_sha256: str,
+    executions: tuple[OperationalFrameActionAllocationTreatmentExecution, ...],
+) -> TwoStageActionPhaseCommit:
+    """Build an ALLOCATE commit from complete, common-key passing v3 records."""
+
+    require_sha256(upstream_input_sha256, "upstream_input_sha256")
+    require_sha256(
+        terminal_provider_ledger_commitment_sha256,
+        "terminal_provider_ledger_commitment_sha256",
+    )
+    assignment = _validated_execution_tuple(executions, require_all_pass=True)
+    commit_input = OperationalFrameActionAllocationCommitInput(
+        upstream_input_sha256=upstream_input_sha256,
+        terminal_provider_ledger_commitment_sha256=(
+            terminal_provider_ledger_commitment_sha256
+        ),
+        treatment_assignment=assignment,
+        allocation_requests=tuple(value.request for value in executions),
+    )
+    payload = _frozen_payload(
+        {
+            "schema_version": 1,
+            "phase": TwoStageActionPhase.ALLOCATE.value,
+            "commit_kind": _COMMIT_KIND,
+            "allocation_input": commit_input.to_record(),
+            "terminal_provider_ledger_commitment": (
+                commit_input.terminal_provider_ledger_commitment_record
+            ),
+            "treatment_assignment_receipt_sha256": assignment.receipt_sha256,
+            "treatment_occurrence_order": [
+                value.to_record() for value in assignment.occurrence_input_order
+            ],
+            "treatment_executions": [value.to_record() for value in executions],
+            "all_operational_allocation_audits_pass": True,
+            "evaluator_authority_eligible": True,
+        }
+    )
+    return TwoStageActionPhaseCommit(
+        receipt=TwoStageActionPhaseReceipt(
+            phase=TwoStageActionPhase.ALLOCATE,
+            input_sha256=commit_input.input_sha256,
+            output_sha256=typed_json_sha256(payload),
+        ),
+        payload=payload,
+    )
+
+
+def validate_operational_frame_action_allocation_phase_commit(
+    executions: tuple[OperationalFrameActionAllocationTreatmentExecution, ...],
+    phase_commit: TwoStageActionPhaseCommit,
+) -> OperationalFrameActionAllocationCommitInput:
+    """Rebuild and compare the exact v3 commit and every execution record."""
+
+    assignment = _validated_execution_tuple(executions, require_all_pass=True)
+    if type(phase_commit) is not TwoStageActionPhaseCommit:
+        raise TypeError("phase_commit must be an exact TwoStageActionPhaseCommit")
+    phase_commit.__post_init__()
+    if phase_commit.receipt.phase is not TwoStageActionPhase.ALLOCATE:
+        raise ValueError("only an ALLOCATE v3 commit can authorize evaluation")
+    payload = thaw_json(phase_commit.payload)
+    if (
+        type(payload) is not dict
+        or payload.get("phase") != TwoStageActionPhase.ALLOCATE.value
+        or payload.get("commit_kind") != _COMMIT_KIND
+        or type(payload.get("allocation_input")) is not dict
+    ):
+        raise ValueError("operational frame-allocation phase payload is malformed")
+    raw_input = payload["allocation_input"]
+    assert type(raw_input) is dict
+    upstream_input_sha256 = raw_input.get("upstream_input_sha256")
+    raw_ledger = raw_input.get("terminal_provider_ledger_commitment")
+    if type(upstream_input_sha256) is not str or type(raw_ledger) is not dict:
+        raise ValueError("operational frame-allocation input is malformed")
+    ledger_sha256 = raw_ledger.get("commitment_sha256")
+    if type(ledger_sha256) is not str:
+        raise ValueError("terminal-provider-ledger commitment is malformed")
+    require_sha256(upstream_input_sha256, "upstream_input_sha256")
+    require_sha256(ledger_sha256, "terminal_provider_ledger_commitment_sha256")
+    expected = build_operational_frame_action_allocation_phase_commit(
+        upstream_input_sha256=upstream_input_sha256,
+        terminal_provider_ledger_commitment_sha256=ledger_sha256,
+        executions=executions,
+    )
+    if (
+        phase_commit.receipt.receipt_sha256
+        != expected.receipt.receipt_sha256
+        or phase_commit.payload != expected.payload
+        or phase_commit.to_record() != expected.to_record()
+    ):
+        raise ValueError(
+            "operational frame-allocation commit differs from exact executions"
+        )
+    return OperationalFrameActionAllocationCommitInput(
+        upstream_input_sha256=upstream_input_sha256,
+        terminal_provider_ledger_commitment_sha256=ledger_sha256,
+        treatment_assignment=assignment,
+        allocation_requests=tuple(value.request for value in executions),
+    )
+
+
+__all__ = [
+    "OperationalFrameActionAllocationCommitRejected",
+    "build_operational_frame_action_allocation_phase_commit",
+    "validate_operational_frame_action_allocation_phase_commit",
+]

agent_evolve/application/action_allocation_frame_v3.py

@@ -0,0 +1,338 @@
+"""Operational-tie-aware greedy allocation over authenticated forecast frames."""
+
+from __future__ import annotations
+
+import math
+
+from agent_evolve.ports.action_allocation import (
+    AllocatedActionMember,
+    ForecastPortfolioUtilityInput,
+    ForecastQuantile,
+    PortfolioAllocationScore,
+)
+from agent_evolve.ports.action_allocation_frame import (
+    FrameActionPortfolioDecision,
+    allocation_score_multiset_sha256,
+)
+from agent_evolve.ports.action_allocation_frame_v3 import (
+    AllocationV3Candidate,
+    AllocationV3SeedSamplingLaw,
+    AllocationV3StepAudit,
+    GREEDY_RISK_DIVERSITY_V3_ALLOCATOR_DEFINITION_SHA256,
+    GREEDY_RISK_DIVERSITY_V3_ALLOCATOR_ID,
+    GREEDY_RISK_DIVERSITY_V3_ALLOCATOR_VERSION,
+    OperationalFrameActionAllocationAudit,
+    OperationalFrameActionAllocationRequest,
+    OperationalFrameActionAllocationResult,
+    allocation_v3_failure_codes,
+    validate_operational_frame_action_allocation_result,
+)
+from agent_evolve.ports.action_forecast import ResolvedActionForecast
+
+
+class OperationalTieAllocationRejected(RuntimeError):
+    """A fail-closed v3 request produced an operational tie."""
+
+    result: OperationalFrameActionAllocationResult
+
+    def __init__(self, result: OperationalFrameActionAllocationResult) -> None:
+        if type(result) is not OperationalFrameActionAllocationResult:
+            raise TypeError("result must be an exact operational frame result")
+        result.__post_init__()
+        if result.audit.passes:
+            raise ValueError("a passing operational allocation cannot be rejected")
+        self.result = result
+        RuntimeError.__init__(
+            self,
+            "operational allocation tie failed its prospectively bound mode",
+        )
+
+
+class OperationalGreedyForecastFrameAllocator:
+    """Stateless allocator-v3 application service.
+
+    Every configuration value capable of changing a decision belongs to the
+    request and therefore to its receipt.  The benchmark utility remains an
+    injected port, and both ``diversity_weight=0.0`` and arbitrary finite N/k
+    are supported.
+    """
+
+    @staticmethod
+    def _utility(
+        request: OperationalFrameActionAllocationRequest,
+        members: tuple[ResolvedActionForecast, ...],
+        quantile: ForecastQuantile,
+    ) -> float:
+        base = request.allocation
+        canonical_members = tuple(
+            sorted(
+                members,
+                key=lambda value: (value.option_identity_sha256, value.option_id),
+            )
+        )
+        value = base.utility.utility(
+            ForecastPortfolioUtilityInput(
+                optimization_semantics=base.frame.request.optimization_semantics,
+                parent_metric_values=base.frame.request.parent_metric_values,
+                metric_scales=base.frame.request.metric_scales,
+                members=canonical_members,
+                quantile=quantile,
+            )
+        )
+        if type(value) is not float or not math.isfinite(value):
+            raise TypeError("bound portfolio utility must return a finite float")
+        return value
+
+    @classmethod
+    def _score(
+        cls,
+        request: OperationalFrameActionAllocationRequest,
+        members: tuple[ResolvedActionForecast, ...],
+        *,
+        attainable_diversity: int,
+    ) -> PortfolioAllocationScore:
+        if type(attainable_diversity) is not int or attainable_diversity <= 0:
+            raise ValueError("attainable_diversity must be a positive exact integer")
+        p10 = cls._utility(request, members, ForecastQuantile.P10)
+        p50 = cls._utility(request, members, ForecastQuantile.P50)
+        p90 = cls._utility(request, members, ForecastQuantile.P90)
+        downside = min(p10, p90)
+        risk_penalty = request.risk_aversion * max(0.0, p50 - downside)
+        diversity_reward = request.diversity_weight * (
+            len({member.family for member in members}) / attainable_diversity
+        )
+        primary = p50 - risk_penalty
+        total = primary + diversity_reward
+        if not all(
+            math.isfinite(value)
+            for value in (risk_penalty, diversity_reward, primary, total)
+        ):
+            raise ValueError("allocator-v3 score arithmetic became non-finite")
+        return PortfolioAllocationScore(
+            p10_utility=p10,
+            p50_utility=p50,
+            p90_utility=p90,
+            downside_utility=downside,
+            risk_penalty=risk_penalty,
+            diversity_reward=diversity_reward,
+            total_utility=total,
+        )
+
+    def assess(
+        self,
+        request: OperationalFrameActionAllocationRequest,
+    ) -> OperationalFrameActionAllocationResult:
+        """Return the complete candidate tables, including a failing attempt."""
+
+        if type(request) is not OperationalFrameActionAllocationRequest:
+            raise TypeError("request must be an exact operational frame request")
+        request.__post_init__()
+        base = request.allocation
+        by_id = {value.option_id: value for value in base.frame.forecasts}
+        global_index_by_id = {
+            forecast.option_id: global_index
+            for global_index, forecast in zip(
+                base.frame.global_row_indices,
+                base.frame.forecasts,
+                strict=True,
+            )
+        }
+        attainable_diversity = min(
+            base.portfolio_size,
+            len({by_id[value].family for value in base.eligible_option_ids}),
+        )
+        remaining = sorted(
+            (by_id[value] for value in base.eligible_option_ids),
+            key=lambda value: (value.option_identity_sha256, value.option_id),
+        )
+        selected: list[ResolvedActionForecast] = []
+        members: list[AllocatedActionMember] = []
+        step_audits: list[AllocationV3StepAudit] = []
+        previous_total = 0.0
+
+        for step in range(1, base.portfolio_size + 1):
+            evaluated: list[
+                tuple[
+                    ResolvedActionForecast,
+                    PortfolioAllocationScore,
+                    float,
+                    str,
+                    AllocationV3Candidate,
+                ]
+            ] = []
+            for candidate in remaining:
+                portfolio = tuple((*selected, candidate))
+                score = self._score(
+                    request,
+                    portfolio,
+                    attainable_diversity=attainable_diversity,
+                )
+                marginal = score.total_utility - previous_total
+                if not math.isfinite(marginal):
+                    raise ValueError(
+                        "allocator-v3 marginal arithmetic became non-finite"
+                    )
+                label = f"row_{global_index_by_id[candidate.option_id]:08d}"
+                candidate_record = AllocationV3Candidate(
+                    candidate_label=label,
+                    option_identity_sha256=candidate.option_identity_sha256,
+                    score=score,
+                    marginal_total_utility=marginal,
+                    public_rank_sha256=request.tie_selection.public_rank_sha256(
+                        step=step,
+                        option_identity_sha256=candidate.option_identity_sha256,
+                    ),
+                )
+                evaluated.append((candidate, score, marginal, label, candidate_record))
+
+            candidate_table = tuple(
+                sorted(
+                    (value[4] for value in evaluated),
+                    key=lambda value: value.candidate_label,
+                )
+            )
+            raw_top = max(value.marginal_total_utility for value in candidate_table)
+            ranked_scores = sorted(
+                (value.marginal_total_utility for value in candidate_table),
+                reverse=True,
+            )
+            raw_runner_gap = (
+                0.0
+                if len(ranked_scores) == 1
+                else ranked_scores[0] - ranked_scores[1]
+            )
+            if not math.isfinite(raw_runner_gap):
+                raise ValueError("allocator-v3 runner-gap arithmetic became non-finite")
+            raw_top_labels = tuple(
+                value.candidate_label
+                for value in candidate_table
+                if value.marginal_total_utility == raw_top
+            )
+            operational = tuple(
+                value
+                for value in candidate_table
+                if raw_top - value.marginal_total_utility
+                <= request.score_resolution.maximum_indistinguishable_score_gap
+            )
+            winner_record = min(
+                operational,
+                key=lambda value: (value.public_rank_sha256, value.candidate_label),
+            )
+            failures = allocation_v3_failure_codes(
+                mode=request.tie_selection.mode,
+                operational_top_count=len(operational),
+            )
+            step_audit = AllocationV3StepAudit(
+                step=step,
+                candidates=candidate_table,
+                distinct_finite_score_count=len(
+                    {value.marginal_total_utility for value in candidate_table}
+                ),
+                raw_top_score=raw_top,
+                raw_runner_gap=raw_runner_gap,
+                raw_top_candidate_labels=raw_top_labels,
+                operational_top_candidate_labels=tuple(
+                    value.candidate_label for value in operational
+                ),
+                selected_candidate_label=winner_record.candidate_label,
+                selected_public_rank_sha256=winner_record.public_rank_sha256,
+                random_oracle_prior_weight_numerator=(
+                    None
+                    if request.tie_selection.seed_sampling_law
+                    is AllocationV3SeedSamplingLaw.FIXED_PUBLIC
+                    else 1
+                ),
+                random_oracle_prior_weight_denominator=(
+                    None
+                    if request.tie_selection.seed_sampling_law
+                    is AllocationV3SeedSamplingLaw.FIXED_PUBLIC
+                    else len(operational)
+                ),
+                score_multiset_sha256=allocation_score_multiset_sha256(
+                    tuple(value.marginal_total_utility for value in candidate_table)
+                ),
+                failure_codes=failures,
+                passes=not failures,
+            )
+            step_audits.append(step_audit)
+
+            winner = next(
+                value
+                for value in evaluated
+                if value[3] == winner_record.candidate_label
+            )
+            best_forecast, best_score, best_marginal, _label, _record = winner
+            selected.append(best_forecast)
+            remaining.remove(best_forecast)
+            members.append(
+                AllocatedActionMember(
+                    rank=step,
+                    option_id=best_forecast.option_id,
+                    option_identity_sha256=best_forecast.option_identity_sha256,
+                    child_configuration_sha256=(
+                        best_forecast.child_configuration_sha256
+                    ),
+                    family=best_forecast.family,
+                    greedy_step_score=best_score,
+                    marginal_total_utility=best_marginal,
+                )
+            )
+            previous_total = best_score.total_utility
+
+        candidate_evaluations = sum(value.candidate_count for value in step_audits)
+        decision = FrameActionPortfolioDecision(
+            allocation_request_sha256=base.request_sha256,
+            frame_receipt_sha256=base.frame.receipt_sha256,
+            source_forecast_receipt_sha256=(
+                base.frame.source_forecast_receipt_sha256
+            ),
+            eligible_options_sha256=base.eligible_options_sha256,
+            members=tuple(members),
+            final_score=members[-1].greedy_step_score,
+            candidate_evaluations=candidate_evaluations,
+            utility_policy_id=base.utility.policy_id,
+            utility_policy_version=base.utility.policy_version,
+            utility_definition_sha256=base.utility.definition_sha256,
+            allocator_policy_id=GREEDY_RISK_DIVERSITY_V3_ALLOCATOR_ID,
+            allocator_policy_version=GREEDY_RISK_DIVERSITY_V3_ALLOCATOR_VERSION,
+            allocator_definition_sha256=(
+                GREEDY_RISK_DIVERSITY_V3_ALLOCATOR_DEFINITION_SHA256
+            ),
+            allocator_configuration_sha256=(
+                request.allocator_configuration_sha256
+            ),
+        )
+        audit = OperationalFrameActionAllocationAudit(
+            operational_request_sha256=request.request_sha256,
+            base_allocation_request_sha256=base.request_sha256,
+            decision_receipt_sha256=decision.receipt_sha256,
+            frame_receipt_sha256=base.frame.receipt_sha256,
+            score_resolution=request.score_resolution,
+            tie_selection=request.tie_selection,
+            steps=tuple(step_audits),
+            candidate_score_count=candidate_evaluations,
+            passes=all(value.passes for value in step_audits),
+        )
+        result = OperationalFrameActionAllocationResult(
+            decision=decision,
+            audit=audit,
+        )
+        validate_operational_frame_action_allocation_result(request, result)
+        return result
+
+    def allocate(
+        self,
+        request: OperationalFrameActionAllocationRequest,
+    ) -> OperationalFrameActionAllocationResult:
+        """Authorize only a result permitted by the prospectively bound mode."""
+
+        result = self.assess(request)
+        if not result.audit.passes:
+            raise OperationalTieAllocationRejected(result)
+        return result
+
+
+__all__ = [
+    "OperationalGreedyForecastFrameAllocator",
+    "OperationalTieAllocationRejected",
+]