agentevolve-optimizer 0.5.0__py3-none-any.whl

agent_evolve/ports/structured_output_budget.py

@@ -0,0 +1,120 @@
+"""Provider-neutral policy port for structured-output token budgets.
+
+The evolutionary engine emits two materially different typed workloads:
+candidate proposals and evidence reflections.  This port lets an experiment
+allocate their output budgets independently without teaching the engine about
+any benchmark or model provider.  The operation token remains available to
+custom policies for finer-grained, benchmark-neutral scheduling.
+"""
+
+from __future__ import annotations
+
+import re
+from enum import Enum
+from typing import Protocol, runtime_checkable
+
+from agent_evolve.ports.structured_generator import MAX_OUTPUT_TOKENS
+
+
+_POLICY_ID = re.compile(r"^[a-z][a-z0-9_.-]{0,95}$")
+_OPERATION_TOKEN = re.compile(r"^[a-z][a-z0-9_.-]{0,95}$")
+
+
+class StructuredOutputRequestKind(str, Enum):
+    """Closed agentic request classes with potentially different workloads."""
+
+    PROPOSAL = "proposal"
+    REFLECTION = "reflection"
+
+
+@runtime_checkable
+class StructuredOutputBudgetPolicy(Protocol):
+    """Resolve an output-token limit for one typed agentic operation."""
+
+    @property
+    def policy_id(self) -> str: ...
+
+    @property
+    def policy_version(self) -> int: ...
+
+    def max_output_tokens(
+        self,
+        *,
+        request_kind: StructuredOutputRequestKind,
+        operation: str,
+    ) -> int: ...
+
+
+def validate_structured_output_operation(operation: str) -> None:
+    """Validate the operation grammar shared with structured generation."""
+
+    if type(operation) is not str or _OPERATION_TOKEN.fullmatch(operation) is None:
+        raise ValueError("operation must use the closed lowercase token grammar")
+
+
+def structured_output_budget_policy_metadata(
+    policy: StructuredOutputBudgetPolicy,
+) -> tuple[str, int]:
+    """Validate and return stable scientific identity for a budget policy."""
+
+    if not isinstance(policy, StructuredOutputBudgetPolicy):
+        raise TypeError(
+            "structured_output_budget_policy must implement "
+            "StructuredOutputBudgetPolicy"
+        )
+    policy_id = policy.policy_id
+    policy_version = policy.policy_version
+    if type(policy_id) is not str or _POLICY_ID.fullmatch(policy_id) is None:
+        raise ValueError("structured-output budget policy_id is not canonical")
+    if type(policy_version) is not int or policy_version <= 0:
+        raise ValueError("structured-output budget policy_version must be positive")
+    return policy_id, policy_version
+
+
+def resolve_structured_output_budget(
+    policy: StructuredOutputBudgetPolicy,
+    *,
+    request_kind: StructuredOutputRequestKind,
+    operation: str,
+) -> int:
+    """Resolve a deterministic, bounded budget without trusting policy state.
+
+    The policy is called twice and its identity is checked around the calls.
+    This makes a mutable or time-varying experimental policy fail closed before
+    a provider request can escape the application boundary.
+    """
+
+    if type(request_kind) is not StructuredOutputRequestKind:
+        raise TypeError("request_kind must be an exact StructuredOutputRequestKind")
+    validate_structured_output_operation(operation)
+    metadata = structured_output_budget_policy_metadata(policy)
+    first = policy.max_output_tokens(
+        request_kind=request_kind,
+        operation=operation,
+    )
+    second = policy.max_output_tokens(
+        request_kind=request_kind,
+        operation=operation,
+    )
+    for value in (first, second):
+        if type(value) is not int or not 1 <= value <= MAX_OUTPUT_TOKENS:
+            raise ValueError(
+                "structured-output max_output_tokens must lie in "
+                f"[1, {MAX_OUTPUT_TOKENS}]"
+            )
+    if first != second:
+        raise ValueError("structured-output budget policy must be deterministic")
+    if structured_output_budget_policy_metadata(policy) != metadata:
+        raise ValueError(
+            "structured-output budget policy metadata changed during resolution"
+        )
+    return first
+
+
+__all__ = [
+    "StructuredOutputBudgetPolicy",
+    "StructuredOutputRequestKind",
+    "resolve_structured_output_budget",
+    "structured_output_budget_policy_metadata",
+    "validate_structured_output_operation",
+]

agent_evolve/ports/subprocess_boundary.py

