agentevolve-optimizer 0.5.0__py3-none-any.whl

agent_evolve/application/campaign_capacity_recourse.py

@@ -0,0 +1,254 @@
+"""Generic campaign boundary for filling an under-realized candidate stage."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from dataclasses import dataclass, field
+from typing import Protocol, runtime_checkable
+
+from agent_evolve.application.agentic_evolution import EvolutionCandidate
+from agent_evolve.application.budgeted_optimizer import OptimizerState
+from agent_evolve.domain.patch import require_sha256
+from agent_evolve.domain.typed_json import (
+    FrozenJsonObject,
+    freeze_json,
+    thaw_json,
+    typed_json_sha256,
+)
+
+
+_TOKEN = re.compile(r"^[a-z][a-z0-9_.:-]{0,127}$")
+_REQUEST_DOMAIN = b"agent-evolve:campaign-capacity-recourse-request:v1\x00"
+_RESULT_DOMAIN = b"agent-evolve:campaign-capacity-recourse-result: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 _candidate_record(candidate: EvolutionCandidate) -> dict[str, object]:
+    EvolutionCandidate.__post_init__(candidate)
+    return {
+        "candidate_id": candidate.candidate_id.value,
+        "configuration_sha256": candidate.occurrence.configuration_hash,
+        "generation": candidate.generation,
+        "valid": candidate.valid,
+        "objectives": [
+            {"metric_id": key, "value_hex": value.hex()}
+            for key, value in candidate.objectives
+        ],
+    }
+
+
+def _policy_identity(
+    port: "CampaignCapacityRecoursePort",
+) -> tuple[str, int, str]:
+    if not isinstance(port, CampaignCapacityRecoursePort):
+        raise TypeError("capacity recourse must implement its port")
+    values = (
+        getattr(port, "policy_id", None),
+        getattr(port, "policy_version", None),
+        getattr(port, "definition_sha256", None),
+    )
+    if type(values[0]) is not str or _TOKEN.fullmatch(values[0]) is None:
+        raise ValueError("capacity recourse policy_id has invalid syntax")
+    if type(values[1]) is not int or values[1] <= 0:
+        raise ValueError("capacity recourse policy_version must be positive")
+    require_sha256(values[2], "capacity recourse definition_sha256")
+    return values  # type: ignore[return-value]
+
+
+@dataclass(frozen=True, slots=True)
+class CampaignCapacityRecourseRequest:
+    campaign_scope_sha256: str
+    preparation_sha256: str
+    stage_request_sha256: str
+    generation: int
+    planned_candidate_occurrences: int
+    realized_candidate_occurrences: int
+    state: OptimizerState
+    request_sha256: str = field(init=False, default="")
+
+    def __post_init__(self) -> None:
+        require_sha256(self.campaign_scope_sha256, "campaign_scope_sha256")
+        require_sha256(self.preparation_sha256, "preparation_sha256")
+        require_sha256(self.stage_request_sha256, "stage_request_sha256")
+        if type(self.generation) is not int or self.generation <= 0:
+            raise ValueError("generation must be positive")
+        for name in (
+            "planned_candidate_occurrences",
+            "realized_candidate_occurrences",
+        ):
+            value = getattr(self, name)
+            if type(value) is not int or value < 0:
+                raise ValueError(f"{name} must be non-negative")
+        if self.realized_candidate_occurrences >= self.planned_candidate_occurrences:
+            raise ValueError("capacity recourse requires a strictly underfilled stage")
+        if type(self.state) is not OptimizerState:
+            raise TypeError("state must be an exact OptimizerState")
+        OptimizerState.__post_init__(self.state)
+        if self.state.generation != self.generation:
+            raise ValueError("optimizer state generation differs from recourse stage")
+        computed = hashlib.sha256(
+            _REQUEST_DOMAIN + _canonical_json(self._unsigned_record())
+        ).hexdigest()
+        if self.request_sha256 not in ("", computed):
+            raise ValueError("request_sha256 does not authenticate the request")
+        object.__setattr__(self, "request_sha256", computed)
+
+    @property
+    def missing_candidate_occurrences(self) -> int:
+        return self.planned_candidate_occurrences - self.realized_candidate_occurrences
+
+    def _unsigned_record(self) -> dict[str, object]:
+        return {
+            "schema_version": 1,
+            "campaign_scope_sha256": self.campaign_scope_sha256,
+            "preparation_sha256": self.preparation_sha256,
+            "stage_request_sha256": self.stage_request_sha256,
+            "generation": self.generation,
+            "planned_candidate_occurrences": self.planned_candidate_occurrences,
+            "realized_candidate_occurrences": self.realized_candidate_occurrences,
+            "missing_candidate_occurrences": self.missing_candidate_occurrences,
+            "state": {
+                "archive_snapshot_hash": self.state.archive_snapshot_hash,
+                "unique_evaluations": self.state.unique_evaluations,
+                "logical_llm_calls": self.state.logical_llm_calls,
+                "candidates": [_candidate_record(value) for value in self.state.candidates],
+            },
+        }
+
+    def to_record(self) -> dict[str, object]:
+        self.__post_init__()
+        return {**self._unsigned_record(), "request_sha256": self.request_sha256}
+
+
+@dataclass(frozen=True, slots=True)
+class CampaignCapacityRecourseResult:
+    request_sha256: str
+    policy_id: str
+    policy_version: int
+    policy_definition_sha256: str
+    candidates: tuple[EvolutionCandidate, ...]
+    evidence: FrozenJsonObject
+    result_sha256: str = field(init=False, default="")
+
+    def __post_init__(self) -> None:
+        require_sha256(self.request_sha256, "request_sha256")
+        if type(self.policy_id) is not str or _TOKEN.fullmatch(self.policy_id) is None:
+            raise ValueError("policy_id has invalid syntax")
+        if type(self.policy_version) is not int or self.policy_version <= 0:
+            raise ValueError("policy_version must be positive")
+        require_sha256(self.policy_definition_sha256, "policy_definition_sha256")
+        if type(self.candidates) is not tuple or not self.candidates:
+            raise ValueError("capacity recourse must return a non-empty exact tuple")
+        if any(type(value) is not EvolutionCandidate for value in self.candidates):
+            raise TypeError("capacity recourse candidates must be exact")
+        for value in self.candidates:
+            EvolutionCandidate.__post_init__(value)
+        if len({value.candidate_id for value in self.candidates}) != len(self.candidates):
+            raise ValueError("capacity recourse candidate IDs must be unique")
+        if len({value.occurrence.configuration_hash for value in self.candidates}) != len(
+            self.candidates
+        ):
+            raise ValueError("capacity recourse configurations must be unique")
+        if type(self.evidence) is not FrozenJsonObject or freeze_json(self.evidence) is not self.evidence:
+            raise TypeError("evidence must be a frozen typed-JSON object")
+        computed = hashlib.sha256(
+            _RESULT_DOMAIN + _canonical_json(self._unsigned_record())
+        ).hexdigest()
+        if self.result_sha256 not in ("", computed):
+            raise ValueError("result_sha256 does not authenticate the result")
+        object.__setattr__(self, "result_sha256", computed)
+
+    def _unsigned_record(self) -> dict[str, object]:
+        return {
+            "schema_version": 1,
+            "request_sha256": self.request_sha256,
+            "policy": {
+                "policy_id": self.policy_id,
+                "policy_version": self.policy_version,
+                "definition_sha256": self.policy_definition_sha256,
+            },
+            "candidates": [_candidate_record(value) for value in self.candidates],
+            "evidence": thaw_json(self.evidence),
+        }
+
+    def to_record(self) -> dict[str, object]:
+        self.__post_init__()
+        return {**self._unsigned_record(), "result_sha256": self.result_sha256}
+
+
+@runtime_checkable
+class CampaignCapacityRecoursePort(Protocol):
+    """Fill every requested stage occurrence from the current optimizer state."""
+
+    policy_id: str
+    policy_version: int
+    definition_sha256: str
+
+    async def fill(
+        self,
+        request: CampaignCapacityRecourseRequest,
+    ) -> CampaignCapacityRecourseResult: ...
+
+
+def validate_campaign_capacity_recourse_result(
+    *,
+    port: CampaignCapacityRecoursePort,
+    request: CampaignCapacityRecourseRequest,
+    result: CampaignCapacityRecourseResult,
+) -> None:
+    identity = _policy_identity(port)
+    if type(request) is not CampaignCapacityRecourseRequest:
+        raise TypeError("request must be exact")
+    request.__post_init__()
+    if type(result) is not CampaignCapacityRecourseResult:
+        raise TypeError("capacity recourse returned a foreign result")
+    result.__post_init__()
+    if result.request_sha256 != request.request_sha256:
+        raise ValueError("capacity recourse result targets another request")
+    if (
+        result.policy_id,
+        result.policy_version,
+        result.policy_definition_sha256,
+    ) != identity:
+        raise ValueError("capacity recourse result has a foreign policy identity")
+    if len(result.candidates) != request.missing_candidate_occurrences:
+        raise ValueError("capacity recourse did not fill every missing occurrence")
+    if any(value.generation != request.generation for value in result.candidates):
+        raise ValueError("capacity recourse candidate has the wrong generation")
+    known_ids = {value.candidate_id for value in request.state.candidates}
+    known_configurations = {
+        value.occurrence.configuration_hash for value in request.state.candidates
+    }
+    if any(value.candidate_id in known_ids for value in result.candidates):
+        raise ValueError("capacity recourse repeated a known candidate occurrence")
+    if any(
+        value.occurrence.configuration_hash in known_configurations
+        for value in result.candidates
+    ):
+        raise ValueError("capacity recourse repeated an evaluated configuration")
+
+
+def validate_campaign_capacity_recourse_port(
+    port: CampaignCapacityRecoursePort,
+) -> tuple[str, int, str]:
+    return _policy_identity(port)
+
+
+__all__ = [
+    "CampaignCapacityRecoursePort",
+    "CampaignCapacityRecourseRequest",
+    "CampaignCapacityRecourseResult",
+    "validate_campaign_capacity_recourse_port",
+    "validate_campaign_capacity_recourse_result",
+]

agent_evolve/application/campaign_contextual_outcomes.py

@@ -0,0 +1,119 @@
+"""Campaign adapter for parent-aware empirical outcome history.
+
+The outcome ledger is deliberately independent from campaign execution.  This
+adapter joins the two at the last safe point before a selector request is
+built: it derives lineage and currently available action families from the
+authenticated campaign context, performs a prior-only query, and returns the
+bounded prompt projection expected by ``CampaignPortfolioContextEnricher``.
+
+No objective name, workload, model, or provider is encoded here.  Workloads
+with a stronger structural similarity notion may inject an exact relevance
+resolver without replacing the retrieval or audit boundary.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol, runtime_checkable
+
+from agent_evolve.application.portfolio_campaign_runtime import (
+    CampaignPortfolioWaveContext,
+)
+from agent_evolve.application.portfolio_outcome_feedback import (
+    ContextualOutcomeQuery,
+    PortfolioOutcomeFeedbackLedger,
+)
+from agent_evolve.domain.typed_json import FrozenJsonObject
+
+
+@runtime_checkable
+class CampaignOutcomeRelevanceResolver(Protocol):
+    """Return canonical family/path filters for one prospective wave."""
+
+    def resolve(
+        self,
+        context: CampaignPortfolioWaveContext,
+    ) -> tuple[tuple[str, ...], tuple[str, ...]]: ...
+
+
+@dataclass(frozen=True, slots=True)
+class AvailableFamilyOutcomeRelevance:
+    """Portable default: compare actions from families available to this parent."""
+
+    def resolve(
+        self,
+        context: CampaignPortfolioWaveContext,
+    ) -> tuple[tuple[str, ...], tuple[str, ...]]:
+        if type(context) is not CampaignPortfolioWaveContext:
+            raise TypeError("context must be an exact CampaignPortfolioWaveContext")
+        CampaignPortfolioWaveContext.__post_init__(context)
+        families = tuple(
+            sorted({option.family for option in context.variation.contract.options})
+        )
+        if not families:
+            raise ValueError("eligible variation contract contains no action family")
+        return families, ()
+
+
+@dataclass(slots=True)
+class ContextualOutcomeCampaignEnricher:
+    """Expose bounded prior outcomes with explicit transfer distance.
+
+    The returned object contains no card identity or model rationale.  Exact
+    same-parent evidence is ranked first, then direct-lineage evidence.  When
+    explicitly enabled, clearly labelled cross-lineage analogies rank last.
+    The campaign runtime attaches it under its reserved contextual-history key.
+    """
+
+    ledger: PortfolioOutcomeFeedbackLedger
+    max_actions: int = 24
+    include_cross_lineage_analogies: bool = False
+    relevance: CampaignOutcomeRelevanceResolver = AvailableFamilyOutcomeRelevance()
+
+    def __post_init__(self) -> None:
+        if type(self.ledger) is not PortfolioOutcomeFeedbackLedger:
+            raise TypeError("ledger must be an exact PortfolioOutcomeFeedbackLedger")
+        if type(self.max_actions) is not int or self.max_actions <= 0:
+            raise ValueError("max_actions must be a positive exact integer")
+        if type(self.include_cross_lineage_analogies) is not bool:
+            raise TypeError("include_cross_lineage_analogies must be an exact boolean")
+        if not isinstance(self.relevance, CampaignOutcomeRelevanceResolver):
+            raise TypeError("relevance must implement CampaignOutcomeRelevanceResolver")
+
+    @staticmethod
+    def _lineage(context: CampaignPortfolioWaveContext) -> tuple[str, ...]:
+        parent = context.parent
+        values = {value.value for value in parent.parent_ids}
+        if parent.common_ancestor_id is not None:
+            values.add(parent.common_ancestor_id.value)
+        return tuple(sorted(values))
+
+    def enrich(
+        self,
+        context: CampaignPortfolioWaveContext,
+    ) -> FrozenJsonObject:
+        self.__post_init__()
+        if type(context) is not CampaignPortfolioWaveContext:
+            raise TypeError("context must be an exact CampaignPortfolioWaveContext")
+        CampaignPortfolioWaveContext.__post_init__(context)
+        families, changed_paths = self.relevance.resolve(context)
+        query = ContextualOutcomeQuery(
+            current_parent_candidate_id=context.parent.candidate_id.value,
+            current_parent_configuration_sha256=(
+                context.parent.occurrence.configuration_hash
+            ),
+            cutoff_wave_index_exclusive=context.stage_request.step.generation,
+            lineage_candidate_ids=self._lineage(context),
+            families=families,
+            changed_paths=changed_paths,
+            max_actions=self.max_actions,
+            include_cross_lineage_analogies=(self.include_cross_lineage_analogies),
+        )
+        return self.ledger.contextual_history(query).to_prompt_record()
+
+
+__all__ = [
+    "AvailableFamilyOutcomeRelevance",
+    "CampaignOutcomeRelevanceResolver",
+    "ContextualOutcomeCampaignEnricher",
+]