archforge-optimizer 0.1.0__py3-none-any.whl

archforge/__init__.py

@@ -0,0 +1,76 @@
+"""ArchForge — a self-improving meta-layer over multi-agent systems.
+
+The **adapter kit** (the public API) lets an external project wrap any MAS as a
+``HostAdapter`` and evolve it; the core organs (Engine, Architect, Judge,
+Gatekeeper, stores) drive the Propose-Evaluate-Commit loop. See
+``docs/superpowers/specs/2026-07-30-adapter-kit-design.md`` for the kit design.
+
+Quick adapter sketch:
+
+    from archforge import (
+        BaseHostAdapter, BaseAgent, CallResult,
+        SpecBuilder, SEQUENCE, JOIN, run_loop, RunnerConfig,
+    )
+
+    class MyAgent(BaseAgent):
+        def call(self, prompt, cfg) -> CallResult:       # the one per-node hook
+            ...
+
+    class MyAdapter(BaseHostAdapter):
+        def make_agent(self, node) -> BaseAgent: ...
+
+    spec = (SpecBuilder().node(...).edge("a","b", kind=SEQUENCE).build())
+    r = run_loop(MyAdapter(), spec, suite, config=RunnerConfig(provider="gemini"))
+"""
+from __future__ import annotations
+
+# ── the contract (host/base.py) — already the seam; re-exported so an adapter
+#    author imports everything from one place (`archforge`). Unchanged modules.
+from archforge.host.base import Agent, AgentResponse, HostMAS, Runnable, Task
+
+# ── the adapter kit (host/adapters) — what every adapter subclasses / uses.
+from archforge.host.adapters import (
+    BaseAgent,
+    BaseHostAdapter,
+    BasePipeline,
+    CallResult,
+    KnobVote,
+    RunContext,
+    cfg_decay,
+    cfg_as_kwargs,
+    estimate_tokens,
+    run_id,
+    topo_order,
+)
+
+# ── Spec bootstrap DSL (spec_builder.py) — the universal floor.
+from archforge.spec_builder import (
+    CONDITIONAL,
+    EdgeType,
+    FANOUT,
+    JOIN,
+    SEQUENCE,
+    SpecBuildError,
+    SpecBuilder,
+)
+
+# ── the run entrypoint (runner.py) — wraps the Engine for embedders.
+from archforge.runner import RunnerConfig, run_cycle, run_loop
+
+from archforge.config import VERSION as __version__  # noqa: F401  (public API)
+
+__all__ = [
+    # contract
+    "HostMAS", "Agent", "Runnable", "Task", "AgentResponse",
+    # kit
+    "BaseHostAdapter", "BaseAgent", "BasePipeline", "CallResult",
+    "RunContext", "KnobVote", "cfg_decay", "cfg_as_kwargs",
+    "run_id", "topo_order", "estimate_tokens",
+    # Spec DSL
+    "SpecBuilder", "SpecBuildError", "EdgeType",
+    "JOIN", "FANOUT", "SEQUENCE", "CONDITIONAL",
+    # runner
+    "RunnerConfig", "run_cycle", "run_loop",
+    # version
+    "__version__",
+]

archforge/__main__.py

@@ -0,0 +1,10 @@
+"""Entry point for `python -m archforge`."""
+
+from __future__ import annotations
+
+import sys
+
+from archforge.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

archforge/architect.py

