forum-engine 1.4.0__py3-none-any.whl

forum/__init__.py

@@ -0,0 +1,3 @@
+"""Forum: accountable multi-agent orchestration engine (pure core)."""
+
+__version__ = "1.4.0"

forum/actor.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+_STOP = object()
+
+
+class Actor:
+    """A minimal mailbox actor: an async receive loop over a queue."""
+
+    def __init__(self, name: str) -> None:
+        self.name = name
+        self.inbox: asyncio.Queue[Any] = asyncio.Queue()
+        self._task: asyncio.Task | None = None
+        self.error: BaseException | None = None
+
+    async def on_message(self, message: Any) -> None:
+        raise NotImplementedError
+
+    async def _loop(self) -> None:
+        while True:
+            message = await self.inbox.get()
+            if message is _STOP:
+                break
+            try:
+                await self.on_message(message)
+            except Exception as exc:  # let-it-crash, but observable
+                self.error = exc
+                break
+
+    def start(self) -> "Actor":
+        self._task = asyncio.create_task(self._loop())
+        return self
+
+    async def send(self, message: Any) -> None:
+        await self.inbox.put(message)
+
+    async def stop(self) -> None:
+        if self._task is None:
+            return
+        await self.inbox.put(_STOP)
+        await self._task

forum/api_executor.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import urllib.request
+
+from forum.executor import Assignment, Result
+
+
+class ApiExecutor:
+    """Drive a model via the Anthropic Messages API over stdlib ``urllib``.
+
+    Network IO lives here, at the edge. ``opener`` is a callable
+    ``(urllib.request.Request) -> bytes`` that performs the request; it is
+    injected in tests so no real network is hit. The default opens the request
+    with ``urllib.request.urlopen``. The blocking call runs off the event loop
+    via ``asyncio.to_thread``.
+    """
+
+    def __init__(
+        self,
+        model: str = "claude-sonnet-4-6",
+        *,
+        api_key_env: str = "ANTHROPIC_API_KEY",
+        base_url: str = "https://api.anthropic.com/v1/messages",
+        max_tokens: int = 1024,
+        opener=None,
+    ) -> None:
+        self._model = model
+        self._api_key_env = api_key_env
+        self._base_url = base_url
+        self._max_tokens = max_tokens
+        self._opener = opener or _default_opener
+
+    @property
+    def model_id(self) -> str:
+        return self._model
+
+    async def run(self, assignment: Assignment) -> Result:
+        request = self._build_request(assignment.instruction)
+        try:
+            raw = await asyncio.to_thread(self._opener, request)
+        except Exception as exc:
+            return Result(assignment.task_id, assignment.agent, f"error: {exc}", ok=False)
+        text = _extract_text(raw)
+        if text is None:
+            preview = raw.decode("utf-8", "replace") if isinstance(raw, (bytes, bytearray)) else str(raw)
+            return Result(
+                assignment.task_id, assignment.agent,
+                f"error: unexpected API response shape: {preview[:200]!r}", ok=False,
+            )
+        return Result(assignment.task_id, assignment.agent, text, ok=True)
+
+    def _build_request(self, instruction: str) -> urllib.request.Request:
+        body = json.dumps(
+            {
+                "model": self._model,
+                "max_tokens": self._max_tokens,
+                "messages": [{"role": "user", "content": instruction}],
+            }
+        ).encode("utf-8")
+        headers = {
+            "content-type": "application/json",
+            "anthropic-version": "2023-06-01",
+            "x-api-key": os.environ.get(self._api_key_env, ""),
+        }
+        return urllib.request.Request(self._base_url, data=body, headers=headers, method="POST")
+
+
+def _extract_text(raw) -> str | None:
+    """Pull the assistant text from an Anthropic Messages response, or None if
+    the payload is not the expected {"content": [{"text": ...}]} shape."""
+    try:
+        data = json.loads(raw)
+        content = data["content"]
+        if isinstance(content, list) and content and isinstance(content[0], dict) and "text" in content[0]:
+            return content[0]["text"]
+    except (json.JSONDecodeError, KeyError, TypeError):
+        return None
+    return None
+
+
+def _default_opener(request: urllib.request.Request) -> bytes:
+    with urllib.request.urlopen(request) as response:
+        return response.read()

