agentevolve-optimizer 0.5.0__py3-none-any.whl

agent_evolve/application/forecast_opportunity_shadow_calibration.py

@@ -0,0 +1,316 @@
+"""Project a same-prefix forecast shadow into calibration evidence.
+
+The projector joins only authenticated, already-observed records:
+
+* the protected forecast-opportunity decision and its sealed raw score;
+* the portable action descriptor used before evaluation; and
+* the final same-prefix challenger-versus-fallback observation.
+
+It does not inspect workload schemas, objective names, prompts, models, or
+providers.  The resulting observation can therefore enter the generic
+prequential calibration memory without adding a workload integration method.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import math
+from dataclasses import dataclass, field
+
+from agent_evolve.application.outcome_adaptive_action_racing import (
+    AdaptiveActionDescriptor,
+    AdaptiveActionRacingDecision,
+)
+from agent_evolve.application.prequential_archive_opportunity_calibration import (
+    ArchiveOpportunityActionContext,
+    ArchiveOpportunityCalibrationEvidenceRole,
+    ArchiveOpportunityCalibrationObservation,
+    ArchiveOpportunityCalibrationRequest,
+)
+from agent_evolve.application.same_prefix_paired_audit import (
+    FORECAST_OPPORTUNITY_SAME_PREFIX_AUDIT_DESIGNER_IDS,
+    FORECAST_OPPORTUNITY_SAME_PREFIX_SHADOW_DESIGNER_ID,
+    FORECAST_STRATIFIED_SAME_PREFIX_AUDIT_DESIGNER_ID,
+    SamePrefixPairedAuditArm,
+    SamePrefixPairedAuditObservation,
+)
+from agent_evolve.domain.typed_json import thaw_json
+
+
+FORECAST_OPPORTUNITY_SHADOW_CALIBRATION_PROJECTOR_ID = (
+    "forecast_opportunity_shadow_calibration"
+)
+FORECAST_OPPORTUNITY_SHADOW_CALIBRATION_PROJECTOR_VERSION = 2
+_DEFINITION_DOMAIN = (
+    b"agent-evolve:forecast-opportunity-shadow-calibration-projector:v2\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")
+
+
+def _hash(domain: bytes, value: object) -> str:
+    return hashlib.sha256(domain + _canonical_json(value)).hexdigest()
+
+
+def _read_nonnegative_hex(record: dict[str, object], key: str) -> float:
+    raw = record.get(key)
+    if type(raw) is not str:
+        raise TypeError(f"{key} must be an exact hexadecimal float")
+    try:
+        value = float.fromhex(raw)
+    except ValueError as error:
+        raise ValueError(f"{key} is not a hexadecimal float") from error
+    if not math.isfinite(value) or value < 0.0:
+        raise ValueError(f"{key} must be finite and non-negative")
+    return float(value)
+
+
+@dataclass(frozen=True, slots=True)
+class ForecastOpportunityShadowCalibrationProjector:
+    """Create one calibration target from a sealed same-prefix forecast arm."""
+
+    projector_id: str = (
+        FORECAST_OPPORTUNITY_SHADOW_CALIBRATION_PROJECTOR_ID
+    )
+    projector_version: int = (
+        FORECAST_OPPORTUNITY_SHADOW_CALIBRATION_PROJECTOR_VERSION
+    )
+    definition_sha256: str = field(init=False)
+
+    def __post_init__(self) -> None:
+        if (
+            self.projector_id
+            != FORECAST_OPPORTUNITY_SHADOW_CALIBRATION_PROJECTOR_ID
+            or self.projector_version
+            != FORECAST_OPPORTUNITY_SHADOW_CALIBRATION_PROJECTOR_VERSION
+        ):
+            raise ValueError("shadow calibration projector identity is immutable")
+        object.__setattr__(
+            self,
+            "definition_sha256",
+            _hash(
+                _DEFINITION_DOMAIN,
+                {
+                    "schema_version": 1,
+                    "projector_id": self.projector_id,
+                    "projector_version": self.projector_version,
+                    "forecast_source": (
+                        "authenticated-protected-decision-raw-score"
+                    ),
+                    "target": (
+                        "exact-forecast-arm-conditional-gain-at-identical-"
+                        "prefix"
+                    ),
+                    "accepted_designers": sorted(
+                        FORECAST_OPPORTUNITY_SAME_PREFIX_AUDIT_DESIGNER_IDS
+                    ),
+                    "fallback_target_retained_in_paired_observation": True,
+                    "paired_evidence_role_and_sampling_propensity_recorded": (
+                        True
+                    ),
+                    "current_or_future_candidate_outcomes_used_for_forecast": (
+                        False
+                    ),
+                    "workload_objective_model_provider_prompt_config_"
+                    "branches": False,
+                },
+            ),
+        )
+
+    @staticmethod
+    def _score_record(
+        decision: AdaptiveActionRacingDecision,
+        action_sha256: str,
+        *,
+        require_recommended: bool,
+    ) -> dict[str, object]:
+        evidence = thaw_json(decision.evidence)
+        ranking = evidence.get("opportunity_ranking")
+        if type(ranking) is not dict:
+            raise TypeError("decision lacks an exact opportunity ranking")
+        recommended = ranking.get("recommended_action_sha256s")
+        scores = ranking.get("scores")
+        if (
+            type(recommended) is not list
+            or type(scores) is not list
+        ):
+            raise TypeError("decision opportunity ranking is incomplete")
+        if require_recommended and action_sha256 not in recommended:
+            raise ValueError(
+                "legacy shadow challenger is not a recommendation"
+            )
+        matches = [
+            value
+            for value in scores
+            if type(value) is dict
+            and value.get("action_sha256") == action_sha256
+        ]
+        if len(matches) != 1:
+            raise ValueError(
+                "opportunity ranking must expose one challenger score"
+            )
+        return matches[0]
+
+    def project(
+        self,
+        *,
+        decision_index: int,
+        evidence_cutoff_ordinal: int,
+        decision: AdaptiveActionRacingDecision,
+        action: AdaptiveActionDescriptor,
+        observation: SamePrefixPairedAuditObservation,
+    ) -> ArchiveOpportunityCalibrationObservation:
+        """Join the sealed raw score to the later real challenger outcome."""
+
+        self.__post_init__()
+        if type(decision_index) is not int or decision_index <= 0:
+            raise ValueError("decision_index must be positive")
+        if (
+            type(evidence_cutoff_ordinal) is not int
+            or evidence_cutoff_ordinal <= 0
+        ):
+            raise ValueError("evidence_cutoff_ordinal must be positive")
+        if type(decision) is not AdaptiveActionRacingDecision:
+            raise TypeError("decision must be exact")
+        if type(action) is not AdaptiveActionDescriptor:
+            raise TypeError("action must be exact")
+        if type(observation) is not SamePrefixPairedAuditObservation:
+            raise TypeError("observation must be exact")
+        decision.__post_init__()
+        action.__post_init__()
+        observation.__post_init__()
+        plan = observation.plan
+        if plan.designer_id not in (
+            FORECAST_OPPORTUNITY_SAME_PREFIX_AUDIT_DESIGNER_IDS
+        ):
+            raise ValueError("observation is not a forecast audit")
+        is_legacy_final_shadow = (
+            plan.designer_id
+            == FORECAST_OPPORTUNITY_SAME_PREFIX_SHADOW_DESIGNER_ID
+        )
+        if (
+            plan.racing_decision_sha256 != decision.decision_sha256
+            or plan.exploration_action_sha256 != action.action_sha256
+            or decision.selected_action_sha256s
+            != (plan.authoritative_action_sha256,)
+            or decision.prior_selected_action_sha256s
+            != plan.common_prefix_action_sha256s
+            or (
+                is_legacy_final_shadow
+                and plan.authoritative_arm
+                is not SamePrefixPairedAuditArm.EXPLORATION
+            )
+            or (
+                plan.designer_id
+                == FORECAST_STRATIFIED_SAME_PREFIX_AUDIT_DESIGNER_ID
+                and plan.authoritative_arm
+                not in {
+                    SamePrefixPairedAuditArm.LEGACY,
+                    SamePrefixPairedAuditArm.EXPLORATION,
+                }
+            )
+        ):
+            raise ValueError(
+                "decision, descriptor, and forecast shadow do not join"
+            )
+        score = self._score_record(
+            decision,
+            action.action_sha256,
+            require_recommended=is_legacy_final_shadow,
+        )
+        raw_acquisition_key = (
+            "raw_acquisition_value_hex"
+            if "raw_acquisition_value_hex" in score
+            else "acquisition_value_hex"
+        )
+        paired_role = (
+            ArchiveOpportunityCalibrationEvidenceRole
+            .SAME_PREFIX_PAIRED_AUTHORITATIVE
+            if plan.authoritative_arm
+            is SamePrefixPairedAuditArm.EXPLORATION
+            else (
+                ArchiveOpportunityCalibrationEvidenceRole
+                .SAME_PREFIX_PAIRED_COUNTERFACTUAL
+            )
+        )
+        return ArchiveOpportunityCalibrationObservation(
+            request=ArchiveOpportunityCalibrationRequest(
+                context=ArchiveOpportunityActionContext(
+                    action_sha256=action.action_sha256,
+                    decision_index=decision_index,
+                    lane_id=action.lane_id,
+                    operator_id=action.operator_id,
+                    native_rank=action.native_rank,
+                    lane_size=action.lane_size,
+                    prior_score=action.prior_score,
+                    parent_generated_in_current_run=(
+                        action.parent_generated_in_current_run
+                    ),
+                ),
+                forecast_reliability=_read_nonnegative_hex(
+                    score,
+                    "reliability_hex",
+                ),
+                raw_adverse_gain=_read_nonnegative_hex(
+                    score,
+                    "adverse_gain_hex",
+                ),
+                raw_central_gain=_read_nonnegative_hex(
+                    score,
+                    "central_gain_hex",
+                ),
+                raw_favorable_gain=_read_nonnegative_hex(
+                    score,
+                    "favorable_gain_hex",
+                ),
+                raw_acquisition_value=_read_nonnegative_hex(
+                    score,
+                    raw_acquisition_key,
+                ),
+                prefix_gain=float(
+                    observation.exploration_set_outcome
+                    .prior_selected_set_gain
+                ),
+                prefix_action_count=len(
+                    plan.common_prefix_action_sha256s
+                ),
+            ),
+            realized_conditional_gain=float(
+                observation.exploration_set_outcome.conditional_set_gain
+            ),
+            decision_sha256=decision.decision_sha256,
+            outcome_sha256=observation.exploration_outcome.outcome_sha256,
+            evidence_cutoff_ordinal=evidence_cutoff_ordinal,
+            evidence_role=(
+                ArchiveOpportunityCalibrationEvidenceRole
+                .AUTHORITATIVE_SELECTED
+                if is_legacy_final_shadow
+                else paired_role
+            ),
+            sampling_propensity=(
+                1.0
+                if is_legacy_final_shadow
+                else plan.exploration_selection_propensity
+            ),
+            paired_observation_sha256=(
+                None
+                if is_legacy_final_shadow
+                else observation.observation_sha256
+            ),
+        )
+
+
+__all__ = [
+    "FORECAST_OPPORTUNITY_SHADOW_CALIBRATION_PROJECTOR_ID",
+    "FORECAST_OPPORTUNITY_SHADOW_CALIBRATION_PROJECTOR_VERSION",
+    "ForecastOpportunityShadowCalibrationProjector",
+]

agent_evolve/application/front_proximity_admission.py

@@ -0,0 +1,311 @@
+"""Front-proximity admission: drop the market's dominated-parent tail.
+
+A candidate's *parent anchor* is the objective point its action was derived
+from.  The anchor's Chebyshev excess over the current archive front measures
+how deep inside the dominated interior that anchor sits: a value at or below
+zero means the anchor is itself non-dominated, and larger values mean the
+anchor is buried further behind the front.
+
+On the jul28 sealed BOiLS held-out markets this quantity is the strongest
+outcome-blind discriminator measured (pooled AUC 0.732 for individual
+positivity, 8 of 8 markets at or above 0.50), and its worst band is
+effectively empty: anchors more than 0.05 normalized units behind the front
+hold 26% of the market mass, 1 of 88 positives and 1.6% of the realised
+gain.  This module turns that observation into a *support restriction* that
+composes over any allocation policy: the wrapped policy still makes every
+decision, it simply never sees the tail of the market that carries no
+outcome mass.
+
+The rule is deliberately RELATIVE — it keeps the market's own best
+``keep_fraction`` of anchors — so it introduces no absolute threshold, no
+workload constant, no metric name and no scale assumption.  Candidates whose
+anchor is unknown are scored at the market's median anchor so an anchorless
+lane is never systematically evicted or systematically protected.
+
+The signal replicates: pooled AUC 0.700 on the five jul27 replay-corpus
+markets that record parent anchors (0.583 to 0.767 per market), against
+0.732 on the eight held-out markets.  What has NOT been shown is that any
+deterministic policy built on it beats the ``lane_heads`` incumbent on four
+sealed cells; the incumbent's own headline sits at the p = 0.08 tail of the
+uniform null, so a four-cell single-run comparison cannot resolve it.
+
+Claim boundary: replay-evaluation only.  Nothing here carries live campaign
+authority.  See
+``research_artifacts/jul28_large_gain_anatomy_and_refinement.md``.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import math
+import re
+from dataclasses import dataclass, field
+
+from agent_evolve.application.calibrated_positive_gain_opportunity import (
+    ObjectivePoint,
+    chebyshev_excess,
+    non_dominated,
+)
+from agent_evolve.application.sequential_market_replay import (
+    MarketRecord,
+    ReplaySelection,
+    ReplayStepReceipt,
+    _corpus_action_sha256,
+    _normalized_point,
+)
+from agent_evolve.domain.patch import require_sha256
+
+FRONT_PROXIMITY_ADMISSION_ID = "front_proximity_admission"
+FRONT_PROXIMITY_ADMISSION_VERSION = 1
+_TOKEN = re.compile(r"^[a-z][a-z0-9_.:-]{0,255}$")
+_DEFINITION_DOMAIN = b"agent-evolve:front-proximity-admission: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")
+
+
+def _hash(value: object) -> str:
+    return hashlib.sha256(
+        _DEFINITION_DOMAIN + _canonical_json(value)
+    ).hexdigest()
+
+
+# ``non_dominated`` and ``chebyshev_excess`` now live in the calibrated
+# scorer, which consumes the same geometry directly; they are re-exported
+# here unchanged so every existing import keeps resolving.
+
+
+@dataclass(frozen=True, slots=True)
+class FrontProximityAdmissionConfig:
+    """How much of the market's anchor distribution stays selectable."""
+
+    #: Fraction of the market's known anchors retained, best (smallest
+    #: Chebyshev excess) first.  1.0 disables the restriction entirely.
+    keep_fraction: float = 0.50
+    #: Never shrink the support below this many candidates, so a small
+    #: market can never be reduced to a single forced choice.
+    minimum_support: int = 2
+
+    def __post_init__(self) -> None:
+        if (
+            type(self.keep_fraction) is not float
+            or not math.isfinite(self.keep_fraction)
+            or not 0.0 < self.keep_fraction <= 1.0
+        ):
+            raise ValueError("keep_fraction must lie in (0, 1]")
+        if type(self.minimum_support) is not int or self.minimum_support < 1:
+            raise ValueError("minimum_support must be a positive integer")
+
+    def to_record(self) -> dict[str, object]:
+        return {
+            "keep_fraction_hex": float(self.keep_fraction).hex(),
+            "minimum_support": self.minimum_support,
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class FrontProximityAdmission:
+    """Restrict a replay policy to the front-proximal part of its market.
+
+    ``anchors`` maps ``action_sha256`` to that candidate's parent objective
+    point in the market's own normalized metric frame.  Candidates absent
+    from the map are scored at the median known excess.
+    """
+
+    inner: object
+    anchors: dict[str, ObjectivePoint]
+    config: FrontProximityAdmissionConfig = field(
+        default_factory=FrontProximityAdmissionConfig
+    )
+    policy_id: str = "replay_arm.front_proximity_admission"
+    definition_sha256: str = field(init=False)
+
+    def __post_init__(self) -> None:
+        if not hasattr(self.inner, "select"):
+            raise TypeError("inner must expose an exact select()")
+        if type(self.anchors) is not dict:
+            raise TypeError("anchors must be an exact mapping")
+        for action_sha256, point in self.anchors.items():
+            require_sha256(action_sha256, "anchors key")
+            if type(point) is not tuple or not point:
+                raise TypeError("anchor points must be exact tuples")
+        self.config.__post_init__()
+        if _TOKEN.fullmatch(self.policy_id) is None:
+            raise ValueError("policy_id must use the closed token grammar")
+        object.__setattr__(
+            self,
+            "definition_sha256",
+            _hash(
+                {
+                    "arm": FRONT_PROXIMITY_ADMISSION_ID,
+                    "version": FRONT_PROXIMITY_ADMISSION_VERSION,
+                    "config": self.config.to_record(),
+                    "inner_policy_id": str(
+                        getattr(self.inner, "policy_id", "")
+                    ),
+                    "inner_definition_sha256": str(
+                        getattr(self.inner, "definition_sha256", "")
+                    ),
+                    "rule": (
+                        "keep the market's best keep_fraction of candidates "
+                        "by parent-anchor chebyshev excess over the archive "
+                        "front, unknown anchors scored at the median, never "
+                        "below minimum_support"
+                    ),
+                }
+            ),
+        )
+
+    def admissible(
+        self,
+        *,
+        record: MarketRecord,
+        revealed: tuple[ReplayStepReceipt, ...],
+        selectable_action_sha256s: tuple[str, ...],
+    ) -> tuple[str, ...]:
+        """The retained support, outcome-blind except for revealed points."""
+
+        support = tuple(sorted(set(selectable_action_sha256s)))
+        if not support:
+            raise ValueError("selectable support must be non-empty")
+        if self.config.keep_fraction >= 1.0:
+            return support
+        metric_ids = record.metric_ids
+        archive: list[ObjectivePoint] = list(record.archive_points)
+        for receipt in revealed:
+            candidate = record.candidate(receipt.action_sha256)
+            if candidate.objectives is not None:
+                archive.append(candidate.objectives)
+        frozen_archive = tuple(archive)
+        scored: list[tuple[str, float | None]] = []
+        for action_sha256 in support:
+            anchor = self.anchors.get(action_sha256)
+            scored.append(
+                (
+                    action_sha256,
+                    None
+                    if anchor is None
+                    else chebyshev_excess(
+                        anchor, frozen_archive, metric_ids
+                    ),
+                )
+            )
+        known = sorted(
+            value for _sha, value in scored if value is not None
+        )
+        if not known:
+            return support
+        median = known[len(known) // 2]
+        index = int(round(self.config.keep_fraction * len(known))) - 1
+        index = max(0, min(len(known) - 1, index))
+        cutoff = known[index]
+        kept = tuple(
+            action_sha256
+            for action_sha256, value in scored
+            if (median if value is None else value) <= cutoff
+        )
+        if len(kept) < min(self.config.minimum_support, len(support)):
+            # Restore in ascending excess order until the floor is met, so
+            # the restriction degrades continuously instead of collapsing.
+            order = sorted(
+                scored,
+                key=lambda item: (
+                    median if item[1] is None else item[1],
+                    item[0],
+                ),
+            )
+            kept = tuple(
+                action_sha256
+                for action_sha256, _value in order[
+                    : min(self.config.minimum_support, len(support))
+                ]
+            )
+        return tuple(sorted(kept)) or support
+
+    def select(
+        self,
+        *,
+        record: MarketRecord,
+        revealed: tuple[ReplayStepReceipt, ...],
+        selectable_action_sha256s: tuple[str, ...],
+        step_index: int,
+        budget: int,
+    ) -> ReplaySelection:
+        kept = self.admissible(
+            record=record,
+            revealed=revealed,
+            selectable_action_sha256s=selectable_action_sha256s,
+        )
+        selection = self.inner.select(
+            record=record,
+            revealed=revealed,
+            selectable_action_sha256s=kept,
+            step_index=step_index,
+            budget=budget,
+        )
+        if type(selection) is not ReplaySelection:
+            raise TypeError("inner policy must return an exact selection")
+        if selection.action_sha256 not in kept:
+            raise ValueError("inner policy escaped the admissible support")
+        return ReplaySelection(
+            action_sha256=selection.action_sha256,
+            selection_propensity=selection.selection_propensity,
+            evidence={
+                **dict(selection.evidence),
+                "admissible_support_size": len(kept),
+                "offered_support_size": len(
+                    set(selectable_action_sha256s)
+                ),
+            },
+        )
+
+
+def anchors_from_corpus(
+    payload: dict[str, object],
+) -> dict[str, ObjectivePoint]:
+    """Parent anchors for one jul27 replay-corpus payload, if recorded.
+
+    Candidates with no recorded parent objective vector are simply absent,
+    which the admission rule treats as the median anchor.
+    """
+
+    market_id = str(payload["market_id"])
+    axes = tuple(payload["hv_reference_point"]["axes"])  # type: ignore[index]
+    metric_ids = tuple(sorted(str(axis["metric_id"]) for axis in axes))
+    anchors: dict[str, ObjectivePoint] = {}
+    for raw in payload["candidates"]:  # type: ignore[union-attr]
+        parent = raw.get("parent")
+        if not isinstance(parent, dict):
+            continue
+        objectives = parent.get("objectives")
+        if not isinstance(objectives, dict):
+            continue
+        if not set(metric_ids) <= set(objectives):
+            continue
+        anchors[_corpus_action_sha256(market_id, raw)] = _normalized_point(
+            {
+                metric_id: float(objectives[metric_id])
+                for metric_id in metric_ids
+            },
+            axes,
+        )
+    return anchors
+
+
+__all__ = [
+    "FRONT_PROXIMITY_ADMISSION_ID",
+    "FRONT_PROXIMITY_ADMISSION_VERSION",
+    "FrontProximityAdmission",
+    "FrontProximityAdmissionConfig",
+    "anchors_from_corpus",
+    "chebyshev_excess",
+    "non_dominated",
+]