@@ -0,0 +1,442 @@
+"""The Architect — the P-E-C "Propose" step (spec §3, §4, §6).
+
+One cycle, one change. `next_attempt(...)` returns an `ArchitectResult`:
+
+  * status="proposed"   — a candidate Spec (incumbent + ONE mutation) + a `Change`
+                           record ready for the orchestrator to evaluate/commit.
+  * status="lint_rejected" — the candidate the Architect formed is structurally
+                           invalid; the linter's reasons are returned. The
+                           candidate NEVER reaches the SuiteRunner (spec E5).
+  * status="plateau"    — no non-dedup-blocked proposal remains; the loop should
+                           stop (spec E7/E8).
+
+Boundaries that keep the optimizer safe:
+  * The Architect is WRITE-FREE over stores. It READS AttemptStore for dedup
+    (E7) but never appends an Attempt — the orchestrator does that, so
+    proposal and commitment stay cleanly separated.
+  * `Change` is the persisted *metadata* (kind/target/diff/rationale/scope); the
+    concrete edit lives in the candidate Spec returned alongside it, built with
+    `archforge.mutate`. dedup keys off (parent, kind, target).
+  * Structural change kinds auto-tag `scope=STRUCTURAL` (defined in
+    archforge.models) — that tag, not the Architect, drives the hybrid gate (I4).
+
+The real `Architect` spends ONE LLM call per cycle (the locked budget); the
+`ScriptedArchitect` decides the proposal deterministically for tests.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal, Protocol, Sequence, runtime_checkable
+
+from pydantic import BaseModel, ConfigDict, Field
+
+import archforge.models as m
+from archforge.lint import LintError, lint
+from archforge.llm.base import LLMClient, Message, Role
+from archforge.mutate import apply_change
+from archforge.stores.attempt_store import AttemptStore
+
+
+# --------------------------------------------------------------------------- #
+# Credit assignment — where did the run lose points?
+# --------------------------------------------------------------------------- #
+
+
+class CreditAssignment(BaseModel):
+    """The node/route blamed for the incumbent's rubric loss (Architect/credit-assignment input)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    node_id: str | None = None        # the agent most responsible for the loss
+    route: str | None = None           # "from->to" if a route is to blame
+    sub_rubric: str | None = None      # the dimension lost
+    severity: float = 0.0              # 1.0 - blamed score, in [0, 1]
+
+
+def credit_assign(
+    incumbent: m.Spec,
+    worst_task_scores: Sequence[m.RunScore],
+) -> CreditAssignment | None:
+    """Localize the rubric loss to a node from per-step StepScores.
+
+    Deterministic: across the worst task's repeat scores, average each node's
+    sub-rubric scores; return the (node, dimension) with the lowest mean. Returns
+    None if no step_scores were recorded (nothing to assign blame to).
+    """
+
+    if not worst_task_scores:
+        return None
+    # sum per (node, dimension) across repeats
+    acc: dict[str, dict[str, list[float]]] = {}
+    for score in worst_task_scores:
+        for ss in score.step_scores:
+            dims = acc.setdefault(ss.node_id, {})
+            for dim, val in ss.sub_rubrics.items():
+                dims.setdefault(dim, []).append(val)
+    if not acc:
+        return None
+
+    # find the (node, dim) with the lowest mean
+    worst_node, worst_dim, worst_mean = None, None, 1.0
+    for node_id, dims in acc.items():
+        for dim, vals in dims.items():
+            mean = sum(vals) / len(vals)
+            if mean < worst_mean:
+                worst_mean, worst_node, worst_dim = mean, node_id, dim
+    if worst_node is None:
+        return None
+    return CreditAssignment(node_id=worst_node, sub_rubric=worst_dim,
+                            severity=1.0 - worst_mean)
+
+
+# --------------------------------------------------------------------------- #
+# Result + Proposal types
+# --------------------------------------------------------------------------- #
+
+
+ArchitectStatus = Literal["proposed", "lint_rejected", "plateau"]
+
+
+class ArchitectProposal(BaseModel):
+    """A concrete candidate (incumbent + one mutation) + its Change metadata."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    candidate: m.Spec
+    change: m.Change
+    blame: CreditAssignment | None = None
+
+
+class ArchitectResult(BaseModel):
+    """The discriminated outcome of one P-E-C Propose step."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    status: ArchitectStatus
+    proposal: ArchitectProposal | None = None
+    rejected_reasons: list[LintError] = Field(default_factory=list)
+    note: str | None = None  # why we rejected/plateaued (for the report)
+
+    @property
+    def proposed(self) -> bool:
+        return self.status == "proposed"
+
+
+# --------------------------------------------------------------------------- #
+# Architect protocol — real + scripted both satisfy this
+# --------------------------------------------------------------------------- #
+
+
+@runtime_checkable
+class ArchitectProtocol(Protocol):
+    def next_attempt(
+        self,
+        incumbent: m.Spec,
+        worst_task_scores: Sequence[m.RunScore],
+        *,
+        attempt_store: AttemptStore,
+    ) -> ArchitectResult: ...
+
+
+# --------------------------------------------------------------------------- #
+# Real Architect — one LLM call per cycle
+# --------------------------------------------------------------------------- #
+
+
+class Architect:
+    """LLM-backed P-E-C proposer. One `complete()` call per `next_attempt`."""
+
+    def __init__(self, llm: LLMClient, *, model: str) -> None:
+        self._llm = llm
+        self._model = model
+
+    def next_attempt(
+        self,
+        incumbent: m.Spec,
+        worst_task_scores: Sequence[m.RunScore],
+        *,
+        attempt_store: AttemptStore,
+    ) -> ArchitectResult:
+        blame = credit_assign(incumbent, worst_task_scores)
+        proposal = self._propose(incumbent, blame)
+        if proposal is None:
+            return _plateau("architect produced no proposal")
+
+        change = _change_from_payload(incumbent, proposal)
+        if change is None:
+            return _plateau("architect returned an unparseable change")
+
+        # Kind gate (shared): prompt_edit/model_swap apply ONLY to llm nodes.
+        mismatch = _kind_mismatch_note(incumbent, change)
+        if mismatch is not None:
+            return _plateau(mismatch)
+
+        # The LLM nests the edit under `payload`; mutate reads the inner fields.
+        edit = proposal.get("payload")
+        if not isinstance(edit, dict):
+            edit = {k: v for k, v in proposal.items() if k not in {"kind", "target", "rationale"}}
+
+        # structural mistakes that survive this far -> lint_rejected (E5)
+        try:
+            candidate = apply_change(incumbent, change, edit)
+        except Exception as exc:  # noqa: BLE001 — mutate is defensive
+            return _lint_rejected(_as_lint_errors(f"mutation failed: {exc}"))
+
+        errors = lint(candidate)
+        if errors:
+            return _lint_rejected(errors)
+
+        # dedup: skip a change already rejected/rolled-back on (parent, kind, target) (E7)
+        blocked = attempt_store.blocking(
+            incumbent.spec_id or incumbent.compute_spec_id(),
+            change.kind.value, change.target,
+        )
+        if blocked:
+            return _plateau(
+                f"(parent={incumbent.spec_id}, kind={change.kind.value}, "
+                f"target={change.target}) already tried: "
+                f"{[a.attempt_id for a in blocked]}"
+            )
+
+        return ArchitectResult(
+            status="proposed",
+            proposal=ArchitectProposal(candidate=candidate, change=change, blame=blame),
+        )
+
+    # --------------------------------------------------------------- internals
+    def _propose(
+        self, incumbent: m.Spec, blame: CreditAssignment | None
+    ) -> dict[str, Any] | None:
+        """One LLM call → a structured change payload. None on no proposal.
+
+        A valid-JSON-but-not-a-change response (no `kind`) is *not* a provider
+        outage: the model answered, just without a usable change this cycle. We
+        return the dict and let `_change_from_payload` turn the missing `kind`
+        into a `None` → plateau (E7/E8). A true outage (non-JSON) raises from the
+        client itself and propagates as `LLMError` for the loop to retry (E9).
+        """
+        messages = self._build_messages(incumbent, blame)
+        completion = self._llm.complete(
+            messages, model=self._model, temperature=0.2, response_format="json",
+        )
+        parsed = completion.parsed
+        return parsed if isinstance(parsed, dict) else None
+
+    def _build_messages(
+        self, incumbent: m.Spec, blame: CreditAssignment | None
+    ) -> list[Message]:
+        blame_text = (
+            f"Blame: node='{blame.node_id}', sub_rubric='{blame.sub_rubric}', "
+            f"severity={blame.severity:.2f}.\n"
+            if blame else "No clear blame node (runs near-perfect). Be conservative.\n"
+        )
+        return [
+            Message(
+                role=Role.SYSTEM,
+                content=(
+                    "You are the Architect of a multi-agent pipeline optimizer. "
+                    "Propose EXACTLY ONE small change to improve the incumbent Spec. "
+                    "Return JSON: {kind, target, rationale, payload}. `kind` ∈ "
+                    "{prompt_edit, knob, add_node, remove_node, rewire, model_swap}. "
+                    "`target` = node_id (or 'from,to' for rewire). `payload` carries "
+                    "the edit: {prompt} | {knobs:{...}} | {model} | {node, wiring} | "
+                    "{remove:[from,to], add:[from,to,type]}. Each Spec node has a "
+                    "`kind` ∈ {llm, rule, retriever, tool, symbolic} and a `tunable` "
+                    "allowlist of the EXTRA knobs it owns. `prompt_edit`/`model_swap` "
+                    "apply ONLY to `llm` nodes; `knob` may set `temperature`/`retries`/"
+                    "`max_tokens` on ANY node, plus any EXTRA key listed in that node's "
+                    "`tunable` (any other extra key is rejected); for non-`llm` nodes "
+                    "prefer `knob` edits to the node's own params (`top_k`,`threshold`,…) "
+                    "or graph edits. Make the change address the blame."
+                ),
+            ),
+            Message(
+                role=Role.USER,
+                content=(
+                    f"INCUMBENT SPEC (nodes + edges):\n{_spec_summary(incumbent)}\n\n"
+                    + blame_text
+                    + "Return the one-change JSON."
+                ),
+            ),
+        ]
+
+
+# --------------------------------------------------------------------------- #
+# ScriptedArchitect — deterministic, for tests
+# --------------------------------------------------------------------------- #
+
+
+class ScriptedArchitect:
+    """Deterministic Architect whose proposals are scripted by the test.
+
+    `propose(change, payload)` queues a proposal (popped per next_attempt). Use
+    `force_lint_error()` to make the next proposal intentionally malformed (E5).
+    `force_plateau()` makes the next call return a plateau. If the queue is empty
+    when next_attempt is called, it plateaus.
+    """
+
+    def __init__(self) -> None:
+        self._queue: list[tuple[m.Change, dict[str, Any]]] = []
+        self._lint_error: bool = False
+        self._force_plateau: bool = False
+        self.calls: list[m.Spec] = []  # incumbents seen, for assertions
+
+    def propose(self, change: m.Change, payload: dict[str, Any]) -> "ScriptedArchitect":
+        self._queue.append((change, payload))
+        return self
+
+    def force_lint_error(self) -> "ScriptedArchitect":
+        self._lint_error = True
+        return self
+
+    def force_plateau(self) -> "ScriptedArchitect":
+        self._force_plateau = True
+        return self
+
+    def next_attempt(
+        self,
+        incumbent: m.Spec,
+        worst_task_scores: Sequence[m.RunScore],
+        *,
+        attempt_store: AttemptStore,
+    ) -> ArchitectResult:
+        self.calls.append(incumbent)
+        if self._force_plateau:
+            self._force_plateau = False
+            return _plateau("scripted plateau")
+        if not self._queue:
+            return _plateau("no scripted proposal left")
+
+        change, payload = self._queue.pop(0)
+        if self._lint_error:
+            self._lint_error = False
+            # build something the linter will reject (orphan edge to a ghost node)
+            return _lint_rejected(_as_lint_errors("scripted malformed candidate"))
+
+        blame = credit_assign(incumbent, worst_task_scores)
+
+        # Kind gate (shared with the real Architect): prompt_edit/model_swap on a
+        # non-llm node plateaus deterministically — nothing committed. Mirrors the
+        # real path's `_kind_mismatch_note` so a scripted E2E exercises the same
+        # rule (the plan's verification step 5).
+        mismatch = _kind_mismatch_note(incumbent, change)
+        if mismatch is not None:
+            return _plateau(mismatch)
+
+        try:
+            candidate = apply_change(incumbent, change, payload)
+        except Exception as exc:  # noqa: BLE001
+            return _lint_rejected(_as_lint_errors(f"mutation failed: {exc}"))
+
+        errors = lint(candidate)
+        if errors:
+            return _lint_rejected(errors)
+
+        blocked = attempt_store.blocking(
+            incumbent.spec_id or incumbent.compute_spec_id(),
+            change.kind.value, change.target,
+        )
+        if blocked:
+            return _plateau(
+                f"scripted change already tried on (parent={incumbent.spec_id}, "
+                f"kind={change.kind.value}, target={change.target})"
+            )
+
+        return ArchitectResult(
+            status="proposed",
+            proposal=ArchitectProposal(candidate=candidate, change=change, blame=blame),
+        )
+
+
+# --------------------------------------------------------------------------- #
+# helpers
+# --------------------------------------------------------------------------- #
+
+
+def _change_from_payload(incumbent: m.Spec, payload: dict[str, Any]) -> m.Change | None:
+    """Build a Change (metadata) from the LLM's structured proposal + rationale."""
+    try:
+        kind = m.ChangeKind(payload["kind"])
+        target = str(payload["target"])
+        rationale = str(payload.get("rationale", ""))
+    except (KeyError, ValueError):
+        return None
+    diff = _describe_diff(kind, target, payload.get("payload", payload))
+    return m.Change.for_kind(kind, target, diff, rationale)
+
+
+def _describe_diff(kind: m.ChangeKind, target: str, payload: Any) -> str:
+    if kind is m.ChangeKind.PROMPT_EDIT:
+        return f"rewrite system_prompt of '{target}'"
+    if kind is m.ChangeKind.KNOB:
+        return f"tune knobs of '{target}'"
+    if kind is m.ChangeKind.MODEL_SWAP:
+        return f"swap model on '{target}'"
+    if kind is m.ChangeKind.ADD_NODE:
+        return f"add node '{target}'"
+    if kind is m.ChangeKind.REMOVE_NODE:
+        return f"remove node '{target}'"
+    if kind is m.ChangeKind.REWIRE:
+        return f"rewire edge at '{target}'"
+    return f"{kind.value} on '{target}'"
+
+
+def _node_opt(spec: m.Spec, node_id: str) -> m.Node | None:
+    """Safe node lookup that returns None instead of raising (decoupled from
+    mutate's private `_node`). Used by the kind gate so a missing target falls
+    through to the normal apply/lint path instead of being mis-plateaued here."""
+    return next((n for n in spec.nodes if n.node_id == node_id), None)
+
+
+def _kind_mismatch_note(spec: m.Spec, change: m.Change) -> str | None:
+    """Kind gate for prompt_edit/model_swap: they apply ONLY to ``llm`` nodes.
+
+    A change of one of those kinds aimed at a non-llm node is valid metadata
+    (not "unparseable") but a kind mismatch, so the candidate should plateau with
+    a precise note (same E7/E8 outcome, nothing committed) rather than mutate
+    silently editing an empty prompt/model on a node that ignores it (a no-op
+    candidate masquerading as a real change). Returns the plateau note when the
+    change must be dropped, or ``None`` to proceed. A missing target is NOT a
+    kind mismatch — return None so it falls through to apply/lint below, which
+    rejects the structural defect instead of being mis-plateaued here.
+
+    Shared by the real ``Architect`` and ``ScriptedArchitect`` so the rule is
+    enforced uniformly and is deterministically testable through the scripted path.
+    """
+    if change.kind not in (m.ChangeKind.PROMPT_EDIT, m.ChangeKind.MODEL_SWAP):
+        return None
+    tgt = _node_opt(spec, change.target)
+    if tgt is None or tgt.kind is m.NodeKind.LLM:
+        return None
+    return (f"{change.kind.value} on non-llm node '{change.target}' "
+            f"(kind={tgt.kind.value})")
+
+
+def _spec_summary(spec: m.Spec) -> str:
+    nodes = "\n".join(
+        f"- {n.node_id} [{n.role}] kind={n.kind.value} model={n.model or '—'} "
+        f"tunable={list(n.knobs.tunable) or '—'} prompt={n.system_prompt!r}"
+        for n in spec.nodes
+    )
+    edges = "\n".join(f"- {e.from_} -> {e.to} ({e.type.value})" for e in spec.edges)
+    return f"NODES:\n{nodes}\nEDGES:\n{edges}"
+
+
+def _plateau(note: str) -> ArchitectResult:
+    return ArchitectResult(status="plateau", note=note)
+
+
+def _lint_rejected(reasons: list[LintError]) -> ArchitectResult:
+    return ArchitectResult(status="lint_rejected", rejected_reasons=reasons,
+                           note="candidate failed the Spec Linter")
+
+
+def _as_lint_errors(text: str) -> list[LintError]:
+    return [LintError(code="self_loop", message=text, location=None)]
+
+
+__all__ = [
+    "CreditAssignment", "credit_assign",
+    "ArchitectProposal", "ArchitectResult", "ArchitectStatus",
+    "ArchitectProtocol", "Architect", "ScriptedArchitect",
+]