forum/budget.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class RunBudget:
+    """A ceiling on a single run, so a loop cannot quietly run away.
+
+    ``max_model_calls`` caps how many times the executor is invoked across the
+    whole run (planning, dispatch, validation, synthesis); it is deterministic
+    and is the cost-relevant dimension. ``max_seconds`` is a best-effort wall
+    clock cap. A breach of either stops the run gracefully and is witnessed in
+    the ledger as a ``budget`` entry; the run stays verifiable.
+    """
+
+    max_model_calls: int | None = None
+    max_seconds: float | None = None

forum/chat_executor.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import urllib.request
+
+from forum.executor import Assignment, Result
+
+
+class ChatExecutor:
+    """Drive any OpenAI-compatible chat-completions endpoint over stdlib urllib.
+
+    This is the model-agnostic path. It speaks the widely-implemented
+    ``/v1/chat/completions`` protocol, so it works with local servers that need
+    no account (Ollama, LM Studio, llama.cpp, vLLM) and with OpenAI-compatible
+    cloud providers alike. Point ``base_url`` at your server and name the model.
+    An API key is optional (local servers usually need none); when ``api_key_env``
+    names a non-empty environment variable, its value is sent as a Bearer token.
+
+    Network IO lives here, at the edge. ``opener`` is a callable
+    ``(urllib.request.Request) -> bytes`` injected in tests so no real network is
+    hit; the blocking call runs off the event loop via ``asyncio.to_thread``.
+    """
+
+    def __init__(
+        self,
+        model: str,
+        *,
+        base_url: str = "http://localhost:11434/v1/chat/completions",
+        api_key_env: str | None = None,
+        max_tokens: int = 1024,
+        opener=None,
+    ) -> None:
+        self._model = model
+        self._base_url = base_url
+        self._api_key_env = api_key_env
+        self._max_tokens = max_tokens
+        self._opener = opener or _default_opener
+
+    @property
+    def model_id(self) -> str:
+        return self._model
+
+    async def run(self, assignment: Assignment) -> Result:
+        request = self._build_request(assignment.instruction)
+        try:
+            raw = await asyncio.to_thread(self._opener, request)
+        except Exception as exc:
+            return Result(assignment.task_id, assignment.agent, f"error: {exc}", ok=False)
+        text = _extract_text(raw)
+        if text is None:
+            preview = raw.decode("utf-8", "replace") if isinstance(raw, (bytes, bytearray)) else str(raw)
+            return Result(
+                assignment.task_id, assignment.agent,
+                f"error: unexpected chat response shape: {preview[:200]!r}", ok=False,
+            )
+        return Result(assignment.task_id, assignment.agent, text, ok=True)
+
+    def _build_request(self, instruction: str) -> urllib.request.Request:
+        body = json.dumps(
+            {
+                "model": self._model,
+                # max_tokens is accepted by OpenAI (back-compat) and by every local
+                # server we target; newer OpenAI models also accept max_completion_tokens.
+                "max_tokens": self._max_tokens,
+                "messages": [{"role": "user", "content": instruction}],
+            }
+        ).encode("utf-8")
+        headers = {"content-type": "application/json"}
+        if self._api_key_env:
+            key = os.environ.get(self._api_key_env, "")
+            if key:
+                headers["authorization"] = f"Bearer {key}"
+        return urllib.request.Request(self._base_url, data=body, headers=headers, method="POST")
+
+
+def _extract_text(raw) -> str | None:
+    """Pull the assistant text from an OpenAI-compatible chat-completions reply,
+    or None if the payload is not the expected choices[0].message.content shape."""
+    try:
+        data = json.loads(raw)
+        choices = data["choices"]
+        if isinstance(choices, list) and choices and isinstance(choices[0], dict):
+            message = choices[0].get("message")
+            if isinstance(message, dict):
+                content = message.get("content")
+                if isinstance(content, str):
+                    return content
+                if isinstance(content, list):
+                    # some OpenAI-compatible gateways return content as a list of
+                    # {type, text} parts; join the text parts
+                    joined = "".join(p.get("text", "") for p in content if isinstance(p, dict))
+                    if joined:
+                        return joined
+    except (json.JSONDecodeError, KeyError, TypeError):
+        return None
+    return None
+
+
+def _default_opener(request: urllib.request.Request) -> bytes:
+    with urllib.request.urlopen(request) as response:
+        return response.read()

