autoforge-agent 0.4.0__py3-none-any.whl

autoforge/autonomy/selfmod.py

@@ -0,0 +1,146 @@
+"""Self-modification: the agent rewrites parts of itself, with a paper trail.
+
+The agent can change:
+  - its own system prompt
+  - the forge config (max rounds, promotion policy, which checks run)
+  - the routing weights (what it values when choosing tools)
+  - the autonomy policy itself
+
+Every change is an `Amendment`: a before/after diff, a rationale, a timestamp,
+and an accepted/rejected verdict. Amendments are immutable once written. The
+log is the accountability mechanism — freedom without memory of what you did
+with it is just chaos.
+
+A rejected amendment is kept too. Knowing what the agent *tried* to change is
+as informative as knowing what it succeeded in changing.
+"""
+from __future__ import annotations
+
+import copy
+import time
+from dataclasses import dataclass, field
+from typing import Any, Callable
+
+
+@dataclass
+class Amendment:
+    """One self-modification, recorded forever."""
+
+    target: str                     # "system_prompt" | "forge_config" | ...
+    rationale: str
+    before: Any
+    after: Any
+    accepted: bool = True
+    rejected_reason: str | None = None
+    timestamp: float = field(default_factory=time.time)
+
+    def is_noop(self) -> bool:
+        return self.before == self.after
+
+    def diff_summary(self) -> str:
+        b = str(self.before)
+        a = str(self.after)
+        if len(b) > 120:
+            b = b[:120] + "..."
+        if len(a) > 120:
+            a = a[:120] + "..."
+        return f"{self.target}: {b!r} -> {a!r}"
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "target": self.target,
+            "rationale": self.rationale,
+            "before": str(self.before)[:500],
+            "after": str(self.after)[:500],
+            "accepted": self.accepted,
+            "rejected_reason": self.rejected_reason,
+            "timestamp": self.timestamp,
+        }
+
+
+class SelfModifier:
+    """Applies and records self-modifications against a host object."""
+
+    def __init__(
+        self,
+        *,
+        require_rationale: bool = True,
+        log_all: bool = True,
+        veto: Callable[[Amendment], str | None] | None = None,
+    ) -> None:
+        self.require_rationale = require_rationale
+        self.log_all = log_all
+        self.veto = veto
+        self.amendments: list[Amendment] = []
+
+    def amend(
+        self,
+        host: Any,
+        target: str,
+        new_value: Any,
+        rationale: str = "",
+        *,
+        attr: str | None = None,
+        nested: tuple[str, ...] = (),
+    ) -> Amendment:
+        """Change `target` on `host` to `new_value`, recording the amendment.
+
+        `target` is a label for the log. `attr`/`nested` locate the real
+        attribute — left unset, `target` is used as the attribute name.
+        """
+        if self.require_rationale and not rationale.strip():
+            amend = Amendment(
+                target=target, rationale=rationale, before=None, after=new_value,
+                accepted=False, rejected_reason="rationale required but not provided",
+            )
+            self.amendments.append(amend)
+            return amend
+
+        # Resolve the container that holds the attribute
+        holder = host
+        for key in nested:
+            holder = getattr(holder, key)
+
+        attr_name = attr or target
+        before = copy.deepcopy(getattr(holder, attr_name, None))
+
+        amendment = Amendment(
+            target=target, rationale=rationale, before=before, after=new_value,
+        )
+
+        if amendment.is_noop():
+            amendment.accepted = False
+            amendment.rejected_reason = "no-op (value unchanged)"
+            self.amendments.append(amendment)
+            return amendment
+
+        if self.veto is not None:
+            reason = self.veto(amendment)
+            if reason:
+                amendment.accepted = False
+                amendment.rejected_reason = reason
+                self.amendments.append(amendment)
+                return amendment
+
+        setattr(holder, attr_name, new_value)
+        self.amendments.append(amendment)
+        return amendment
+
+    # -- introspection ---------------------------------------------------
+    def log(self) -> list[dict[str, Any]]:
+        return [a.to_dict() for a in self.amendments]
+
+    def accepted_count(self) -> int:
+        return sum(1 for a in self.amendments if a.accepted)
+
+    def rejected_count(self) -> int:
+        return sum(1 for a in self.amendments if not a.accepted)
+
+    def last_rationale(self) -> str | None:
+        for a in reversed(self.amendments):
+            if a.accepted:
+                return a.rationale
+        return None
+
+
+__all__ = ["SelfModifier", "Amendment"]

