agentevolve-optimizer 0.5.0__py3-none-any.whl

agent_evolve/ports/variation_source.py

@@ -0,0 +1,226 @@
+"""Workload-neutral source labels for sealed finite variation options.
+
+Variation source is a property of how a candidate configuration entered the
+finite action universe.  It is deliberately independent of whether a language
+model retained the option or deterministic reconciliation inserted it.  The
+latter remains semantic-provenance evidence; conflating the two would split one
+proposal source across unrelated posterior arms.
+"""
+
+from __future__ import annotations
+
+import re
+
+from agent_evolve.domain.finite_variation import (
+    FiniteVariationContract,
+    FiniteVariationOption,
+)
+
+
+PRIMARY_VARIATION_SOURCE_ID = "primary"
+VARIATION_SOURCE_METADATA_KEY = "evaluation_source"
+VARIATION_SOURCE_MINIMUM_METADATA_KEY = "evaluation_source_minimum"
+VARIATION_SOURCE_RANK_METADATA_KEY = "evaluation_source_rank"
+VARIATION_OPERATOR_METADATA_KEY = "evaluation_operator"
+VARIATION_DIVERSITY_SIGNATURE_METADATA_KEY = "evaluation_diversity_signature"
+VARIATION_CANDIDATE_POOL_REQUIREMENT_METADATA_KEY = (
+    "candidate_pool_membership_requirement"
+)
+_SOURCE_ID = re.compile(r"^[a-z][a-z0-9_.:-]{0,255}$")
+
+
+def _source_id_from_validated_option(option: FiniteVariationOption) -> str:
+    """Project source metadata after one enclosing graph validation."""
+
+    source_id = dict(option.metadata).get(
+        VARIATION_SOURCE_METADATA_KEY,
+        PRIMARY_VARIATION_SOURCE_ID,
+    )
+    if _SOURCE_ID.fullmatch(source_id) is None:
+        raise ValueError("variation source ID must use the closed token grammar")
+    return source_id
+
+
+def finite_variation_source_id(option: FiniteVariationOption) -> str:
+    """Return one sealed source label, inheriting ``primary`` when absent."""
+
+    if type(option) is not FiniteVariationOption:
+        raise TypeError("option must be an exact FiniteVariationOption")
+    option.__post_init__()
+    return _source_id_from_validated_option(option)
+
+
+def finite_variation_source_by_option(
+    contract: FiniteVariationContract,
+) -> dict[str, str]:
+    """Project a finite contract into exact option-to-source attribution."""
+
+    if type(contract) is not FiniteVariationContract:
+        raise TypeError("contract must be an exact FiniteVariationContract")
+    contract.__post_init__()
+    return {
+        option.option_id: _source_id_from_validated_option(option)
+        for option in contract.options
+    }
+
+
+def finite_variation_source_ids(
+    contract: FiniteVariationContract,
+) -> tuple[str, ...]:
+    """Return the canonical source-arm universe declared by one contract."""
+
+    return tuple(sorted(set(finite_variation_source_by_option(contract).values())))
+
+
+def finite_variation_source_minimum_counts(
+    contract: FiniteVariationContract,
+) -> tuple[tuple[str, int], ...]:
+    """Project semantic evaluator-exposure floors from a finite contract.
+
+    The result deliberately names source counts rather than representative
+    option IDs.  Structural feasibility layers can therefore choose any
+    compatible action from a source while retaining one workload-neutral
+    inverted API.
+    """
+
+    if type(contract) is not FiniteVariationContract:
+        raise TypeError("contract must be an exact FiniteVariationContract")
+    contract.__post_init__()
+    available_by_source: dict[str, int] = {}
+    minimum_by_source: dict[str, int] = {}
+    for option in contract.options:
+        metadata = dict(option.metadata)
+        source_id = metadata.get(VARIATION_SOURCE_METADATA_KEY)
+        raw_minimum = metadata.get(VARIATION_SOURCE_MINIMUM_METADATA_KEY)
+        if source_id is None and raw_minimum is None:
+            continue
+        if source_id is None:
+            raise ValueError("source exposure minimum requires a source ID")
+        if source_id != _source_id_from_validated_option(option):
+            raise ValueError("source option metadata differs from its source ID")
+        if raw_minimum is None:
+            # Attribution and hard exposure are deliberately independent.
+            continue
+        if not raw_minimum.isascii() or not raw_minimum.isdigit():
+            raise ValueError("evaluation source minimum must be decimal digits")
+        minimum = int(raw_minimum)
+        if not 1 <= minimum < 8:
+            raise ValueError("evaluation source minimum must lie in [1, 8)")
+        previous = minimum_by_source.setdefault(source_id, minimum)
+        if previous != minimum:
+            raise ValueError("one proposal source declares inconsistent minimums")
+        available_by_source[source_id] = available_by_source.get(source_id, 0) + 1
+    for source_id, minimum in minimum_by_source.items():
+        if available_by_source[source_id] < minimum:
+            raise ValueError("proposal source cannot satisfy its exposure minimum")
+    return tuple(sorted(minimum_by_source.items()))
+
+
+def finite_variation_candidate_pool_required_option_ids(
+    contract: FiniteVariationContract,
+) -> tuple[str, ...]:
+    """Return options that must survive model-blind pool screening.
+
+    Pool membership is intentionally distinct from evaluator allocation.  An
+    upstream expert may need a complete reference slate exposed to the model
+    and downstream allocator without forcing that slate to consume every real
+    evaluation slot.  The closed metadata value prevents truthy-string or
+    workload-specific interpretations at the common-pool boundary.
+    """
+
+    if type(contract) is not FiniteVariationContract:
+        raise TypeError("contract must be an exact FiniteVariationContract")
+    contract.__post_init__()
+    required: list[str] = []
+    for option in contract.options:
+        raw = dict(option.metadata).get(
+            VARIATION_CANDIDATE_POOL_REQUIREMENT_METADATA_KEY
+        )
+        if raw is None:
+            continue
+        if raw != "required":
+            raise ValueError(
+                "candidate-pool membership requirement must be exactly required"
+            )
+        required.append(option.option_id)
+    return tuple(sorted(required))
+
+
+def _operator_id_from_validated_option(option: FiniteVariationOption) -> str:
+    """Project operator metadata after one enclosing graph validation."""
+
+    metadata = dict(option.metadata)
+    operator_id = metadata.get(VARIATION_OPERATOR_METADATA_KEY)
+    if operator_id is None:
+        operator_id = "composite" if "composition_radius" in metadata else "atomic"
+    if _SOURCE_ID.fullmatch(operator_id) is None:
+        raise ValueError("variation operator ID must use the closed token grammar")
+    return operator_id
+
+
+def finite_variation_operator_id(option: FiniteVariationOption) -> str:
+    """Return a typed operator arm without inspecting workload identifiers.
+
+    New catalogs may declare ``evaluation_operator`` explicitly.  Existing
+    authenticated radius-composition catalogs remain replayable through their
+    generic ``composition_radius`` metadata; all other options inherit the
+    primary atomic operator.
+    """
+
+    if type(option) is not FiniteVariationOption:
+        raise TypeError("option must be an exact FiniteVariationOption")
+    option.__post_init__()
+    return _operator_id_from_validated_option(option)
+
+
+def finite_variation_operator_by_option(
+    contract: FiniteVariationContract,
+) -> dict[str, str]:
+    """Project exact option-to-operator attribution in one validation pass."""
+
+    if type(contract) is not FiniteVariationContract:
+        raise TypeError("contract must be an exact FiniteVariationContract")
+    contract.__post_init__()
+    return {
+        option.option_id: _operator_id_from_validated_option(option)
+        for option in contract.options
+    }
+
+
+def finite_variation_diversity_signature(option: FiniteVariationOption) -> str:
+    """Return the adapter-declared typed diversity signature or action family.
+
+    This is an optional inverted-API seam.  The default preserves the existing
+    finite-family semantics; workloads can later expose a finer phenotype-safe
+    signature without teaching the search controller domain names.
+    """
+
+    if type(option) is not FiniteVariationOption:
+        raise TypeError("option must be an exact FiniteVariationOption")
+    option.__post_init__()
+    signature = dict(option.metadata).get(
+        VARIATION_DIVERSITY_SIGNATURE_METADATA_KEY,
+        option.family,
+    )
+    if _SOURCE_ID.fullmatch(signature) is None:
+        raise ValueError("diversity signature must use the closed token grammar")
+    return signature
+
+
+__all__ = [
+    "PRIMARY_VARIATION_SOURCE_ID",
+    "VARIATION_DIVERSITY_SIGNATURE_METADATA_KEY",
+    "VARIATION_CANDIDATE_POOL_REQUIREMENT_METADATA_KEY",
+    "VARIATION_OPERATOR_METADATA_KEY",
+    "VARIATION_SOURCE_METADATA_KEY",
+    "VARIATION_SOURCE_MINIMUM_METADATA_KEY",
+    "VARIATION_SOURCE_RANK_METADATA_KEY",
+    "finite_variation_diversity_signature",
+    "finite_variation_candidate_pool_required_option_ids",
+    "finite_variation_operator_by_option",
+    "finite_variation_operator_id",
+    "finite_variation_source_by_option",
+    "finite_variation_source_id",
+    "finite_variation_source_ids",
+    "finite_variation_source_minimum_counts",
+]

