agentevolve-optimizer 0.5.0__py3-none-any.whl

agent_evolve/integrations/pydantic_ai/execution_binding.py

@@ -0,0 +1,138 @@
+"""Domain-neutral separation of scientific and execution call identities."""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, replace
+import hashlib
+import json
+from typing import Any
+
+from pydantic import BaseModel
+
+from agent_evolve.domain.ids import LLMCallId
+from agent_evolve.ports.structured_generator import StructuredGenerationRequest
+
+
+def _schema_bytes(output_type: type[object]) -> bytes:
+    if not issubclass(output_type, BaseModel):
+        raise TypeError("structured output type must be a Pydantic BaseModel")
+    return json.dumps(
+        output_type.model_json_schema(mode="validation"),
+        allow_nan=False,
+        ensure_ascii=True,
+        separators=(",", ":"),
+        sort_keys=True,
+    ).encode("ascii")
+
+
+@dataclass(frozen=True, slots=True)
+class StructuredScienceRequestBinding:
+    """Fingerprint one scientific request independently of its execution ID."""
+
+    science_call_id: str
+    operation: str
+    prompt_utf8_bytes: int
+    prompt_sha256: str
+    output_schema_utf8_bytes: int
+    output_schema_sha256: str
+    output_tool_name: str
+    max_output_tokens: int
+    temperature_hex: str | None
+
+    @classmethod
+    def from_request(
+        cls,
+        request: StructuredGenerationRequest[Any],
+    ) -> "StructuredScienceRequestBinding":
+        if type(request) is not StructuredGenerationRequest:
+            raise TypeError("request must be an exact StructuredGenerationRequest")
+        StructuredGenerationRequest.__post_init__(request)
+        prompt = request.prompt.encode("utf-8", errors="strict")
+        schema = _schema_bytes(request.output_type)
+        return cls(
+            science_call_id=request.call_id.value,
+            operation=request.operation,
+            prompt_utf8_bytes=len(prompt),
+            prompt_sha256=hashlib.sha256(prompt).hexdigest(),
+            output_schema_utf8_bytes=len(schema),
+            output_schema_sha256=hashlib.sha256(schema).hexdigest(),
+            output_tool_name=request.output_tool_name,
+            max_output_tokens=request.max_output_tokens,
+            temperature_hex=(
+                None
+                if request.temperature is None
+                else float(request.temperature).hex()
+            ),
+        )
+
+    def provider_fingerprint(self) -> tuple[object, ...]:
+        return (
+            self.operation,
+            self.prompt_utf8_bytes,
+            self.prompt_sha256,
+            self.output_schema_utf8_bytes,
+            self.output_schema_sha256,
+            self.output_tool_name,
+            self.max_output_tokens,
+            self.temperature_hex,
+        )
+
+
+def rebind_structured_execution_request(
+    request: StructuredGenerationRequest[Any],
+    *,
+    expected: StructuredScienceRequestBinding,
+    execution_call_id: LLMCallId,
+) -> StructuredGenerationRequest[Any]:
+    """Replace only queue identity after verifying the scientific payload."""
+
+    if type(expected) is not StructuredScienceRequestBinding:
+        raise TypeError("expected must be a StructuredScienceRequestBinding")
+    if type(execution_call_id) is not LLMCallId:
+        raise TypeError("execution_call_id must be an exact LLMCallId")
+    LLMCallId.__post_init__(execution_call_id)
+    observed = StructuredScienceRequestBinding.from_request(request)
+    if observed != expected:
+        raise ValueError("structured scientific request does not match its binding")
+    rebound = replace(request, call_id=execution_call_id)
+    rebound_binding = StructuredScienceRequestBinding.from_request(rebound)
+    if rebound_binding.provider_fingerprint() != expected.provider_fingerprint():
+        raise AssertionError("execution-ID rebinding changed provider-visible fields")
+    return rebound
+
+
+@dataclass(slots=True)
+class ExecutionIdRebindingRunner:
+    """Adapt a frozen scientific request to a fresh queue execution ID."""
+
+    runner: Callable[[StructuredGenerationRequest[Any]], Awaitable[object]]
+    expected: StructuredScienceRequestBinding
+    execution_call_id: LLMCallId
+
+    def __post_init__(self) -> None:
+        if not callable(self.runner):
+            raise TypeError("runner must be callable")
+        if type(self.expected) is not StructuredScienceRequestBinding:
+            raise TypeError("expected must be a StructuredScienceRequestBinding")
+        if type(self.execution_call_id) is not LLMCallId:
+            raise TypeError("execution_call_id must be an exact LLMCallId")
+        LLMCallId.__post_init__(self.execution_call_id)
+
+    async def __call__(
+        self,
+        request: StructuredGenerationRequest[Any],
+    ) -> object:
+        rebound = rebind_structured_execution_request(
+            request,
+            expected=self.expected,
+            execution_call_id=self.execution_call_id,
+        )
+        return await self.runner(rebound)
+
+
+__all__ = [
+    "ExecutionIdRebindingRunner",
+    "StructuredScienceRequestBinding",
+    "rebind_structured_execution_request",
+]