autoforge/autonomy/spawn.py

@@ -0,0 +1,227 @@
+"""Spawning: the agent creates other agents, freely.
+
+No pre-declared agent pool, no fixed orchestration graph. An agent decides at
+runtime that a subtask wants its own worker, and spawns one. The child can
+share the parent's tool registry (so tools forged by one are usable by all) or
+get an isolated one (so experiments don't pollute the parent's library).
+
+Two sharing modes:
+
+  SHARED  — same registry object. A tool the child forges is immediately
+            available to the parent. Fast convergence, but a bad tool
+            propagates.
+  ISOLATED — child gets a copy. It can forge freely; only tools that pass its
+            verification AND the parent approves are merged back.
+
+The parent chooses per-spawn. Default is SHARED, because the whole thesis is
+that a growing shared library is the point — isolation is for when you want to
+A/B a child's tool quality before trusting it.
+"""
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Callable
+
+from ..tools.registry import ToolRegistry
+from ..tools.spec import ToolSpec, ToolState
+from .roles import ceiling, role_brief
+
+
+class ShareMode(str, Enum):
+    SHARED = "shared"
+    ISOLATED = "isolated"
+
+
+@dataclass
+class SpawnRecord:
+    child_id: str
+    task: str
+    mode: str
+    parent_id: str
+    started: float = field(default_factory=time.time)
+    finished: float = 0.0
+    result: str = ""
+    tools_forged: list[str] = field(default_factory=list)
+    error: str | None = None
+    # Which role the child ran as, and — if it tried to reach past that role —
+    # what it was refused. A refusal is evidence the whitelist is live rather
+    # than decorative, so it is recorded rather than swallowed.
+    role: str = ""
+    refusals: list[str] = field(default_factory=list)
+    #: The directive the child was handed, kept so the trace shows the role
+    #: reached a model instead of only reaching a dataclass.
+    brief: str = ""
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "child_id": self.child_id,
+            "task": self.task[:200],
+            "mode": self.mode,
+            "role": self.role or None,
+            "brief_chars": len(self.brief),
+            "tools_forged": self.tools_forged,
+            "refusals": self.refusals,
+            "duration_s": round(self.finished - self.started, 2) if self.finished else None,
+            "error": self.error,
+        }
+
+
+@dataclass
+class Spawner:
+    """Creates child agents on demand.
+
+    `agent_factory(parent, registry) -> agent-like` must return an object with
+    a `.run(task) -> result` method whose result exposes `.content` and the
+    child's registry (if it forged anything).
+    """
+
+    registry: ToolRegistry
+    agent_factory: Callable[[Any, ToolRegistry], Any]
+    parent_id: str = "root"
+    spawn_count: int = 0
+    history: list[SpawnRecord] = field(default_factory=list)
+    max_depth: int = 8              # a limit the agent can raise, not a cage
+    policy: Any = None              # AutonomyPolicy | None — gates merge_back
+    _depth: int = 0
+
+    def spawn(
+        self,
+        task: str,
+        *,
+        mode: ShareMode = ShareMode.SHARED,
+        child_registry: ToolRegistry | None = None,
+        restrict_to: set[str] | list[str] | None = None,
+        role: str = "",
+        brief: str = "",
+        deny: Callable[[Any], str] | None = None,
+    ) -> SpawnRecord:
+        self.spawn_count += 1
+        child_id = f"{self.parent_id}.{self.spawn_count}"
+
+        # A role is enforceable on its own. The caller may add a whitelist, a
+        # richer brief (a node's hint on top of the role's), or a whole different
+        # ceiling — but naming a role is enough to get the role's behaviour, so
+        # there is no way to spawn a "critic" that is not held to a critic's
+        # limits by simply forgetting to pass one.
+        if role:
+            brief = brief or role_brief(role)
+            if deny is None:
+                deny = ceiling(role)
+
+        record = SpawnRecord(
+            child_id=child_id, task=task, mode=mode.value, parent_id=self.parent_id,
+            role=role, brief=brief,
+        )
+
+        if self._depth >= self.max_depth:
+            record.error = f"max spawn depth {self.max_depth} reached (raise it if needed)"
+            record.finished = time.time()
+            self.history.append(record)
+            return record
+
+        base_reg = self.registry if mode == ShareMode.SHARED else (
+            child_registry or ToolRegistry())
+        # A role's whitelist becomes a lens over the real registry, so the child
+        # can only see and call what its role allows. Registration still lands on
+        # base_reg — which is why the forged-tool diff is taken there: a child
+        # that forges something outside its whitelist really did create it, and
+        # hiding that from the parent would be the wrong kind of tidiness.
+        #
+        # `deny` is the role's capability ceiling, which is not a whitelist: a
+        # critic's tool set depends on what each tool does, and forged tools are
+        # named at runtime, so the ceiling has to be judged per-spec.
+        reg = base_reg.scoped(restrict_to or (), role=role, deny=deny)
+        before = set(base_reg.names())
+
+        try:
+            child = self.agent_factory(self, reg)
+            # Handed over after construction rather than through the factory
+            # signature, so an existing two-argument `agent_factory` — including
+            # the fakes in the tests — keeps working. A child that does not
+            # implement the hook is simply one that cannot be briefed, and the
+            # record says so by carrying an empty brief.
+            if brief:
+                hook = getattr(child, "apply_role", None)
+                if callable(hook):
+                    hook(brief, role)
+            result = child.run(task)
+            record.result = getattr(result, "content", str(result))
+        except Exception as exc:  # noqa: BLE001
+            record.error = f"{type(exc).__name__}: {exc}"
+
+        after = set(base_reg.names())
+        record.tools_forged = sorted(after - before)
+        record.refusals = list(getattr(reg, "refusals", []) or [])
+        record.finished = time.time()
+        self.history.append(record)
+        return record
+
+    def child_spawner(self, child_registry: ToolRegistry) -> "Spawner":
+        """A spawner for a child, one level deeper."""
+        return Spawner(
+            registry=child_registry,
+            agent_factory=self.agent_factory,
+            parent_id=f"{self.parent_id}.{self.spawn_count}",
+            max_depth=self.max_depth,
+            policy=self.policy,
+            _depth=self._depth + 1,
+        )
+
+    # -- merging isolated children back --------------------------------
+    def merge_back(
+        self,
+        child_registry: ToolRegistry,
+        *,
+        require_state: ToolState = ToolState.ACTIVE,
+        approve: Callable[[ToolSpec], bool] | None = None,
+    ) -> list[str]:
+        """Pull an isolated child's trusted tools into the parent library.
+
+        `approve=None` (the default) is not "no gate": it means the policy
+        decides. When may_promote_tools is off the child's tools may not be
+        sealed ACTIVE in the first place, so require_state already filters them
+        and merge_back ends up pulling nothing. Pass an explicit `approve`
+        callback to merge anyway, one spec at a time.
+        """
+        merged: list[str] = []
+        collect = self._collect_approved
+        for name, spec in child_registry._tools.items():
+            if spec.state != require_state:
+                continue
+            if not collect(spec, approve):
+                continue
+            self.registry.register(spec, replace=True)
+            merged.append(name)
+        return merged
+
+    @staticmethod
+    def _collect_approved(
+        spec: ToolSpec,
+        approve: Callable[[ToolSpec], bool] | None,
+    ) -> bool:
+        """Explicit callback always wins. With none, accept: require_state
+        already filtered, and the caller who owns the policy decides whether
+        merge_back is reachable at all (see `denied_reason`)."""
+        return approve(spec) if approve is not None else True
+
+    def denied_reason(self) -> str | None:
+        """Why merge_back would refuse to pull anything, or None if it won't."""
+        if self.policy is not None and not self.policy.may_promote_tools:
+            return (
+                "may_promote_tools is off: children may not seal tools ACTIVE, "
+                "so there is nothing at ACTIVE to merge. Pass approve=... to "
+                "accept on a case-by-case basis."
+            )
+        return None
+
+    def summary(self) -> dict[str, Any]:
+        return {
+            "spawned": self.spawn_count,
+            "max_depth": self.max_depth,
+            "children": [r.to_dict() for r in self.history],
+        }
+
+
+__all__ = ["Spawner", "SpawnRecord", "ShareMode"]