@@ -0,0 +1,138 @@
+"""Workload-neutral contract for bounded child-process execution."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import hashlib
+import json
+import re
+from typing import Protocol, runtime_checkable
+
+
+EXPLICIT_ENVIRONMENT_BOUNDARY_DEFINITION_SHA256 = hashlib.sha256(
+    b"agent-evolve:explicit-environment-subprocess-boundary:v1;"
+    b"exact-argv;pinned-cwd;finite-timeout;capture-text;no-shell;"
+    b"ambient-environment-deny-by-default;sensitive-name-deny"
+).hexdigest()
+_ENVIRONMENT_NAME = re.compile(r"[A-Za-z_][A-Za-z0-9_]*")
+_SENSITIVE_NAME = re.compile(r"(?:KEY|TOKEN|SECRET|PASSWORD)$", re.IGNORECASE)
+
+
+def _canonical_sha256(value: object) -> str:
+    payload = json.dumps(
+        value,
+        ensure_ascii=True,
+        allow_nan=False,
+        sort_keys=True,
+        separators=(",", ":"),
+    ).encode("ascii")
+    return hashlib.sha256(payload).hexdigest()
+
+
+@dataclass(frozen=True, slots=True)
+class ChildProcessPolicy:
+    """Stable deny-by-default environment and execution policy."""
+
+    policy_id: str
+    policy_version: int
+    inherited_environment_allowlist: tuple[str, ...]
+    fixed_environment: tuple[tuple[str, str], ...] = ()
+
+    def __post_init__(self) -> None:
+        if type(self.policy_id) is not str or not self.policy_id:
+            raise ValueError("policy_id must be a non-empty string")
+        if type(self.policy_version) is not int or self.policy_version <= 0:
+            raise ValueError("policy_version must be a positive integer")
+        inherited = self.inherited_environment_allowlist
+        if (
+            type(inherited) is not tuple
+            or inherited != tuple(sorted(set(inherited)))
+            or any(type(name) is not str for name in inherited)
+        ):
+            raise ValueError(
+                "inherited_environment_allowlist must be a sorted unique tuple"
+            )
+        fixed = self.fixed_environment
+        if type(fixed) is not tuple or any(
+            type(item) is not tuple
+            or len(item) != 2
+            or type(item[0]) is not str
+            or type(item[1]) is not str
+            for item in fixed
+        ):
+            raise TypeError("fixed_environment must contain exact string pairs")
+        fixed_names = tuple(name for name, _ in fixed)
+        if fixed_names != tuple(sorted(set(fixed_names))):
+            raise ValueError("fixed_environment names must be sorted and unique")
+        all_names = inherited + fixed_names
+        if any(_ENVIRONMENT_NAME.fullmatch(name) is None for name in all_names):
+            raise ValueError("environment names must be canonical")
+        if any(_SENSITIVE_NAME.search(name) is not None for name in all_names):
+            raise ValueError("sensitive environment names cannot be allowlisted")
+        if set(inherited).intersection(fixed_names):
+            raise ValueError("fixed and inherited environment names must be disjoint")
+        if any("\x00" in value for _, value in fixed):
+            raise ValueError("fixed environment values cannot contain NUL")
+
+    def to_record(self) -> dict[str, object]:
+        return {
+            "schema_version": 1,
+            "policy_id": self.policy_id,
+            "policy_version": self.policy_version,
+            "implementation_definition_sha256": (
+                EXPLICIT_ENVIRONMENT_BOUNDARY_DEFINITION_SHA256
+            ),
+            "argv_policy": "preserve_exact_sequence_no_shell_v1",
+            "working_directory_policy": "required_pinned_absolute_directory_v1",
+            "timeout_policy": "required_finite_positive_seconds_v1",
+            "environment_policy": "ambient_deny_explicit_allowlist_v1",
+            "sensitive_name_policy": (
+                "reject_names_ending_key_token_secret_password_v1"
+            ),
+            "inherited_environment_allowlist": list(
+                self.inherited_environment_allowlist
+            ),
+            "fixed_environment": [
+                {"name": name, "value": value}
+                for name, value in self.fixed_environment
+            ],
+        }
+
+    @property
+    def identity_sha256(self) -> str:
+        return _canonical_sha256(self.to_record())
+
+
+@dataclass(frozen=True, slots=True)
+class ChildProcessResult:
+    returncode: int
+    stdout: str
+    stderr: str
+
+    def __post_init__(self) -> None:
+        if type(self.returncode) is not int:
+            raise TypeError("returncode must be an integer")
+        if type(self.stdout) is not str or type(self.stderr) is not str:
+            raise TypeError("captured output must be text")
+
+
+@runtime_checkable
+class BoundedSubprocessBoundary(Protocol):
+    """Execute exact argv under one stable, explicit process policy."""
+
+    @property
+    def identity_sha256(self) -> str: ...
+
+    def stable_record(self) -> dict[str, object]: ...
+
+    def invocation_observation(self, executable: str) -> dict[str, object]: ...
+
+    def run(self, argv: tuple[str, ...], *, timeout_s: float) -> ChildProcessResult: ...
+
+
+__all__ = [
+    "BoundedSubprocessBoundary",
+    "ChildProcessPolicy",
+    "ChildProcessResult",
+    "EXPLICIT_ENVIRONMENT_BOUNDARY_DEFINITION_SHA256",
+]