autonomous-agent-algos 0.1.0__py3-none-any.whl

aaa/__init__.py

@@ -0,0 +1,10 @@
+"""AutonomousAgentAlgos (AAA): event-driven agent algorithms over arbitrary data."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("autonomous-agent-algos")
+except PackageNotFoundError:  # running from a source tree that was never installed
+    __version__ = "0+unknown"
+
+__all__ = ["__version__"]

aaa/algos/__init__.py

@@ -0,0 +1,26 @@
+from aaa.algos.control import FSM, Node, WorkflowGraph
+from aaa.algos.ensemble import RAGAgent, SelfConsistency, Supervisor
+from aaa.algos.loops import LLMLoop, ReAct, RecallConfig, ToolLoop
+from aaa.algos.plan import Plan, PlanAndExecute, Step
+from aaa.algos.refine import GenerateTestRepair, GeneratorCritic
+from aaa.algos.route import Route, Router
+
+__all__ = [
+    "FSM",
+    "GenerateTestRepair",
+    "GeneratorCritic",
+    "LLMLoop",
+    "Node",
+    "Plan",
+    "PlanAndExecute",
+    "RAGAgent",
+    "ReAct",
+    "RecallConfig",
+    "Route",
+    "Router",
+    "SelfConsistency",
+    "Step",
+    "Supervisor",
+    "ToolLoop",
+    "WorkflowGraph",
+]

aaa/algos/base.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+import json
+import re
+from typing import Any
+
+from aaa.core.outcome import OutcomeKind
+from aaa.events import Event
+from aaa.llm.types import LLMRequest, Message
+
+
+def llm_request(
+    parent: Event, req: LLMRequest, tag: str = "main", *, prev: str | None = None
+) -> Event:
+    """Build an `aaa.llm.requested` event.
+
+    With `prev` (the id of the previous request event of the SAME conversation), `req.messages`
+    must hold only the messages appended since that request's reply; the event then stores just
+    that delta plus a pointer. The LLM handler reconstructs the full transcript the provider
+    needs, so the log (and algorithm state) grows linearly with turns, not quadratically."""
+    body = req.model_dump(mode="json")
+    data: dict[str, Any] = {"request": body, "tag": tag}
+    if prev is not None:
+        data["conv"] = {"prev": prev, "delta": body["messages"]}
+        body["messages"] = []
+    return parent.caused("aaa.llm.requested", data)
+
+
+def finish(parent: Event, kind: OutcomeKind, value: Any = None, reason: str | None = None) -> Event:
+    return parent.caused(
+        "aaa.run.completed", {"kind": kind.value, "value": value, "reason": reason}
+    )
+
+
+def tool_request(parent: Event, call_id: str, name: str, arguments: dict[str, Any]) -> Event:
+    return parent.caused(
+        "aaa.tool.requested", {"call_id": call_id, "name": name, "arguments": arguments}
+    )
+
+
+_FENCE = re.compile(r"^```[a-zA-Z0-9_-]*\s*\n(.*?)\n```\s*$", re.DOTALL)
+
+
+def strip_fence(text: str) -> str:
+    t = text.strip()
+    m = _FENCE.match(t)
+    return m.group(1) if m else t
+
+
+def parse_json_obj(text: str | None) -> dict[str, Any] | None:
+    """Best-effort: a JSON object from raw model text (fenced or surrounded by prose)."""
+    if not text:
+        return None
+    t = strip_fence(text)
+    for cand in (t, t[t.find("{") : t.rfind("}") + 1] if "{" in t else ""):
+        try:
+            v = json.loads(cand)
+        except ValueError:
+            continue
+        if isinstance(v, dict):
+            return v
+    return None
+
+
+def render_result(payload: Any) -> str:
+    return payload if isinstance(payload, str) else json.dumps(payload, default=str)
+
+
+def first_started(hist: list[Event]) -> Event:
+    return next(e for e in hist if e.type == "aaa.run.started")
+
+
+def task_messages(inp: dict[str, Any], system: str) -> list[Message]:
+    if "messages" in inp:
+        return [Message.model_validate(m) for m in inp["messages"]]
+    msgs = [Message(role="system", content=system)] if system else []
+    msgs.append(Message(role="user", content=str(inp.get("task", ""))))
+    return msgs

aaa/algos/control.py

@@ -0,0 +1,183 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from aaa.algos.base import finish, tool_request
+from aaa.core.outcome import OutcomeKind
+from aaa.events import Event, Projection
+from aaa.runtime import Ctx
+
+
+@dataclass
+class Node:
+    """One workflow step = one tool call. `args(results, input)` builds its arguments from
+    upstream outputs; `when(results, input)` can skip it (skipped nodes yield None)."""
+
+    id: str
+    tool: str
+    after: list[str] = field(default_factory=list)
+    args: Callable[[dict[str, Any], dict[str, Any]], dict[str, Any]] | dict[str, Any] | None = None
+    when: Callable[[dict[str, Any], dict[str, Any]], bool] | None = None
+    on_error: str = "fail"  # "fail" | "continue"
+
+
+class _WF(BaseModel):
+    input: dict[str, Any] = Field(default_factory=dict)
+    results: dict[str, Any] = Field(default_factory=dict)
+    errors: dict[str, str] = Field(
+        default_factory=dict
+    )  # raw failures; on_error policy applied at read time
+    requested: list[str] = Field(default_factory=list)
+
+
+def _apply_wf(st: _WF, e: Event) -> _WF:
+    d = e.data
+    if e.type == "aaa.run.started":
+        st.input = d["input"]
+    elif e.type == "aaa.tool.requested":
+        st.requested.append(d["call_id"])
+    elif e.type == "aaa.node.skipped":
+        st.requested.append(d["node_id"])
+        st.results[d["node_id"]] = None
+    elif e.type == "aaa.tool.completed":
+        st.results[d["call_id"]] = d["result"]
+    elif e.type == "aaa.tool.failed":
+        st.errors[d["call_id"]] = f"{d['error']['type']}: {d['error']['message']}"
+    return st
+
+
+WF = Projection(_WF, _apply_wf, name="aaa.workflow", version=1, state_type=_WF)
+
+
+class WorkflowGraph:
+    """Deterministic DAG execution: no LLM decides control flow. Ready nodes run in parallel;
+    tools bring approval gates, timeouts, idempotency and budgets. Cyclic/stateful control
+    flow belongs to FSM. Output = `output` node id, a callable(results), or all results."""
+
+    name = "workflow"
+
+    def __init__(
+        self, nodes: list[Node], *, output: str | Callable[[dict[str, Any]], Any] | None = None
+    ) -> None:
+        ids = [n.id for n in nodes]
+        if len(set(ids)) != len(ids):
+            raise ValueError("duplicate node ids")
+        for n in nodes:
+            if missing := [a for a in n.after if a not in ids]:
+                raise ValueError(f"node {n.id} depends on unknown {missing}")
+        self.nodes = {n.id: n for n in nodes}
+        self._check_acyclic()
+        self.output = output
+
+    def _check_acyclic(self) -> None:
+        seen: set[str] = set()
+        todo = set(self.nodes)
+        while todo:
+            ready = {i for i in todo if all(a in seen for a in self.nodes[i].after)}
+            if not ready:
+                raise ValueError("workflow has a dependency cycle (use FSM for loops)")
+            seen |= ready
+            todo -= ready
+
+    def subscriptions(self) -> list[str]:
+        return ["aaa.run.started", "aaa.tool.completed", "aaa.tool.failed"]
+
+    async def on_event(self, e: Event, ctx: Ctx) -> list[Event]:
+        st = await ctx.project(WF)
+        inp, requested = st.input, set(st.requested)
+        results: dict[str, Any] = dict(st.results)
+        failed: dict[str, str] = {}
+        for k, msg in st.errors.items():
+            if self.nodes[k].on_error == "continue":
+                results[k] = None
+            else:
+                failed[k] = msg
+        if failed:
+            k, msg = next(iter(failed.items()))
+            return [finish(e, OutcomeKind.FAILED, reason=f"node {k} failed: {msg}")]
+        out: list[Event] = []
+        progress = True
+        while progress:  # fixpoint: skipping a node can make its dependents ready
+            progress = False
+            for n in self.nodes.values():
+                if n.id in requested or not all(a in results for a in n.after):
+                    continue
+                requested.add(n.id)
+                progress = True
+                if n.when and not n.when(results, inp):
+                    results[n.id] = None
+                    out.append(e.caused("aaa.node.skipped", {"node_id": n.id}))
+                    continue
+                args = n.args(results, inp) if callable(n.args) else dict(n.args or {})
+                out.append(tool_request(e, n.id, n.tool, args))
+        if all(i in results for i in self.nodes):
+            val = (
+                results[self.output]
+                if isinstance(self.output, str)
+                else (self.output(results) if self.output else results)
+            )
+            return [*out, finish(e, OutcomeKind.SUCCESS, val)]
+        return out
+
+
+class _FSM(BaseModel):
+    input: dict[str, Any] = Field(default_factory=dict)
+    path: list[str] = Field(default_factory=list)  # states entered after `initial`
+
+
+def _apply_fsm(st: _FSM, e: Event) -> _FSM:
+    if e.type == "aaa.run.started":
+        st.input = e.data["input"]
+    elif e.type == "aaa.fsm.transitioned":
+        st.path.append(e.data["to"])
+    return st
+
+
+FSM_STATE = Projection(_FSM, _apply_fsm, name="aaa.fsm", version=1, state_type=_FSM)
+
+Transition = str | Callable[[Event, dict[str, Any]], str | None]
+
+
+class FSM:
+    """Explicit finite-state machine driven by external/internal events. `transitions[state]
+    [event_type]` is the next state or a function(event, input) -> next state | None (guard).
+    `on_enter[state](event, input)` may return events (request a tool, an LLM call, ...).
+    Reaching a terminal state completes the run with the path taken. The current state is a
+    fold of `aaa.fsm.transitioned` events, so it survives restarts."""
+
+    name = "fsm"
+
+    def __init__(
+        self,
+        initial: str,
+        transitions: dict[str, dict[str, Transition]],
+        terminal: set[str],
+        on_enter: dict[str, Callable[[Event, dict[str, Any]], list[Event]]] | None = None,
+    ) -> None:
+        self.initial, self.transitions, self.terminal = initial, transitions, terminal
+        self.on_enter = on_enter or {}
+        self._types = sorted({t for m in transitions.values() for t in m})
+
+    def subscriptions(self) -> list[str]:
+        return ["aaa.run.started", *self._types]
+
+    async def on_event(self, e: Event, ctx: Ctx) -> list[Event]:
+        st = await ctx.project(FSM_STATE)
+        inp = st.input
+        path = [self.initial, *st.path]
+        cur = path[-1]
+        if e.type == "aaa.run.started":
+            return [*self.on_enter.get(cur, lambda *_: [])(e, inp)]
+        rule = self.transitions.get(cur, {}).get(e.type)
+        nxt = rule(e, inp) if callable(rule) else rule
+        if nxt is None:
+            return [e.caused("aaa.fsm.ignored", {"state": cur, "event": e.type})]
+        out = [e.caused("aaa.fsm.transitioned", {"from": cur, "to": nxt, "on": e.type})]
+        out += self.on_enter.get(nxt, lambda *_: [])(e, inp)
+        if nxt in self.terminal:
+            out.append(finish(e, OutcomeKind.SUCCESS, {"state": nxt, "path": [*path, nxt]}))
+        return out

aaa/algos/ensemble.py

@@ -0,0 +1,173 @@
+from __future__ import annotations
+
+import re
+from collections import Counter
+from collections.abc import Callable
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from aaa.algos.base import finish, llm_request
+from aaa.algos.loops import ToolLoop
+from aaa.core.outcome import OutcomeKind
+from aaa.data.index import Index
+from aaa.events import Event, Projection
+from aaa.llm.types import LLMRequest, LLMResponse, Message
+from aaa.runtime import Algorithm, Ctx
+from aaa.tools import Tool, ToolContext, ToolError, ToolRegistry, search_tool
+
+_ANS = re.compile(r"Answer:\s*(.+)", re.IGNORECASE)
+
+
+def default_extract(text: str) -> str:
+    m = _ANS.findall(text)
+    return (m[-1] if m else (text.strip().splitlines() or [""])[-1]).strip()
+
+
+def _norm(s: str) -> str:
+    return re.sub(r"[^\w\s.-]", "", s.lower()).strip().rstrip(".")
+
+
+class _Samples(BaseModel):
+    texts: list[str] = Field(
+        default_factory=list
+    )  # raw model text; `extract` is applied at read time
+    failures: int = 0
+
+
+def _apply_sample(st: _Samples, e: Event) -> _Samples:
+    if e.type == "aaa.llm.completed":
+        st.texts.append(LLMResponse.model_validate(e.data["response"]).message.content or "")
+    elif e.type == "aaa.llm.failed":
+        st.failures += 1
+    return st
+
+
+SAMPLES = Projection(_Samples, _apply_sample, name="aaa.samples", version=1, state_type=_Samples)
+
+
+class SelfConsistency:
+    """Sample N independent answers in parallel and return the majority (ties -> earliest).
+    Only worthwhile when answers can be compared exactly (math, classification, extraction)."""
+
+    name = "self_consistency"
+
+    def __init__(
+        self,
+        n: int = 5,
+        *,
+        temperature: float = 0.8,
+        model: str | None = None,
+        system: str = "Think step by step, then end with a line 'Answer: <final answer>'.",
+        extract: Callable[[str], str] = default_extract,
+    ) -> None:
+        self.n, self.temperature, self.model, self.system, self.extract = (
+            n,
+            temperature,
+            model,
+            system,
+            extract,
+        )
+
+    def subscriptions(self) -> list[str]:
+        return ["aaa.run.started", "aaa.llm.completed", "aaa.llm.failed"]
+
+    async def on_event(self, e: Event, ctx: Ctx) -> list[Event]:
+        if e.type == "aaa.run.started":
+            task = e.data["input"].get("task", "")
+            req = LLMRequest(
+                model=self.model,
+                params={"temperature": self.temperature},
+                messages=[
+                    Message(role="system", content=self.system),
+                    Message(role="user", content=str(task)),
+                ],
+            )
+            return [llm_request(e, req, f"s{i}") for i in range(self.n)]
+        st = await ctx.project(SAMPLES)
+        samples = [self.extract(t) for t in st.texts]
+        failures = st.failures
+        if len(samples) + failures < self.n:
+            return []
+        if not samples:
+            return [finish(e, OutcomeKind.FAILED, reason="all samples failed")]
+        votes = Counter(_norm(s) for s in samples)
+        best, count = max(
+            votes.items(), key=lambda kv: (kv[1], -[_norm(s) for s in samples].index(kv[0]))
+        )
+        answer = next(s for s in samples if _norm(s) == best)
+        return [
+            finish(
+                e,
+                OutcomeKind.SUCCESS,
+                {
+                    "answer": answer,
+                    "votes": count,
+                    "samples": len(samples),
+                    "agreement": round(count / len(samples), 3),
+                },
+            )
+        ]
+
+
+class RAGAgent(ToolLoop):
+    """Agentic RAG: a ToolLoop whose tool is retrieval over any `Index`. The model decides
+    when/what to retrieve and is told to ground and cite. Attach `ToolHandler(rag.tools)`."""
+
+    name = "rag_agent"
+    _PROMPT = (
+        "Answer using only evidence retrieved with the search tool. Cite passage ids like [d1]. "
+        "If the evidence is insufficient, say so instead of guessing."
+    )
+
+    def __init__(self, index: Index, *, k: int = 5, **kw: Any) -> None:
+        kw.setdefault("system", self._PROMPT)
+        super().__init__(ToolRegistry([search_tool(index, k=k)]), **kw)
+
+
+class Supervisor(ToolLoop):
+    """Centralized coordinator: an LLM delegates sub-tasks to named worker algorithms (each a
+    child run: own budget accounting, cancelled with the parent). Parallelism is bounded by the
+    'delegate' pool. Attach `ToolHandler(supervisor.tools)`."""
+
+    name = "supervisor"
+
+    def __init__(
+        self,
+        workers: dict[str, tuple[Algorithm, str]],
+        *,
+        extra_tools: list[Tool] | None = None,
+        **kw: Any,
+    ) -> None:
+        reg = ToolRegistry(extra_tools or [])
+        for wname, (algo, desc) in workers.items():
+            reg.add(self._delegate_tool(wname, algo, desc))
+        roster = "\n".join(f"- delegate_{k}: {d}" for k, (_, d) in workers.items())
+        kw.setdefault(
+            "system",
+            f"You coordinate specialist workers. Delegate sub-tasks (possibly in parallel), then combine their results.\n{roster}",
+        )
+        super().__init__(reg, **kw)
+
+    @staticmethod
+    def _delegate_tool(wname: str, algo: Algorithm, desc: str) -> Tool:
+        async def delegate(task: str, ctx: ToolContext) -> Any:
+            handle = await ctx.engine.start(
+                algo, {"task": task}, parent=ctx.run_id, tag=ctx.call_id
+            )
+            out = await handle.result()
+            if not out.ok:
+                raise ToolError(f"worker {wname} ended {out.kind.value}: {out.reason}")
+            return (
+                out.value["text"]
+                if isinstance(out.value, dict) and "text" in out.value
+                else out.value
+            )
+
+        return Tool(
+            delegate,
+            name=f"delegate_{wname}",
+            description=f"Delegate a self-contained sub-task. {desc}",
+            pool="delegate",
+            timeout_s=600,
+        )