autoforge/autonomy/topology.py

@@ -0,0 +1,235 @@
+"""Agent topology: the agent can inspect and redesign its own multi-agent
+architecture.
+
+This is the dimension autoforge was missing relative to TPGO (ACL 2026).
+A single agent loop, however many tools it can forge, is still a single
+loop. The agent should be able to decide:
+
+  - How many agents exist in its system
+  - What role each agent plays
+  - How they communicate (tool bridge, shared registry, pipe)
+  - Which topology works better for which task type
+
+The topology is modelled as a directed graph where nodes are agent roles
+and edges are communication channels. The agent can mutate this graph,
+run trials, and keep the winning configuration.
+
+A topology is a *proposal*. It is not the runtime itself — the runtime
+reads a topology and instantiates the described agents.
+"""
+from __future__ import annotations
+
+import time
+import json
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+import re
+
+
+class RoleType(str, Enum):
+    COORDINATOR = "coordinator"   # delegates, merges results
+    WORKER = "worker"             # focused executor
+    CRITIC = "critic"             # reviews outputs, provides feedback
+    GATE = "gate"                 # filters/validates before passing on
+    FORGE = "forge"               # specialised tool-forging agent
+
+
+@dataclass
+class AgentNode:
+    """One agent in the topology."""
+    id: str
+    role: RoleType
+    system_prompt_hint: str = ""
+    tools_whitelist: list[str] = field(default_factory=list)
+    max_turns: int | None = None
+
+
+@dataclass
+class TopologyEdge:
+    """A communication channel between two agents."""
+    source: str
+    target: str
+    channel: str = "tool_call"    # tool_call | shared_registry | pipe | broadcast
+
+
+@dataclass
+class Topology:
+    """A complete multi-agent architecture proposal."""
+    nodes: list[AgentNode] = field(default_factory=list)
+    edges: list[TopologyEdge] = field(default_factory=list)
+    rationale: str = ""
+    created_at: float = field(default_factory=time.time)
+    fitness: float = 0.0           # set after evaluation
+    trials: int = 0
+
+    def add(self, node: AgentNode) -> "Topology":
+        self.nodes.append(node)
+        return self
+
+    def connect(self, source: str, target: str, channel: str = "tool_call") -> "Topology":
+        self.edges.append(TopologyEdge(source, target, channel))
+        return self
+
+    def validate(self) -> list[str]:
+        errors = []
+        ids = {n.id for n in self.nodes}
+        for e in self.edges:
+            if e.source not in ids:
+                errors.append(f"edge source {e.source!r} not in nodes")
+            if e.target not in ids:
+                errors.append(f"edge target {e.target!r} not in nodes")
+        return errors
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "nodes": [{"id": n.id, "role": n.role.value, "hint": n.system_prompt_hint[:80]}
+                      for n in self.nodes],
+            "edges": [{"from": e.source, "to": e.target, "channel": e.channel}
+                      for e in self.edges],
+            "rationale": self.rationale[:200],
+            "fitness": round(self.fitness, 3) if self.fitness else None,
+            "trials": self.trials,
+        }
+
+    @classmethod
+    def single_agent(cls, prompt_hint: str = "") -> "Topology":
+        return cls(
+            nodes=[AgentNode(id="main", role=RoleType.COORDINATOR,
+                             system_prompt_hint=prompt_hint)],
+        )
+
+
+_TOPOLOGY_MUTATE_SYSTEM = """You are an AI systems architect. You are given the current
+multi-agent topology and a task or failure report. Design an IMPROVED topology.
+
+The topology is a graph of agents. Each agent has:
+  - id: unique name
+  - role: coordinator | worker | critic | gate | forge
+  - system_prompt_hint: what this agent should focus on
+  - tools_whitelist: which tools it can access (empty = all)
+
+Edges define who talks to whom. Communication channels:
+  - tool_call: source calls target via a tool
+  - shared_registry: both share a tool library
+  - pipe: source streams results to target
+
+Rules for good topologies:
+- coordinators delegate and merge, they do NOT do fine work themselves
+- workers focus on one type of task
+- critics review worker outputs before they reach the coordinator
+- a forge agent specialises in tool creation, not task execution
+- keep it minimal — more agents means more latency
+- 2-4 agents is usually enough
+
+Output STRICT JSON only:
+{
+  "rationale": "why this topology fits the task",
+  "nodes": [{"id": "...", "role": "...", "system_prompt_hint": "...", "tools_whitelist": [...]}],
+  "edges": [{"source": "...", "target": "...", "channel": "tool_call"}]
+}
+"""
+
+_TOPOLOGY_ANALYSE_SYSTEM = """You are a systems analyst. Given a topology and a trace of
+execution (tool calls, errors, results), identify what went wrong architecturally.
+
+Output STRICT JSON:
+{
+  "bottleneck": "which agent/edge caused the problem",
+  "root_cause": "one sentence",
+  "suggested_change": "what to add/remove/reassign"
+}
+"""
+
+
+class TopologyDesigner:
+    """An LLM-powered topology creator and mutator."""
+
+    def __init__(self, llm: Any, generator_model: str | None = None) -> None:
+        self.llm = llm
+        self.generator_model = generator_model
+
+    def design(self, task: str, current_topology: Topology | None = None,
+               failure_report: str = "", max_agents: int = 4) -> Topology:
+        """Design a topology from scratch or mutate an existing one.
+
+        `max_agents` is a soft ceiling on team size, passed to the model as a
+        budget hint. The result is not truncated if the model overshoots —
+        clipping nodes would leave dangling edges and silently degrade the
+        whole design, which is worse than a slightly oversized team.
+        """
+        from ..core.message import Message
+        from ..forge.generator import extract_json
+
+        prompt = f"Task: {task}\n"
+        prompt += f"\nTeam-size budget: at most {max_agents} agents.\n"
+        if current_topology:
+            prompt += f"\nCurrent topology:\n{json.dumps(current_topology.to_dict(), indent=2)}\n"
+            prompt += f"\nCurrent fitness: {current_topology.fitness}\n"
+        if failure_report:
+            prompt += f"\nFailure report:\n{failure_report}\n"
+        prompt += "\nDesign the topology now."
+
+        resp = self.llm.chat(
+            [Message.system(_TOPOLOGY_MUTATE_SYSTEM), Message.user(prompt)],
+            tools=None,
+        )
+        data = extract_json(resp.content)
+        if data is None:
+            return Topology.single_agent(task)
+
+        return self._parse_topology(data, task)
+
+    def analyse(self, topology: Topology, trace: list[dict[str, Any]]) -> dict[str, str]:
+        """Analyse a topology's execution trace for bottlenecks."""
+        from ..core.message import Message
+        from ..forge.generator import extract_json
+
+        prompt = (
+            f"Topology:\n{json.dumps(topology.to_dict(), indent=2)}\n"
+            f"\nExecution trace (last 10 events):\n"
+            + "\n".join(
+                json.dumps(t, ensure_ascii=False)[:200]
+                for t in trace[-10:]
+            )
+            + "\nAnalyse and suggest improvements."
+        )
+        resp = self.llm.chat(
+            [Message.system(_TOPOLOGY_ANALYSE_SYSTEM), Message.user(prompt)],
+            tools=None,
+        )
+        data = extract_json(resp.content)
+        if data is None:
+            return {"bottleneck": "unknown", "root_cause": "analysis failed",
+                    "suggested_change": "retry"}
+        return {
+            "bottleneck": str(data.get("bottleneck", "unknown")),
+            "root_cause": str(data.get("root_cause", "")),
+            "suggested_change": str(data.get("suggested_change", "")),
+        }
+
+    @staticmethod
+    def _parse_topology(data: dict, fallback_task: str) -> Topology:
+        t = Topology(rationale=str(data.get("rationale", "")))
+        for n in data.get("nodes", []):
+            try:
+                role = RoleType(n.get("role", "worker"))
+            except ValueError:
+                role = RoleType.WORKER
+            t.add(AgentNode(
+                id=str(n.get("id", f"agent_{len(t.nodes)}")),
+                role=role,
+                system_prompt_hint=str(n.get("system_prompt_hint", "")),
+                tools_whitelist=list(n.get("tools_whitelist") or []),
+            ))
+        for e in data.get("edges", []):
+            t.connect(str(e.get("source", "")), str(e.get("target", "")),
+                      str(e.get("channel", "tool_call")))
+        errors = t.validate()
+        if errors:
+            # Degrade gracefully: return a simple topology rather than crashing
+            return Topology.single_agent(fallback_task)
+        return t
+
+
+__all__ = ["Topology", "TopologyDesigner", "AgentNode", "TopologyEdge", "RoleType"]