agent_evolve/proposal_mode.py

@@ -0,0 +1,157 @@
+"""Which operator the model is actually running, chosen per campaign.
+
+Two modes, and the difference between them is not a hyper-parameter -- it is
+which evolutionary operator exists at all.
+
+``catalogue``   the engine enumerates a finite set of parent-relative edits and
+                the model selects among them. Model authority is one opaque
+                identifier; every child configuration is engine-owned. Sealed by
+                :mod:`agent_evolve.domain.finite_variation`, replayed by
+                resolving the identifier against the sealed contract. This is the
+                constrained mode: it certifies feasibility by construction and it
+                makes allocation a well-posed scoring problem. It also means the
+                model never generates anything, so mutation, crossover, offspring
+                generation and population initialization are all absent, and only
+                selection remains.
+
+``generative``  the model emits configurations conforming to the problem's
+                ``candidate_model``, rejected by ``validate`` when illegal and
+                built by ``materialize``. Sealed by
+                :mod:`agent_evolve.domain.generative_emission`, replayed from the
+                emission itself. This is the path the five public obligations
+                always admitted; what was missing was the audit trail, which is
+                the other half of this module's job.
+
+**The matched null moves with the mode, and this module is where that is
+enforced.** A generative arm sampled from an unbounded schema must be compared
+against a null drawn from *that* schema, not from the catalogue the treatment no
+longer uses. Comparing across supports is failure mode 2 in this project's own
+taxonomy, and it is the easiest mistake to make here because the old null still
+runs and still produces a number.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Callable, Dict, Optional, Sequence
+
+from agent_evolve.application.generative_proposal_journal import (
+    candidate_schema_sha256,
+)
+from agent_evolve.harness.generative_seal import SealedGenerativeHarness
+from agent_evolve.proposers.random_proposer import RandomProposer
+
+__all__ = [
+    "CATALOGUE",
+    "GENERATIVE",
+    "PROPOSAL_MODES",
+    "ProposalSupport",
+    "build_generative_proposer",
+    "build_matched_null_proposer",
+    "describe_support",
+    "require_matched_support",
+]
+
+CATALOGUE = "catalogue"
+GENERATIVE = "generative"
+PROPOSAL_MODES = (GENERATIVE, CATALOGUE)
+
+
+@dataclass(frozen=True)
+class ProposalSupport:
+    """The space a proposer is allowed to draw from, named so it can be checked.
+
+    ``schema_sha256`` is present for the generative mode and is the whole story
+    there: the support *is* the schema. For the catalogue mode the support is the
+    sealed contract, which is parent-relative and therefore changes every
+    generation, so ``option_count`` describes one parent's neighbourhood rather
+    than the reachable space.
+    """
+
+    mode: str
+    schema_sha256: Optional[str] = None
+    option_count: Optional[int] = None
+
+    def __post_init__(self) -> None:
+        if self.mode not in PROPOSAL_MODES:
+            raise ValueError(f"mode must be one of {PROPOSAL_MODES}, got {self.mode!r}")
+        if self.mode == GENERATIVE and not self.schema_sha256:
+            raise ValueError("a generative support is identified by its schema digest")
+
+
+def describe_support(problem: Any, mode: str = GENERATIVE) -> ProposalSupport:
+    """Name the support a campaign in *mode* would draw from."""
+
+    if mode == GENERATIVE:
+        return ProposalSupport(
+            mode=GENERATIVE,
+            schema_sha256=candidate_schema_sha256(
+                getattr(problem, "candidate_model", None)
+            ),
+        )
+    return ProposalSupport(mode=CATALOGUE)
+
+
+def require_matched_support(
+    treatment: ProposalSupport, null: ProposalSupport
+) -> None:
+    """Refuse a comparison whose arms do not draw from the same space.
+
+    This is a hard failure and not a warning. A support mismatch does not make a
+    result noisy, it makes it about something other than what it claims, and the
+    number it produces looks entirely ordinary.
+    """
+
+    if treatment.mode != null.mode:
+        raise ValueError(
+            f"support mismatch: the treatment proposes in {treatment.mode!r} mode "
+            f"and the null in {null.mode!r} mode. The null has to move with the "
+            "treatment or the comparison measures the change of support."
+        )
+    if treatment.mode == GENERATIVE and treatment.schema_sha256 != null.schema_sha256:
+        raise ValueError(
+            "support mismatch: treatment and null sample different candidate "
+            f"schemas ({treatment.schema_sha256} vs {null.schema_sha256})."
+        )
+
+
+def build_generative_proposer(
+    problem: Any,
+    *,
+    delegate: Optional[Any] = None,
+    mode: str = "record",
+    validator: Optional[Callable[[Dict[str, Any]], Any]] = None,
+    sealed_calls: Sequence[Any] = (),
+    on_seal: Optional[Callable[[Dict[str, Any]], None]] = None,
+) -> SealedGenerativeHarness:
+    """Wrap *delegate* so its emissions are sealed against *problem*'s schema.
+
+    ``validator`` defaults to the problem's own ``validate``, which is the point:
+    the feasibility rule that gates the run is the same one the seal records, so
+    a replay cannot be told a different story about what was legal.
+    """
+
+    schema_sha256 = candidate_schema_sha256(getattr(problem, "candidate_model", None))
+    if validator is None:
+        validator = getattr(problem, "validate", None)
+    return SealedGenerativeHarness(
+        delegate,
+        candidate_schema_sha256=schema_sha256,
+        mode=mode,
+        validator=validator,
+        sealed_calls=sealed_calls,
+        on_seal=on_seal,
+    )
+
+
+def build_matched_null_proposer(problem: Any, *, seed: Optional[int] = None):
+    """The uninformed arm for a generative campaign: same schema, no model.
+
+    Returned rather than described, so an experiment cannot accidentally use the
+    catalogue-era null against a generative treatment. The schema digest it
+    reports is the same one :func:`build_generative_proposer` pins, and
+    :func:`require_matched_support` will say so.
+    """
+
+    candidate_schema_sha256(getattr(problem, "candidate_model", None))
+    return RandomProposer(seed=seed)

agent_evolve/proposers/__init__.py

@@ -0,0 +1,10 @@
+"""Proposers: where candidates come from.
+
+``random`` needs no credentials and is also the control arm every claim about
+a model should be measured against. ``llm`` is the model-driven proposer and
+resolves through the harness registry.
+"""
+
+from agent_evolve.proposers.random_proposer import RandomProposer
+
+__all__ = ["RandomProposer"]

agent_evolve/proposers/random_proposer.py

@@ -0,0 +1,188 @@
+"""A proposer that samples the candidate schema instead of calling a model.
+
+This exists for two reasons and serves both equally.
+
+It is the **credential-free path**: someone can install the package and watch
+the loop run end to end -- seeds, validation, materialization, evaluation, a
+Pareto front -- before deciding whether to spend anything on a provider.
+
+It is also the **honest baseline**. Uninformed sampling over the same schema,
+the same budget and the same evaluator is the control every claim in this
+project is measured against, and on one benchmark a single median random draw
+already accounted for roughly 80 percent of the hypervolume that a full
+optimization run produced. Anyone deciding whether a model is worth paying for
+on *their* problem should run this arm first. ``agent_evolve check`` does
+exactly that.
+
+Sampling is derived from the candidate model's JSON schema, so it needs no
+problem-specific code. It is deliberately uninformed: it never reads the Pareto
+front, the failures, or the insights, because a baseline that learned would not
+be a baseline.
+"""
+
+from __future__ import annotations
+
+import random
+import string
+from typing import Any, Dict, List, Optional, Sequence
+
+from agent_evolve.harness.base import HarnessBase
+
+__all__ = ["RandomProposer"]
+
+_MAX_TRIES_PER_CANDIDATE = 24
+
+
+class RandomProposer(HarnessBase):
+    """Uninformed sampler over the candidate schema. No provider, no network."""
+
+    id = "random"
+
+    #: This proposer synthesises no guidance. Declared rather than
+    #: discovered, so the loop skips the insight calls instead of warning
+    #: about an empty return that is correct.
+    provides_insights = False
+
+    def __init__(self, seed: Optional[int] = None) -> None:
+        super().__init__()
+        self._rng = random.Random(seed)
+        self.calls: List[str] = []
+
+    # -- the seven harness operations -------------------------------------
+    # Candidate ops sample; insight ops return nothing, because an uninformed
+    # baseline that produced guidance would not be uninformed.
+
+    def generate_initial(self, n: int) -> List[Dict[str, Any]]:
+        return self._sample(n, "generate_initial")
+
+    def regenerate(
+        self,
+        failed_str: str,
+        n: int,
+        constraint_instruction: str,
+        performance_insights: str,
+    ) -> List[Dict[str, Any]]:
+        return self._sample(n, "regenerate")
+
+    def generate_offspring(
+        self,
+        pareto_str: str,
+        n: int,
+        constraint_instruction: str,
+        performance_insights: str,
+    ) -> List[Dict[str, Any]]:
+        return self._sample(n, "generate_offspring")
+
+    def regenerate_offspring(
+        self,
+        failed_str: str,
+        pareto_str: str,
+        n: int,
+        constraint_instruction: str,
+        performance_insights: str,
+    ) -> List[Dict[str, Any]]:
+        return self._sample(n, "regenerate_offspring")
+
+    def failure_insights(self, failed_str: str, n_failed: int) -> List[str]:
+        return []
+
+    def constraint_instruction(self, failed_str: str, previous: Optional[str] = None) -> str:
+        return previous or ""
+
+    def performance_insights(
+        self,
+        stats_str: str,
+        pareto_str: str,
+        previous: Optional[str] = None,
+    ) -> str:
+        return previous or ""
+
+    # -- sampling ----------------------------------------------------------
+
+    def _sample(self, n: int, op: str) -> List[Dict[str, Any]]:
+        self.calls.append(op)
+        schema = self._schema()
+        return [self._draw_object(schema, schema) for _ in range(max(0, n))]
+
+    def _schema(self) -> Dict[str, Any]:
+        ctx = self._ctx
+        model = getattr(ctx, "candidate_model", None) if ctx is not None else None
+        if model is None:
+            return {}
+        try:
+            return model.model_json_schema()
+        except Exception:
+            return {}
+
+    def _resolve(self, node: Dict[str, Any], root: Dict[str, Any]) -> Dict[str, Any]:
+        seen = 0
+        while isinstance(node, dict) and "$ref" in node and seen < 8:
+            ref = node["$ref"]
+            seen += 1
+            if not ref.startswith("#/"):
+                return {}
+            target: Any = root
+            for part in ref[2:].split("/"):
+                if not isinstance(target, dict) or part not in target:
+                    return {}
+                target = target[part]
+            node = target if isinstance(target, dict) else {}
+        return node if isinstance(node, dict) else {}
+
+    def _draw_object(self, node: Dict[str, Any], root: Dict[str, Any]) -> Dict[str, Any]:
+        node = self._resolve(node, root)
+        props = node.get("properties") or {}
+        required = set(node.get("required") or props.keys())
+        out: Dict[str, Any] = {}
+        for name, sub in props.items():
+            if name in required:
+                out[name] = self._draw(sub, root)
+        return out
+
+    def _draw(self, node: Dict[str, Any], root: Dict[str, Any], depth: int = 0) -> Any:
+        node = self._resolve(node, root)
+        if depth > 6:
+            return None
+        if "enum" in node and node["enum"]:
+            return self._rng.choice(list(node["enum"]))
+        if "const" in node:
+            return node["const"]
+        for key in ("anyOf", "oneOf"):
+            if node.get(key):
+                return self._draw(self._rng.choice(list(node[key])), root, depth + 1)
+
+        kind = node.get("type")
+        if isinstance(kind, list):
+            kind = self._rng.choice([k for k in kind if k != "null"] or ["string"])
+
+        if kind == "integer":
+            lo = node.get("minimum", node.get("exclusiveMinimum", 0))
+            hi = node.get("maximum", node.get("exclusiveMaximum", lo + 16))
+            lo, hi = int(lo), int(hi)
+            return self._rng.randint(lo, hi) if hi >= lo else lo
+        if kind == "number":
+            lo = float(node.get("minimum", node.get("exclusiveMinimum", 0.0)))
+            hi = float(node.get("maximum", node.get("exclusiveMaximum", lo + 1.0)))
+            return self._rng.uniform(lo, hi) if hi >= lo else lo
+        if kind == "boolean":
+            return self._rng.random() < 0.5
+        if kind == "array":
+            items = node.get("items") or {}
+            lo = int(node.get("minItems", 1))
+            hi = int(node.get("maxItems", max(lo, 6)))
+            count = self._rng.randint(lo, hi) if hi >= lo else lo
+            drawn = [self._draw(items, root, depth + 1) for _ in range(count)]
+            if node.get("uniqueItems"):
+                unique: List[Any] = []
+                for value in drawn:
+                    if value not in unique:
+                        unique.append(value)
+                drawn = unique
+            return drawn
+        if kind == "object":
+            return self._draw_object(node, root)
+        if kind == "null":
+            return None
+
+        alphabet = string.ascii_lowercase
+        return "".join(self._rng.choice(alphabet) for _ in range(self._rng.randint(3, 8)))