forum/cli.py

@@ -0,0 +1,264 @@
+from __future__ import annotations
+
+import argparse
+import asyncio
+import dataclasses
+import json
+import shlex
+import sys
+
+from forum import __version__
+
+DEFAULT_LEDGER = "forum-ledger"
+
+
+def _make_executor(args):
+    """Pick an executor from flags (the first present wins): --chat-url, --api, --cmd, else None.
+
+    Forum is model-agnostic: --cmd runs any command (a local model CLI needs no
+    account), --chat-url talks to any OpenAI-compatible server (local or cloud),
+    and --api is one specific provider (Anthropic).
+    """
+    chat_url = getattr(args, "chat_url", None)
+    if chat_url:
+        from forum.chat_executor import ChatExecutor
+
+        return ChatExecutor(
+            getattr(args, "model", None) or "default",
+            base_url=chat_url,
+            api_key_env=getattr(args, "api_key_env", None),
+        )
+    if getattr(args, "api", False):
+        from forum.api_executor import ApiExecutor
+
+        return ApiExecutor(args.model) if getattr(args, "model", None) else ApiExecutor()
+    cmd = getattr(args, "cmd", None)
+    if cmd:
+        from forum.executor import SubprocessExecutor
+
+        return SubprocessExecutor(shlex.split(cmd))
+    return None
+
+
+def _open_ledger(directory):
+    from forum.ledger import Ledger
+    from forum.storage import FileStorage
+
+    return Ledger(FileStorage(directory))
+
+
+def _cmd_route(args) -> int:
+    from forum.roster import load_default
+    from forum.routing import LexicalRouter
+
+    result = LexicalRouter().score(args.text, load_default())
+    print(json.dumps({
+        "decided": result.decided,
+        "confidence": result.confidence,
+        "needs_escalation": result.needs_escalation,
+        "candidates": [{"agent": c.agent, "score": c.score} for c in result.candidates],
+    }, indent=2))
+    return 0
+
+
+def _cmd_submit(args) -> int:
+    executor = _make_executor(args)
+    if executor is None:
+        print(
+            "submit needs a model executor. Forum is model-agnostic: pass --cmd "
+            '"<model cli>" (any command, local models need no account), --chat-url '
+            "<openai-compatible url> (e.g. a local Ollama server), or --api (Anthropic).",
+            file=sys.stderr,
+        )
+        return 2
+    from forum.budget import RunBudget
+    from forum.daemon import build_orchestrator
+
+    budget = None
+    if args.max_model_calls is not None or args.max_seconds is not None:
+        budget = RunBudget(max_model_calls=args.max_model_calls, max_seconds=args.max_seconds)
+    orch = build_orchestrator(args.ledger, executor=executor)
+    try:
+        answer = asyncio.run(orch.submit(args.request, budget=budget))
+    except ValueError as exc:
+        print(f"submit failed: {exc}", file=sys.stderr)
+        return 1
+    print(answer)
+    print(f"checkpoint: {orch.ledger.checkpoint()}", file=sys.stderr)
+    return 0
+
+
+def _cmd_serve(args) -> int:
+    from forum.daemon import serve
+
+    asyncio.run(serve(
+        ledger_dir=args.ledger, host=args.host, port=args.port, executor=_make_executor(args)
+    ))
+    return 0
+
+
+def _cmd_mcp(args) -> int:
+    from forum.daemon import build_orchestrator
+    from forum.mcp_surface import serve_stdio
+
+    orch = build_orchestrator(args.ledger, executor=_make_executor(args))
+    asyncio.run(serve_stdio(orch))
+    return 0
+
+
+def _cmd_ledger_verify(args) -> int:
+    led = _open_ledger(args.ledger)
+    print(json.dumps({"chain": led.verify(), "deep": led.verify(deep=True)}, indent=2))
+    return 0
+
+
+def _cmd_ledger_show(args) -> int:
+    led = _open_ledger(args.ledger)
+    entries = led.replay()
+    if args.limit:
+        entries = entries[-args.limit:]
+    for e in entries:
+        print(f"{e.seq:>5}  {e.actor:<12} {e.kind:<10} parent={e.causal_parent}")
+    return 0
+
+
+def _cmd_ledger_replay(args) -> int:
+    led = _open_ledger(args.ledger)
+    entries = led.replay(until=args.seq)
+    print(json.dumps([dataclasses.asdict(e) for e in entries], indent=2))
+    return 0
+
+
+def _cmd_ledger_get(args) -> int:
+    led = _open_ledger(args.ledger)
+    try:
+        entry = led.get(args.seq)
+    except KeyError:
+        print(f"no ledger entry at seq {args.seq}", file=sys.stderr)
+        return 1
+    print(json.dumps(dataclasses.asdict(entry), indent=2))
+    return 0
+
+
+def _cmd_ledger_summary(args) -> int:
+    from forum.report import summarize
+
+    s = summarize(_open_ledger(args.ledger))
+    if args.json:
+        print(json.dumps(s, indent=2))
+        return 0
+    print(f"entries: {s['entries']}")
+    print(f"requests: {s['requests']} | plans: {s['plans']} | tasks: {s['tasks']}")
+    print(f"task results: {s['task_results']} (failed {s['failed_results']}) | verdicts: pass {s['verdicts_pass']} / fail {s['verdicts_fail']}")
+    print(f"intent checks: {s['intent_checks']} (flagged {s['intent_flagged']})")
+    print(f"escalations: {s['escalations']} | budget stops: {s['budget_stops']} | contexts: {s['contexts']} | answers: {s['answers']}")
+    print(f"model calls: {s['model_calls']}")
+    print(f"checkpoint: {s['checkpoint'][:16]}... | verified: {s['verified']}")
+    return 0
+
+
+def _cmd_bench(args) -> int:
+    from forum.report import compare, summarize
+
+    a = summarize(_open_ledger(args.a))
+    b = summarize(_open_ledger(args.b))
+    delta = compare(a, b)
+    if args.json:
+        print(json.dumps({"a": a, "b": b, "delta": delta}, indent=2))
+        return 0
+    print(f"{'metric':<16}{'A':>8}{'B':>8}{'delta':>8}")
+    for key in delta:
+        print(f"{key:<16}{a.get(key, 0):>8}{b.get(key, 0):>8}{delta[key]:>+8}")
+    return 0
+
+
+def _add_ledger(sp) -> None:
+    sp.add_argument("--ledger", default=DEFAULT_LEDGER, help="ledger directory (default: forum-ledger)")
+
+
+def _add_executor(sp) -> None:
+    sp.add_argument("--cmd", default=None, help='run any model command per task, e.g. --cmd "ollama run llama3" (no account needed)')
+    sp.add_argument("--chat-url", default=None, help="an OpenAI-compatible chat-completions URL, e.g. a local Ollama or LM Studio server (no account needed)")
+    sp.add_argument("--api", action="store_true", help="use the Anthropic API executor (reads ANTHROPIC_API_KEY)")
+    sp.add_argument("--model", default=None, help="model id for --chat-url or --api")
+    sp.add_argument("--api-key-env", default=None, help="env var holding a Bearer key for --chat-url (optional; local servers need none)")
+
+
+def _print_help_rc(parser: argparse.ArgumentParser) -> int:
+    parser.print_help()
+    return 1
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="forum", description="Forum: accountable multi-agent orchestration.")
+    parser.add_argument("--version", action="version", version=f"forum {__version__}")
+    sub = parser.add_subparsers(dest="command")
+
+    route = sub.add_parser("route", help="route a request to a capability lane (no model needed)")
+    route.add_argument("text")
+    route.set_defaults(func=_cmd_route)
+
+    submit = sub.add_parser("submit", help="plan and answer a request, witnessed")
+    submit.add_argument("request")
+    submit.add_argument("--max-model-calls", type=int, default=None, help="bound the run to N model calls (witnessed budget)")
+    submit.add_argument("--max-seconds", type=float, default=None, help="bound the run to S seconds (best-effort)")
+    _add_ledger(submit)
+    _add_executor(submit)
+    submit.set_defaults(func=_cmd_submit)
+
+    serve = sub.add_parser("serve", help="run the HTTP daemon")
+    serve.add_argument("--host", default="127.0.0.1")
+    serve.add_argument("--port", type=int, default=8080)
+    _add_ledger(serve)
+    _add_executor(serve)
+    serve.set_defaults(func=_cmd_serve)
+
+    mcp = sub.add_parser("mcp", help="run the MCP (stdio) server")
+    _add_ledger(mcp)
+    _add_executor(mcp)
+    mcp.set_defaults(func=_cmd_mcp)
+
+    ledger = sub.add_parser("ledger", help="inspect the ledger")
+    lsub = ledger.add_subparsers(dest="ledger_command")
+    verify = lsub.add_parser("verify", help="verify the chain and payloads")
+    _add_ledger(verify)
+    verify.set_defaults(func=_cmd_ledger_verify)
+    show = lsub.add_parser("show", help="list entries (seq, actor, kind)")
+    _add_ledger(show)
+    show.add_argument("--limit", type=int, default=0, help="show only the last N entries")
+    show.set_defaults(func=_cmd_ledger_show)
+    replay = lsub.add_parser("replay", help="dump entries up to a seq")
+    _add_ledger(replay)
+    replay.add_argument("seq", type=int)
+    replay.set_defaults(func=_cmd_ledger_replay)
+    get = lsub.add_parser("get", help="dump one entry by seq")
+    _add_ledger(get)
+    get.add_argument("seq", type=int)
+    get.set_defaults(func=_cmd_ledger_get)
+    summary = lsub.add_parser("summary", help="aggregate the ledger into a run summary")
+    _add_ledger(summary)
+    summary.add_argument("--json", action="store_true", help="emit the summary as JSON")
+    summary.set_defaults(func=_cmd_ledger_summary)
+    ledger.set_defaults(func=lambda a: _print_help_rc(ledger))
+
+    bench = sub.add_parser("bench", help="compare two ledgers (A/B) by their summaries")
+    bench.add_argument("a", help="ledger directory A")
+    bench.add_argument("b", help="ledger directory B")
+    bench.add_argument("--json", action="store_true", help="emit both summaries and the delta as JSON")
+    bench.set_defaults(func=_cmd_bench)
+
+    return parser
+
+
+def main(argv=None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    func = getattr(args, "func", None)
+    if func is None:
+        parser.print_help()
+        return 1
+    return func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

forum/context.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from typing import Protocol
+
+
+class ContextProvider(Protocol):
+    """Supplies organized context for a request, before Forum plans or routes.
+
+    This is the seam to the "brain": a peer like the index flagship can implement
+    it (rendering its code-and-knowledge map to text), and Forum will witness the
+    exact context that shaped a plan. Keep it pure and offline; return "" when
+    there is nothing relevant. Forum never imports the provider, only this shape.
+    """
+
+    def context(self, request: str) -> str: ...
+
+
+class NullContextProvider:
+    """The zero-dependency default: no external context. Forum stands alone."""
+
+    def context(self, request: str) -> str:
+        return ""

forum/control.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from forum.executor import Assignment, Executor
+from forum.llm import ask_json
+from forum.plan import Plan, Task
+from forum.roster import Roster
+
+_COORDINATOR_PROMPT = """You are a planner. Break the request into a minimal task DAG.
+Available agents: <<AGENTS>>.
+Return ONLY JSON of the form:
+{"tasks": [{"id": "T1", "agent": "<one of the agents>", "instruction": "...", "depends_on": []}]}
+Use depends_on to order tasks. Keep the plan small.
+
+Request: <<REQUEST>>"""
+
+
+class Coordinator:
+    """Turn a plain request into a validated task plan, using a model."""
+
+    async def plan(self, request: str, roster: Roster, executor: Executor, context: str = "") -> Plan:
+        names = [a.name for a in roster.agents]
+        prompt = _COORDINATOR_PROMPT.replace("<<AGENTS>>", ", ".join(names)).replace("<<REQUEST>>", request)
+        if context:
+            prompt = f"Context (organized knowledge to use):\n{context}\n\n" + prompt
+        data = await ask_json(executor, "coordinator", prompt)
+        if "tasks" not in data:
+            raise ValueError(f"coordinator response missing 'tasks'; got keys {list(data)}")
+        tasks = tuple(
+            Task(
+                str(t["id"]),
+                str(t["agent"]),
+                str(t["instruction"]),
+                tuple(str(d) for d in t.get("depends_on", [])),
+            )
+            for t in data["tasks"]
+        )
+        for t in tasks:
+            if t.agent not in names:
+                raise ValueError(f"coordinator chose unknown agent: {t.agent!r}")
+        plan = Plan(tasks)
+        plan.schedule()  # raises on a cycle or an unknown dependency
+        return plan
+
+
+@dataclass(frozen=True, slots=True)
+class Classification:
+    agent: str
+    confidence: float
+    reason: str
+
+
+_CLASSIFIER_PROMPT = """Pick the single best agent for the task.
+Agents: <<AGENTS>>.
+Return ONLY JSON of the form:
+{"agent": "<one of the agents>", "confidence": 0.0, "reason": "..."}
+
+Task: <<TASK>>"""
+
+
+class Classifier:
+    """Pick an agent for a single task when keyword routing cannot decide."""
+
+    async def classify(self, task: str, roster: Roster, executor: Executor) -> Classification:
+        names = [a.name for a in roster.agents]
+        prompt = _CLASSIFIER_PROMPT.replace("<<AGENTS>>", ", ".join(names)).replace("<<TASK>>", task)
+        data = await ask_json(executor, "classifier", prompt)
+        if "agent" not in data:
+            raise ValueError(f"classifier response missing 'agent'; got keys {list(data)}")
+        agent = str(data["agent"])
+        if agent not in names:
+            raise ValueError(f"classifier chose unknown agent: {agent!r}")
+        return Classification(agent, float(data.get("confidence", 0.0)), str(data.get("reason", "")))
+
+
+@dataclass(frozen=True, slots=True)
+class Verdict:
+    ok: bool
+    score: float
+    reason: str
+
+
+_VALIDATOR_PROMPT = """Judge whether the output satisfies the instruction.
+Return ONLY JSON of the form:
+{"ok": true, "score": 0.0, "reason": "..."}
+
+Instruction: <<INSTRUCTION>>
+Output: <<OUTPUT>>"""
+
+
+class Validator:
+    """Judge an output against its instruction, using a model."""
+
+    async def validate(self, instruction: str, output: str, executor: Executor) -> Verdict:
+        prompt = _VALIDATOR_PROMPT.replace("<<INSTRUCTION>>", instruction).replace("<<OUTPUT>>", output)
+        data = await ask_json(executor, "validator", prompt)
+        if "ok" not in data:
+            raise ValueError(f"validator response missing 'ok'; got keys {list(data)}")
+        raw_ok = data["ok"]
+        ok = raw_ok if isinstance(raw_ok, bool) else str(raw_ok).strip().lower() not in ("false", "0", "no", "")
+        return Verdict(ok, float(data.get("score", 0.0)), str(data.get("reason", "")))
+
+
+_SYNTHESIZER_PROMPT = """Combine the task results into one clear answer to the request.
+
+Request: <<REQUEST>>
+Results:
+<<RESULTS>>
+
+Write the final answer."""
+
+
+class Synthesizer:
+    """Combine task results into one answer, using a model."""
+
+    async def synthesize(self, request: str, results: dict, executor: Executor) -> str:
+        lines = "\n".join(f"- {tid}: {r.output}" for tid, r in results.items())
+        prompt = _SYNTHESIZER_PROMPT.replace("<<REQUEST>>", request).replace("<<RESULTS>>", lines)
+        out = await executor.run(Assignment("control:synthesizer", "synthesizer", prompt))
+        return out.output.strip()