agentevolve-optimizer 0.5.0__py3-none-any.whl

agent_evolve/policies/llm_init.py

@@ -0,0 +1,267 @@
+"""Model-authored population initialization: the highest-leverage decision.
+
+Initialization shapes the entire trajectory -- every later operator recombines
+what the first generation contained. Until now that decision was schema-
+uniform noise; this seam lets the model propose the initial population from
+the domain card: on a sizing problem, textbook-informed starting points can
+place the run in a different basin before a single evaluation is spent.
+
+The authoring line, applied to initialization: every proposed member is
+validated VALUE-BY-VALUE against the declared domains (declared loci must
+hold declared values; undeclared loci must keep the template's value);
+rejected members are counted and their slots fall back to schema-uniform
+draws; the caller's own seeds always come first and always survive. The
+budget then arbitrates: proposed members are evaluated like any other
+candidate, and a bad initial population is paid for in the open.
+
+WHAT THE ASK IS FOR is a separate decision from who answers it, and ``style``
+declares it. ``"joint"`` -- the default, and every sealed row -- asks for one
+list that is individually strong AND collectively diverse. That single ask
+conflates two things, and the ladder measured the cost: median pool regret is
+better at reasoning effort ``none`` than at ``medium`` on 23 of 24 paired
+seeds, because deliberation buys DIVERSITY and the pool median pays for it.
+``"split"`` is the same one call with two labelled sub-asks -- k_exploit
+strongest individual bets, k_explore configurations covering distinct regions
+-- so effort and capability have a channel (the exploit subset) that is not
+diversity-conflated, and the telemetry labels every returned member so that
+subset can be scored on its own.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, List, Optional, Sequence
+
+from agent_evolve.policies.genetic import Locus, loci_of, locus_domain, read_locus
+
+__all__ = ["InitTelemetry", "author_initial_population", "INIT_PROMPT",
+           "SPLIT_INIT_PROMPT", "INIT_STYLES"]
+
+Config = Dict[str, Any]
+
+#: What the one initialization call asks for. See the module docstring.
+INIT_STYLES = ("joint", "split")
+
+#: The labels a returned member can carry, and the counter prefixes that go
+#: with them. ``"joint"`` and ``"unlabeled"`` are labels without a subset:
+#: nothing in the reply distinguished those members, so nothing counts them
+#: apart.
+_SUBSETS = ("exploit", "explore")
+
+
+@dataclass
+class InitTelemetry:
+    calls: int = 0
+    proposed: int = 0
+    accepted: int = 0
+    rejected_out_of_domain: int = 0
+    rejected_shape: int = 0
+    unparseable: int = 0
+    errors: int = 0
+    #: The split ask's two halves, counted apart. Zero under ``"joint"``, and
+    #: zero under a split reply that arrived as a bare list: a member nothing
+    #: labelled is not evidence about either half.
+    exploit_proposed: int = 0
+    exploit_accepted: int = 0
+    explore_proposed: int = 0
+    explore_accepted: int = 0
+    #: One label per RETURNED member, in the returned order -- so a scorer can
+    #: read the exploit subset's quality without re-deriving which member came
+    #: from which half. "exploit" | "explore" | "joint" | "unlabeled".
+    labels: List[str] = field(default_factory=list)
+
+    def as_dict(self) -> dict[str, int]:
+        return {name: getattr(self, name) for name in
+                ("calls", "proposed", "accepted", "rejected_out_of_domain",
+                 "rejected_shape", "unparseable", "errors",
+                 "exploit_proposed", "exploit_accepted",
+                 "explore_proposed", "explore_accepted")}
+
+
+INIT_PROMPT = """{context}
+
+You are proposing the INITIAL POPULATION for an evolutionary search over the
+problem above. These {k} configurations are the raw material every later
+recombination works with; they should be individually strong bets AND
+collectively diverse (covering distinct promising regions/trade-offs), based
+on what the parameters and objectives MEAN.
+
+Reply with ONLY a JSON list of exactly {k} configuration objects, each with
+every parameter field, every value taken from that parameter's declared
+domain. No commentary."""
+
+
+SPLIT_INIT_PROMPT = """{context}
+
+You are proposing the INITIAL POPULATION for an evolutionary search over the
+problem above. These {k} configurations are the raw material every later
+recombination works with, and they are asked for in TWO parts. Each part is
+optimized for its own thing and for nothing else.
+
+EXPLOIT: exactly {k_exploit} configurations that are the STRONGEST INDIVIDUAL
+BETS on the evidence of the card above -- what you would submit if only the
+single best member counted. Do not spend any of these on coverage.
+
+EXPLORE: exactly {k_explore} configurations covering DISTINCT promising
+regions and trade-offs of the space -- what you would submit if only the
+spread counted. Do not spend any of these on being individually safe.
+
+Every configuration in both parts carries every parameter field, with every
+value taken from that parameter's declared domain.
+
+Reply with ONLY this JSON shape and no other text:
+{{"exploit": [...], "explore": [...]}}"""
+
+
+def _bare_list(text: str) -> Optional[list]:
+    """The first bracketed run of *text* as a JSON list, or ``None``.
+
+    The parse every sealed initialization ran, factored out unchanged so that
+    both styles read a list the same way -- and so the split style's fallback
+    reads exactly what a joint reply would have been read as.
+    """
+
+    match = re.search(r"\[.*\]", text, re.S)
+    if match is None:
+        return None
+    try:
+        raw = json.loads(match.group(0))
+    except (ValueError, TypeError):
+        return None
+    return raw if isinstance(raw, list) else None
+
+
+def _labelled_lists(text: str) -> Optional[tuple[list, list]]:
+    """``(exploit, explore)`` from the split reply shape, or ``None``.
+
+    ``None`` whenever either key is missing or is not a list: the reply did
+    not answer the ask that was made, and this seam repairs nothing.
+    """
+
+    match = re.search(r"\{.*\}", text, re.S)
+    if match is None:
+        return None
+    try:
+        raw = json.loads(match.group(0))
+    except (ValueError, TypeError):
+        return None
+    if not isinstance(raw, dict):
+        return None
+    exploit, explore = raw.get("exploit"), raw.get("explore")
+    if not isinstance(exploit, list) or not isinstance(explore, list):
+        return None
+    return exploit, explore
+
+
+def _rejection(member: Any, template: Config, candidate_model: Any) -> Optional[str]:
+    """``None`` when *member* is admissible, else which counter it moves.
+
+    Value-by-value against the declared domains: a declared locus must hold a
+    declared value, an undeclared one must keep the template's. The one place
+    a member is judged, so both styles are judged identically.
+    """
+
+    if not isinstance(member, dict) or set(member) != set(template):
+        return "shape"
+    try:
+        member_loci = loci_of(member)
+    except Exception:
+        return "shape"
+    if member_loci != loci_of(template):
+        return "shape"
+    for locus in member_loci:
+        value = read_locus(member, locus)
+        domain = locus_domain(candidate_model, locus)
+        if domain:
+            if value not in domain:
+                return "domain"
+        elif value != read_locus(template, locus):
+            return "domain"
+    return None
+
+
+def author_initial_population(
+    complete: Callable[[str], str],
+    *,
+    candidate_model: Any,
+    template: Config,
+    k: int,
+    domain_context: str,
+    telemetry: Optional[InitTelemetry] = None,
+    style: str = "joint",
+) -> List[Config]:
+    """Up to *k* validated initial members; whatever is rejected costs a slot,
+    not the run -- the loop fills shortfalls schema-uniformly.
+
+    *style* is the ASK (see the module docstring). ``"joint"`` is the sealed
+    one, prompt and parse unchanged. ``"split"`` is one call carrying two
+    labelled sub-asks, ``k_exploit = (k + 1) // 2`` strongest bets first and
+    the rest coverage; the halves are capped separately, members come back
+    exploit-first, and every returned member is labelled in the telemetry. A
+    split reply missing either key is read as a bare list if one is there --
+    unlabelled, counted in no half -- and is otherwise unparseable. Nothing is
+    repaired, in either style.
+    """
+
+    if style not in INIT_STYLES:
+        raise ValueError(
+            f"init style must be one of {INIT_STYLES}, got {style!r}")
+
+    tel = telemetry if telemetry is not None else InitTelemetry()
+    tel.calls += 1
+    k_exploit = (k + 1) // 2
+    prompt = (
+        INIT_PROMPT.format(context=domain_context, k=k) if style == "joint"
+        else SPLIT_INIT_PROMPT.format(
+            context=domain_context, k=k, k_exploit=k_exploit,
+            k_explore=k - k_exploit)
+    )
+    try:
+        text = complete(prompt)
+    except Exception:
+        tel.errors += 1
+        return []
+
+    batches: tuple[tuple[str, list], ...]
+    if style == "joint":
+        raw = _bare_list(text)
+        if raw is None:
+            tel.unparseable += 1
+            return []
+        batches = (("joint", raw[:k]),)
+    else:
+        pair = _labelled_lists(text)
+        if pair is not None:
+            batches = (("exploit", pair[0][:k_exploit]),
+                       ("explore", pair[1][:k - k_exploit]))
+        else:
+            raw = _bare_list(text)
+            if raw is None:
+                tel.unparseable += 1
+                return []
+            batches = (("unlabeled", raw[:k]),)
+
+    accepted: List[Config] = []
+    for label, members in batches:
+        subset = label if label in _SUBSETS else None
+        for member in members:
+            tel.proposed += 1
+            if subset:
+                setattr(tel, f"{subset}_proposed",
+                        getattr(tel, f"{subset}_proposed") + 1)
+            reason = _rejection(member, template, candidate_model)
+            if reason == "shape":
+                tel.rejected_shape += 1
+                continue
+            if reason is not None:
+                tel.rejected_out_of_domain += 1
+                continue
+            tel.accepted += 1
+            if subset:
+                setattr(tel, f"{subset}_accepted",
+                        getattr(tel, f"{subset}_accepted") + 1)
+            tel.labels.append(label)
+            accepted.append(dict(member))
+    return accepted

agent_evolve/policies/llm_operator.py

@@ -0,0 +1,109 @@
+"""The model writes variation operators: moves, not candidates.
+
+A hand-rolled operator zoo encodes what its author guessed about structure
+in general. The model is asked once, from the schema and objective meanings,
+to write up to three ``vary`` functions encoding what THIS domain's
+structure rewards -- co-moving coupled parameters, preserving named motifs,
+reordering adjacent actions. Each authored operator becomes one arm in the
+measured portfolio: it earns offspring slots through survival credit, its
+children pass the material check or its slot falls back to the classical
+arm, and the preregistered retirement rule ends arms that never produce a
+survivor. The model authors the move; the run decides what it was worth.
+
+Extraction and gating mirror ``llm_surrogate``: fenced blocks only, the
+worker's own import gate applied at authoring time, every rejection counted.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Callable, List, Optional, Sequence
+
+from agent_evolve.core.authored import CONTRACTS, AuthoredArtifact, authored_artifact
+from agent_evolve.core.problem import ObjectiveSpec
+from agent_evolve.infrastructure.authored_worker import ALLOWED_IMPORTS
+from agent_evolve.policies.llm_surrogate import AuthorTelemetry, gate_source
+
+__all__ = ["author_operators", "OPERATOR_PROMPT"]
+
+
+OPERATOR_PROMPT = """You are writing VARIATION OPERATORS for a genetic \
+optimizer over a structured configuration space. An operator constructs one \
+child from two parents; good operators exploit what the parameters MEAN --
+co-move parameters that are physically coupled, preserve fragments that only \
+work together, reorder adjacent actions, move along known trade-offs.
+
+OBJECTIVES (name and direction):
+{goals}
+
+SEARCH SPACE:
+{schema}
+
+Write up to {max_operators} DIFFERENT operators. Each must be one Python \
+function with EXACTLY this signature:
+
+    {contract}
+
+Rules:
+- `loci` lists the heritable positions in order (sequence fields appear as
+  `name[i]`); `domains` maps each locus to its allowed values under the
+  current sampling prior. Every value you place must come from a parent at
+  that locus or from `domains` -- anything else is rejected and wastes the
+  slot.
+- Derive all randomness from `seed` (e.g. `random.Random(seed)`), so a child
+  is reproducible.
+- Standard library only; imports limited to: {imports}.
+- Each operator in its OWN fenced Python block, each defining `vary`.
+- Do not write candidates, wrappers, or commentary between blocks.
+
+Reply with ONLY the fenced code blocks."""
+
+
+_FENCE = re.compile(r"```(?:python)?\s*\n(.*?)```", re.S)
+
+
+def author_operators(
+    complete: Callable[[str], str],
+    *,
+    objectives: Sequence[ObjectiveSpec],
+    schema_text: str,
+    max_operators: int = 3,
+    attempts: int = 2,
+    telemetry: Optional[AuthorTelemetry] = None,
+) -> List[AuthoredArtifact]:
+    """Ask for up to *max_operators* ``vary`` functions; gate each block whole."""
+
+    tel = telemetry if telemetry is not None else AuthorTelemetry()
+    contract = CONTRACTS["operator"]
+    prompt = OPERATOR_PROMPT.format(
+        goals="\n".join(f"  {s.name}: {s.goal}imise" for s in objectives),
+        schema=schema_text,
+        max_operators=max_operators,
+        contract=contract.description,
+        imports=", ".join(sorted(ALLOWED_IMPORTS)),
+    )
+    for _attempt in range(max(1, attempts)):
+        tel.calls += 1
+        try:
+            text = complete(prompt)
+        except Exception:
+            tel.errors += 1
+            continue
+        blocks = _FENCE.findall(text)
+        if not blocks:
+            tel.no_code_block += 1
+            continue
+        artifacts: List[AuthoredArtifact] = []
+        for index, block in enumerate(blocks[:max_operators]):
+            source = gate_source(block, contract=contract, telemetry=tel)
+            if source is None:
+                continue
+            tel.accepted += 1
+            tel.sources.append(source)
+            artifacts.append(authored_artifact(
+                "operator", source,
+                name=f"llm_op{index + 1}", authored_by="llm",
+            ))
+        if artifacts:
+            return artifacts
+    return []