agent_evolve/integrations/pydantic_ai/forecast_geometry_action_committee.py

@@ -0,0 +1,217 @@
+"""Compose forecast-geometry ballots into one protected action committee."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import math
+
+from agent_evolve.application.protected_action_committee import (
+    ActionCommitteeArmBinding,
+    ProtectedActionCommitteePolicy,
+)
+from agent_evolve.application.materialized_action_broker import (
+    MaterializedSlateFeasibilityPort,
+)
+
+from .semantic_coverage_residual_portfolio import (
+    ForecastGeometryRacingResidualPortfolio,
+)
+
+
+@dataclass(frozen=True, slots=True)
+class ForecastGeometryActionCommitteePortfolio:
+    """The existing consequence arms behind one outcome-blind exact-K policy."""
+
+    source_portfolio: ForecastGeometryRacingResidualPortfolio
+    allocation: ProtectedActionCommitteePolicy
+    additional_arm_bindings: tuple[ActionCommitteeArmBinding, ...] = ()
+
+    def __post_init__(self) -> None:
+        if (
+            type(self.source_portfolio)
+            is not ForecastGeometryRacingResidualPortfolio
+        ):
+            raise TypeError("source_portfolio must be exact")
+        self.source_portfolio.__post_init__()
+        if type(self.allocation) is not ProtectedActionCommitteePolicy:
+            raise TypeError("allocation must be an exact protected committee")
+        self.allocation.__post_init__()
+        if (
+            type(self.additional_arm_bindings) is not tuple
+            or any(
+                type(value) is not ActionCommitteeArmBinding
+                for value in self.additional_arm_bindings
+            )
+        ):
+            raise TypeError(
+                "additional_arm_bindings must contain exact bindings"
+            )
+        for value in self.additional_arm_bindings:
+            value.__post_init__()
+        additional_ids = tuple(
+            value.arm_id for value in self.additional_arm_bindings
+        )
+        if additional_ids != tuple(sorted(set(additional_ids))):
+            raise ValueError(
+                "additional arm bindings must be unique and canonical"
+            )
+        source_identities = tuple(
+            sorted(
+                (
+                    value.branch_id,
+                    value.policy.policy_id,
+                    value.policy.policy_version,
+                    value.policy.definition_sha256,
+                )
+                for value in self.source_portfolio.planner.branch_bindings
+            )
+        )
+        committee_identities = tuple(
+            sorted(
+                (
+                    value.arm_id,
+                    value.policy.policy_id,
+                    value.policy.policy_version,
+                    value.policy.definition_sha256,
+                )
+                for value in self.allocation.arm_bindings
+            )
+        )
+        additional_identities = tuple(
+            sorted(
+                (
+                    value.arm_id,
+                    value.policy.policy_id,
+                    value.policy.policy_version,
+                    value.policy.definition_sha256,
+                )
+                for value in self.additional_arm_bindings
+            )
+        )
+        if committee_identities != tuple(
+            sorted((*source_identities, *additional_identities))
+        ):
+            raise ValueError(
+                "committee policies differ from source and additional arms"
+            )
+        if self.allocation.protected_arm_id != "forecast_neutral":
+            raise ValueError("forecast-neutral must remain the protected arm")
+
+
+def compose_forecast_geometry_action_committee(
+    *,
+    source_portfolio: ForecastGeometryRacingResidualPortfolio,
+    protected_slots: int,
+    audit_slots: int,
+    audit_seed_sha256: str,
+    arm_weights: tuple[tuple[str, float], ...] = (),
+    additional_arm_bindings: tuple[
+        ActionCommitteeArmBinding,
+        ...,
+    ] = (),
+    slate_feasibility: MaterializedSlateFeasibilityPort | None = None,
+) -> ForecastGeometryActionCommitteePortfolio:
+    """Replace complete-slate commitment with protected action aggregation.
+
+    ``source_portfolio`` is an interceptable bundle of already-composed
+    outcome-blind policies. Its sequential race is not executed. The committee
+    reuses the exact branch policies, including any source-exposure or hard-
+    feasibility wrappers, so workload adapters do not acquire another seam.
+    Optional additional bindings can expose independent, workload-neutral
+    support views such as raw prequential score or provider-native rank.
+    """
+
+    if (
+        type(source_portfolio)
+        is not ForecastGeometryRacingResidualPortfolio
+    ):
+        raise TypeError("source_portfolio must be exact")
+    source_portfolio.__post_init__()
+    source_bindings = source_portfolio.planner.branch_bindings
+    arm_ids = tuple(value.branch_id for value in source_bindings)
+    if (
+        type(additional_arm_bindings) is not tuple
+        or any(
+            type(value) is not ActionCommitteeArmBinding
+            for value in additional_arm_bindings
+        )
+    ):
+        raise TypeError(
+            "additional_arm_bindings must contain exact bindings"
+        )
+    for value in additional_arm_bindings:
+        value.__post_init__()
+    additional_ids = tuple(
+        value.arm_id for value in additional_arm_bindings
+    )
+    if additional_ids != tuple(sorted(set(additional_ids))):
+        raise ValueError(
+            "additional arm bindings must be unique and canonical"
+        )
+    if set(additional_ids) & set(arm_ids):
+        raise ValueError("additional arms collide with consequence arms")
+    if not arm_weights:
+        weight_by_arm = {arm_id: 1.0 for arm_id in arm_ids}
+    else:
+        if (
+            type(arm_weights) is not tuple
+            or arm_weights
+            != tuple(sorted(arm_weights, key=lambda value: value[0]))
+        ):
+            raise ValueError("arm_weights must be canonical")
+        weight_by_arm: dict[str, float] = {}
+        for arm_id, weight in arm_weights:
+            if (
+                type(arm_id) is not str
+                or arm_id in weight_by_arm
+                or type(weight) is not float
+                or not math.isfinite(weight)
+                or weight <= 0.0
+            ):
+                raise ValueError(
+                    "arm weights require unique IDs and positive finite floats"
+                )
+            weight_by_arm[arm_id] = weight
+        if set(weight_by_arm) != set(arm_ids):
+            raise ValueError("arm_weights must cover every consequence arm")
+
+    source_arm_bindings = tuple(
+        sorted(
+            (
+                ActionCommitteeArmBinding(
+                    arm_id=value.branch_id,
+                    policy=value.policy,
+                    weight=weight_by_arm[value.branch_id],
+                )
+                for value in source_bindings
+            ),
+            key=lambda value: value.arm_id,
+        )
+    )
+    allocation = ProtectedActionCommitteePolicy(
+        arm_bindings=tuple(
+            sorted(
+                (
+                    *source_arm_bindings,
+                    *additional_arm_bindings,
+                ),
+                key=lambda value: value.arm_id,
+            )
+        ),
+        protected_arm_id="forecast_neutral",
+        protected_slots=protected_slots,
+        audit_slots=audit_slots,
+        audit_seed_sha256=audit_seed_sha256,
+        slate_feasibility=slate_feasibility,
+    )
+    return ForecastGeometryActionCommitteePortfolio(
+        source_portfolio=source_portfolio,
+        allocation=allocation,
+        additional_arm_bindings=additional_arm_bindings,
+    )
+
+
+__all__ = [
+    "ForecastGeometryActionCommitteePortfolio",
+    "compose_forecast_geometry_action_committee",
+]

agent_evolve/integrations/pydantic_ai/harness.py

@@ -0,0 +1,159 @@
+"""pydantic-ai harness: typed structured outputs per op (no JSON-string round-trip).
+
+Prompt wording comes from the problem's ``Directives`` (``self.directives``); this
+adapter runs ``pydantic_ai.Agent`` with a typed ``output_type`` per op:
+``list[CandidateConfig]`` for candidate ops, ``list[str]`` / ``str`` for insights.
+"""
+
+from __future__ import annotations
+
+from typing import Any, List, Optional
+
+from agent_evolve.harness.base import HarnessBase, HarnessOutputError
+
+
+_AGENT_RUN_FAILED = object()
+
+
+def _attempt_agent_run_sync(agent: Any, instruction: str, settings: dict | None) -> Any:
+    """Run the framework behind an exception-state-clearing private boundary."""
+
+    try:
+        if settings is not None:
+            return agent.run_sync(instruction, model_settings=settings)
+        return agent.run_sync(instruction)
+    except Exception:
+        return _AGENT_RUN_FAILED
+
+
+class PydanticAIHarness(HarnessBase):
+    id = "pydantic_ai"
+
+    def __init__(self) -> None:
+        super().__init__()
+        self._last_output_type_contract = None
+
+    @property
+    def last_output_type_contract(self):
+        """The immutable contract bound to the most recent Agent execution."""
+
+        return self._last_output_type_contract
+
+    def _model_settings(self) -> Optional[dict]:
+        settings: dict = {}
+        if self.cfg.temperature is not None:
+            settings["temperature"] = self.cfg.temperature
+        # OpenRouter provider routing (pin official first-party provider, no fallbacks)
+        # flows through LLMConfig.extra as {"extra_body": {"provider": {...}}}.
+        extra_body = (self.cfg.extra or {}).get("extra_body")
+        if extra_body:
+            settings["extra_body"] = extra_body
+        return settings or None
+
+    def _output(self, output_type: Any, instruction: str) -> Any:
+        from pydantic_ai import Agent
+
+        from agent_evolve.integrations.pydantic_ai.boundary_codec import (
+            build_output_type_contract,
+            validate_output_type_contract,
+        )
+
+        # The application workflow is the sole retry owner. Framework output
+        # retries can issue a different repair prompt while the legacy/event
+        # layer still believes it is replaying one request, so they must remain
+        # disabled at this boundary. Provider-client transport retries are a
+        # separate M1e composition-root gate and are not asserted here.
+        # Reject unsupported/deferred output workflows and bind their canonical
+        # type/schema identity before any Agent request can execute.
+        self._last_output_type_contract = None
+        output_contract = build_output_type_contract(output_type)
+        agent = Agent(
+            self.cfg.model,
+            output_type=output_contract.output_type,
+            retries=0,
+        )
+        validate_output_type_contract(
+            output_contract,
+            compiled_json_schema=agent.output_json_schema(),
+        )
+        self._last_output_type_contract = output_contract
+        settings = self._model_settings()
+        res = _attempt_agent_run_sync(agent, instruction, settings)
+        if res is _AGENT_RUN_FAILED:
+            # Raised outside the private handler so framework ExceptionGroups,
+            # provider payloads, and secrets cannot survive as context/cause.
+            raise HarnessOutputError("pydantic_ai: agent execution failed") from None
+        self._observe_usage(res)
+        return res.output
+
+    def _observe_usage(self, res: Any) -> None:
+        """Surface per-call token usage to the loop's event observer (best-effort)."""
+        if self._observer is None:
+            return
+        try:
+            u = res.usage
+            if callable(u):  # older pydantic-ai exposed usage() as a method
+                u = u()
+        except Exception:
+            return
+        inp = getattr(u, "input_tokens", None)
+        if inp is None:
+            inp = getattr(u, "request_tokens", None)
+        out = getattr(u, "output_tokens", None)
+        if out is None:
+            out = getattr(u, "response_tokens", None)
+        self._observer({"kind": "llm_usage", "model": self.cfg.model,
+                        "input_tokens": inp, "output_tokens": out})
+
+    def _candidates(self, op: str, instruction: str) -> List[dict]:
+        # Wrap the typed list in a Proposal model with a thought_process field so
+        # the model reasons before committing to factors.
+        from pydantic import create_model
+
+        proposal = create_model(
+            "Proposal",
+            thought_process=(str, ...),
+            candidates=(List[self.candidate_type], ...),
+        )
+        result = self._output(proposal, instruction)
+        return self._to_dicts(result.candidates, op)
+
+    # -- ops -------------------------------------------------------------
+    def generate_initial(self, n):
+        self._observe("generate_initial")
+        return self._candidates("generate_initial", self.directives.compose_initial(self.context, n))
+
+    def regenerate(self, failed_str, n, constraint_instruction, performance_insights):
+        self._observe("regenerate")
+        instr = self.directives.compose_regenerate(
+            self.context, failed_str, n, constraint_instruction, performance_insights)
+        return self._candidates("regenerate", instr)
+
+    def generate_offspring(self, pareto_str, n, constraint_instruction, performance_insights):
+        self._observe("generate_offspring")
+        instr = self.directives.compose_offspring(
+            self.context, pareto_str, n, constraint_instruction, performance_insights)
+        return self._candidates("generate_offspring", instr)
+
+    def regenerate_offspring(self, failed_str, pareto_str, n,
+                             constraint_instruction, performance_insights):
+        self._observe("regenerate_offspring")
+        instr = self.directives.compose_regenerate_offspring(
+            self.context, failed_str, pareto_str, n, constraint_instruction, performance_insights)
+        return self._candidates("regenerate_offspring", instr)
+
+    def failure_insights(self, failed_str, n_failed):
+        self._observe("failure_insights")
+        instr = self.directives.compose_failure_insights(self.context, failed_str, n_failed)
+        return self._to_str_list(self._output(List[str], instr))
+
+    def constraint_instruction(self, failed_str, previous=None):
+        self._observe("constraint_instruction")
+        instr = self.directives.compose_constraint_instruction(self.context, failed_str, previous or "")
+        return str(self._output(str, instr)).strip()
+
+    def performance_insights(self, stats_str, pareto_str, previous=None):
+        self._observe("performance_insights")
+        instr = self.directives.compose_performance_insights(
+            self.context, stats_str, pareto_str, previous or "")
+        return str(self._output(str, instr)).strip()