agent_evolve/policies/llm_prior.py

@@ -0,0 +1,194 @@
+"""A model reading a screen and proposing where to sample.
+
+The blind version of this does not work and the reason is worth stating: asked
+from the schema alone, a model reasons about a *plausible* instance of the
+domain rather than the one in front of it. Measured on an accelerator venue, it
+declined to exclude anything, arguing that registers trade latency against area
+-- sound in general, and false there, where latency was a function of one other
+locus entirely. What it lacked was a model of the evaluator, not domain
+knowledge. So this proposer never runs blind: it reads a screen.
+
+What it returns is a restriction over declared domains -- never a candidate,
+never a value the schema does not declare. That is the same choice-not-authoring
+line the chooser holds, applied to the generator rather than to the pair.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass, field
+from typing import Any, Callable, Mapping, Sequence
+
+from agent_evolve.core.problem import ObjectiveSpec
+from agent_evolve.policies.genetic import DomainRestriction, Locus, locus_domain
+from agent_evolve.policies.structure import Attribution, render_attribution
+
+__all__ = ["PriorTelemetry", "llm_prior_proposer", "PROMPT"]
+
+PROMPT = """\
+You are advising an optimizer that has already spent {n} of its evaluations on
+a screening design. The rest of the budget remains.
+
+OBJECTIVES ({goals}).
+
+THE SEARCH SPACE:
+{schema}
+
+WHAT THE SCREEN MEASURED. Per parameter value: the mean of each objective over
+the screened candidates carrying that value, and how many of them were
+non-dominated within the screen.
+{screen}
+
+Read this as evidence about how THIS evaluator behaves -- it may or may not
+match how such problems usually behave.
+
+YOUR TASK. Propose a sampling prior: for each parameter, either restrict
+sampling to a subset of its values, or leave it free. You are not choosing a
+candidate and must not propose one; you are shaping the distribution the
+optimizer draws from.
+
+Restricting to a genuinely better region multiplies the remaining budget.
+Restricting wrongly can put the best region out of reach. Over-restricting a
+parameter that spreads candidates ALONG the frontier destroys the diversity a
+multi-objective search needs. Leave a parameter free unless the screen gives
+you a reason.
+
+Reply with JSON only:
+{{"restrictions": {{"<param>": [allowed values...]}}, "free": ["<param>", ...]}}
+Every parameter appears exactly once, in "restrictions" or in "free".
+"""
+
+
+@dataclass
+class PriorTelemetry:
+    """What the proposer's replies did. Counted, never inferred."""
+
+    calls: int = 0
+    unparseable: int = 0
+    wrote_candidate: int = 0
+    out_of_domain: int = 0
+    empty: int = 0
+    restricted_loci: int = 0
+    errors: int = 0
+    proposals: list = field(default_factory=list)
+
+    def as_dict(self) -> dict[str, int]:
+        return {
+            "calls": self.calls,
+            "unparseable": self.unparseable,
+            "wrote_candidate": self.wrote_candidate,
+            "out_of_domain": self.out_of_domain,
+            "empty": self.empty,
+            "restricted_loci": self.restricted_loci,
+            "errors": self.errors,
+            "proposals": len(self.proposals),
+        }
+
+
+def _domains(candidate_model: Any, attr: Attribution) -> dict[str, tuple]:
+    names = list(dict.fromkeys(s.locus for s in attr.levels))
+    out: dict[str, tuple] = {}
+    for name in names:
+        base = name.split("[")[0]
+        domain = locus_domain(candidate_model, Locus(base))
+        if not domain:                       # a sequence element's own domain
+            index = name[name.find("[") + 1:-1] if "[" in name else None
+            domain = locus_domain(
+                candidate_model,
+                Locus(base, int(index)) if index is not None else Locus(base))
+        if domain:
+            out[base] = domain
+    return out
+
+
+def llm_prior_proposer(
+    complete: Callable[[str], str],
+    *,
+    objectives: Sequence[ObjectiveSpec],
+    telemetry: PriorTelemetry | None = None,
+    domain_context: str = "",
+) -> Callable[[Attribution, Any], DomainRestriction]:
+    """A :data:`~agent_evolve.policies.structure.PriorProposer` backed by *complete*.
+
+    A reply naming values the schema never declared is REJECTED whole, not
+    repaired: a repaired prior is the harness's prior wearing the model's name,
+    and the measurement it feeds would be attributing someone else's decision.
+    An unusable reply yields an empty restriction, which is exactly the
+    unguided sampling distribution -- the safe direction to fail in.
+    """
+
+    from agent_evolve.policies.semantics import objective_lines, parameter_lines
+
+    tel = telemetry if telemetry is not None else PriorTelemetry()
+    goals = ", ".join(objective_lines(objectives))
+    # An empty context contributes nothing to the prompt, so a caller that
+    # supplies no card gets the pre-semantics prompt byte-for-byte.
+    preamble = f"{domain_context.strip()}\n\n" if domain_context.strip() else ""
+
+    def propose(attr: Attribution, candidate_model: Any) -> DomainRestriction:
+        domains = _domains(candidate_model, attr)
+        if not domains:
+            return DomainRestriction({})
+        described = parameter_lines(candidate_model, fields=list(domains))
+        prompt = preamble + PROMPT.format(
+            n=attr.n_evaluated, goals=goals,
+            schema="\n".join(f"  {line}" for line in described)
+            if described else
+            "\n".join(f"  {k}: one of {list(v)}" for k, v in domains.items()),
+            screen=render_attribution(attr))
+        tel.calls += 1
+        try:
+            reply = complete(prompt)
+        except Exception:
+            tel.errors += 1
+            return DomainRestriction({})
+
+        match = re.search(r"\{.*\}", reply or "", re.S)
+        if not match:
+            tel.unparseable += 1
+            return DomainRestriction({})
+        try:
+            doc = json.loads(match.group(0))
+        except json.JSONDecodeError:
+            tel.unparseable += 1
+            return DomainRestriction({})
+        if not isinstance(doc, dict):
+            tel.unparseable += 1
+            return DomainRestriction({})
+
+        restrictions = doc.get("restrictions")
+        if not isinstance(restrictions, dict):
+            tel.unparseable += 1
+            return DomainRestriction({})
+        # A reply that hands back whole configurations is authoring, which this
+        # channel exists not to do. Detect it by shape: a mapping of parameter
+        # to a single scalar rather than to a list of allowed values.
+        if restrictions and all(
+                not isinstance(v, list) for v in restrictions.values()):
+            tel.wrote_candidate += 1
+            return DomainRestriction({})
+
+        allowed: dict[str, list] = {}
+        for key, values in restrictions.items():
+            domain = domains.get(key)
+            if domain is None or not isinstance(values, list) or not values:
+                tel.out_of_domain += 1
+                return DomainRestriction({})
+            kept = [v for v in values if v in domain]
+            if len(kept) != len(values):
+                tel.out_of_domain += 1
+                return DomainRestriction({})
+            if len(kept) < len(domain):
+                allowed[key] = kept
+
+        if not allowed:
+            tel.empty += 1
+        tel.restricted_loci += len(allowed)
+        tel.proposals.append(dict(allowed))
+        return DomainRestriction(allowed)
+
+    propose.telemetry = tel                  # type: ignore[attr-defined]
+    propose.mechanism = "prior"              # type: ignore[attr-defined]
+    propose.authored_by = "llm"              # type: ignore[attr-defined]
+    return propose