loom-threads 0.1.0__py3-none-any.whl

loom/__init__.py

@@ -0,0 +1,20 @@
+"""Loom: thread-and-episode orchestration on its own any-llm engine."""
+
+from loom.agent import Tool, ToolResult, run_loop
+from loom.coding import create_coding_tools
+from loom.dispatch import DEFAULT_MAX_TURNS, DEFAULT_TIMEOUT_SECS, run_dispatch
+from loom.episodes import Episode, EpisodeStore
+from loom.threads import create_thread_tools
+
+__all__ = [
+    "DEFAULT_MAX_TURNS",
+    "DEFAULT_TIMEOUT_SECS",
+    "Episode",
+    "EpisodeStore",
+    "Tool",
+    "ToolResult",
+    "create_coding_tools",
+    "create_thread_tools",
+    "run_dispatch",
+    "run_loop",
+]

loom/agent.py

@@ -0,0 +1,206 @@
+"""Agent loop on any-llm: sequential tool calls, OpenAI-dict messages,
+tiny event set for the CLI.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from collections.abc import AsyncIterator, Mapping, Sequence
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class ToolResult:
+    text: str
+    is_error: bool = False
+    details: dict[str, Any] | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class Tool:
+    name: str
+    description: str
+    parameters: dict[str, Any]
+    execute_fn: Any  # async (args: dict) -> ToolResult
+
+    async def execute(self, args: Mapping[str, Any]) -> ToolResult:
+        try:
+            return await self.execute_fn(dict(args))
+        except Exception as exc:  # tools are an isolation boundary
+            return ToolResult(text=f"Error: {exc}", is_error=True)
+
+
+# Events: just enough for cli.py / dispatch.py to print + collect episodes.
+@dataclass(frozen=True, slots=True)
+class TextDelta:
+    delta: str
+
+
+@dataclass(frozen=True, slots=True)
+class ToolStart:
+    tool_name: str
+    args: dict[str, Any]
+
+
+@dataclass(frozen=True, slots=True)
+class ToolEnd:
+    tool_name: str
+    result: ToolResult
+    is_error: bool
+
+
+@dataclass(frozen=True, slots=True)
+class AssistantEnd:
+    text: str
+
+
+@dataclass(frozen=True, slots=True)
+class AgentError:
+    message: str
+
+
+Event = TextDelta | ToolStart | ToolEnd | AssistantEnd | AgentError
+
+
+def to_openai_tools(tools: Sequence[Tool]) -> list[dict[str, Any]]:
+    return [
+        {
+            "type": "function",
+            "function": {
+                "name": t.name,
+                "description": t.description,
+                "parameters": t.parameters,
+            },
+        }
+        for t in tools
+    ]
+
+
+def split_model(model: str, default_provider: str | None = None) -> tuple[str, str]:
+    """Accept 'provider:model' or plain model + separate provider."""
+    if ":" in model:
+        provider, _, model_id = model.partition(":")
+        return provider or (default_provider or "openai"), model_id
+    return (default_provider or "openai"), model
+
+
+async def run_loop(
+    *,
+    provider: str | None,
+    model: str,
+    system: str,
+    messages: list[dict[str, Any]],
+    tools: Sequence[Tool],
+    max_turns: int = 32,
+    api_key: str | None = None,
+    api_base: str | None = None,
+) -> AsyncIterator[Event]:
+    """One agent run: call model, execute tool calls sequentially, repeat.
+
+    `messages` uses OpenAI dict format. Mutated in place (assistant + tool
+    turns appended) so callers can inspect history; the final assistant text
+    arrives as AssistantEnd per turn, AgentError on failure.
+    """
+    from any_llm import AnyLLM  # lazy: keeps import cheap for tests
+
+    provider_name, model_id = split_model(model, provider)
+    api_key = api_key or os.getenv("LOOM_LLM_PROVIDER_API_KEY")
+    api_base = api_base or os.getenv("LOOM_LLM_PROVIDER_BASE_URL")
+    llm = AnyLLM.create(provider_name, api_key=api_key, api_base=api_base)
+    by_name = {t.name: t for t in tools}
+    wire_tools = to_openai_tools(tools) if tools else None
+
+    history: list[Any] = [{"role": "system", "content": system}, *messages]
+
+    for _ in range(max(1, max_turns)):
+        try:
+            result = await llm.acompletion(
+                model=model_id,
+                messages=history,
+                tools=wire_tools,
+            )
+        except Exception as exc:
+            yield AgentError(message=str(exc))
+            return
+
+        msg = result.choices[0].message
+        text: str = msg.content or ""
+        raw_calls = getattr(msg, "tool_calls", None) or []
+
+        if text:
+            yield TextDelta(delta=text)
+
+        calls: list[tuple[str, str, dict[str, Any]]] = []
+        for call in raw_calls:
+            fn = getattr(call, "function", None)
+            if fn is None:
+                continue
+            try:
+                args = json.loads(fn.arguments or "{}")
+            except (json.JSONDecodeError, TypeError):
+                args = {}
+            if not isinstance(args, dict):
+                args = {}
+            calls.append((call.id, fn.name, args))
+
+        # Replay assistant turn so the next request sees tool calls.
+        history.append(
+            {
+                "role": "assistant",
+                "content": text,
+                **(
+                    {
+                        "tool_calls": [
+                            {
+                                "id": cid,
+                                "type": "function",
+                                "function": {"name": name, "arguments": json.dumps(args)},
+                            }
+                            for cid, name, args in calls
+                        ]
+                    }
+                    if calls
+                    else {}
+                ),
+            }
+        )
+        yield AssistantEnd(text=text)
+
+        if not calls:
+            return
+
+        for cid, name, args in calls:
+            tool = by_name.get(name)
+            yield ToolStart(tool_name=name, args=args)
+            if tool is None:
+                result_ = ToolResult(text=f"Error: tool {name} not found", is_error=True)
+            else:
+                result_ = await tool.execute(args)
+            history.append(
+                {
+                    "role": "tool",
+                    "tool_call_id": cid,
+                    "name": name,
+                    "content": result_.text,
+                }
+            )
+            yield ToolEnd(tool_name=name, result=result_, is_error=result_.is_error)
+
+    yield AgentError(message=f"Agent stopped after max_turns={max_turns}")
+
+
+__all__ = [
+    "AgentError",
+    "AssistantEnd",
+    "Event",
+    "TextDelta",
+    "Tool",
+    "ToolEnd",
+    "ToolResult",
+    "ToolStart",
+    "run_loop",
+    "split_model",
+    "to_openai_tools",
+]

loom/cli.py

@@ -0,0 +1,238 @@
+"""Print-mode orchestrator: `loom "refactor the parser"`.
+
+The orchestrator only holds thread tools; workers get coding tools.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import sys
+from collections.abc import Mapping
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path
+from typing import Any
+
+from loom.agent import AgentError, AssistantEnd, TextDelta, Tool, ToolEnd, ToolStart, run_loop
+from loom.engine import build_engine, credential_path, load_credentials, save_credentials
+from loom.episodes import EpisodeStore
+from loom.prompts import orchestrator_prompt
+from loom.sessions import SessionStore
+from loom.threads import create_thread_tools
+
+
+def _get_version() -> str:
+    for dist in ("loom-threads", "loom"):
+        try:
+            return f"loom {version(dist)}"
+        except PackageNotFoundError:
+            continue
+    return "loom unknown"
+
+
+def _parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        prog="loom", description="Thread-and-episode orchestration (any-llm engine)."
+    )
+    parser.add_argument("prompt", help="What to work on.")
+    parser.add_argument("--provider", default=None, help="any-llm provider name.")
+    parser.add_argument("--model", default=None, help="Model id ('provider:model' or plain).")
+    parser.add_argument("--cwd", default=".", help="Working directory for workers.")
+    parser.add_argument(
+        "--store",
+        default=None,
+        help="Episode directory (default: <cwd>/.loom/episodes).",
+    )
+    parser.add_argument("--max-turns", type=int, default=32, help="Orchestrator turns.")
+    parser.add_argument(
+        "--resume",
+        action="append",
+        default=[],
+        metavar="SESSION_ID",
+        help="Resume a session (one ID appends in place; several start a new run).",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=_get_version(),
+        help="Show the loom version and exit.",
+    )
+    return parser.parse_args(argv)
+
+
+def _preview(text: str, limit: int = 220) -> str:
+    flat = " ".join(text.split())
+    return flat if len(flat) <= limit else flat[: limit - 1] + "…"
+
+
+EPISODE_PREVIEW = 300
+
+
+def _episode_lines(result: Any) -> list[str]:
+    details = result.details
+    episodes = details.get("episodes") if isinstance(details, dict) else None
+    if not isinstance(episodes, list):
+        return [f"<< {_preview(result.text, EPISODE_PREVIEW)}"]
+    lines = []
+    for episode in episodes:
+        if not isinstance(episode, Mapping):
+            continue
+        name = str(episode.get("name", "?"))
+        text = str(episode.get("text", ""))
+        marker = "!! " if text.startswith("Error:") else ""
+        lines.append(f"<< {marker}{name} ({len(text):,} chars): {_preview(text, EPISODE_PREVIEW)}")
+    return lines
+
+
+def _dispatch_label(arguments: Mapping[str, Any]) -> str:
+    items = arguments.get("items")
+    if isinstance(items, list):
+        names = [
+            str(item["name"]) for item in items if isinstance(item, Mapping) and item.get("name")
+        ]
+        return "batch: " + ", ".join(names)
+    return f"thread {_preview(str(arguments.get('name', '')), 40)}"
+
+
+def _open_session(sessions: SessionStore, resume: list[str], prompt: str) -> str:
+    """One existing --resume id continues in place; otherwise start a new run."""
+    if len(resume) == 1 and sessions.path_of(resume[0]).exists():
+        sessions.log_input(resume[0], prompt)
+        return resume[0]
+    return sessions.start(prompt)
+
+
+def _episode_entries(result: Any) -> list[tuple[str, str, str | None]] | None:
+    """Per-episode (name, text, id) triples in dispatch order, or None."""
+    details = result.details
+    episodes = details.get("episodes") if isinstance(details, dict) else None
+    if not isinstance(episodes, list):
+        return None
+    entries = []
+    for episode in episodes:
+        if not isinstance(episode, Mapping):
+            continue
+        raw_id = episode.get("id")
+        entries.append(
+            (
+                str(episode.get("name", "?")),
+                str(episode.get("text", "")),
+                raw_id if isinstance(raw_id, str) else None,
+            )
+        )
+    return entries
+
+
+async def _run(args: argparse.Namespace) -> None:
+    cwd = Path(args.cwd).resolve()
+    store = EpisodeStore(args.store or cwd / ".loom" / "episodes")
+    provider, model, worker_tools = build_engine(
+        provider_name=args.provider, model=args.model, cwd=cwd
+    )
+    sessions = SessionStore(cwd / ".loom" / "sessions")
+
+    messages: list[dict[str, Any]] = []
+    for prior in args.resume:
+        rendered = sessions.render(prior, store)
+        if rendered is None:
+            print(f"warning: session '{prior}' not found", file=sys.stderr)
+        else:
+            messages.append({"role": "user", "content": rendered})
+    messages.append({"role": "user", "content": args.prompt})
+    session_id = _open_session(sessions, args.resume, args.prompt)
+
+    def on_worker_event(name: str, event: object) -> None:
+        if isinstance(event, ToolStart):
+            print(f"    [{name}] {event.tool_name} {_preview(str(event.args))}")
+        elif isinstance(event, ToolEnd):
+            status = "error" if event.is_error else "ok"
+            print(f"    [{name}] -> {status}: {_preview(event.result.text)}")
+
+    tools: list[Tool] = create_thread_tools(
+        provider=provider,
+        model=model,
+        worker_tools=worker_tools,
+        store=store,
+        working_directory=cwd,
+        on_event=on_worker_event,
+        session=session_id,
+    )
+
+    pending_label = ""
+    async for event in run_loop(
+        provider=provider,
+        model=model,
+        system=orchestrator_prompt(str(cwd)),
+        messages=messages,
+        tools=tools,
+        max_turns=args.max_turns,
+    ):
+        if isinstance(event, ToolStart):
+            pending_label = _dispatch_label(event.args)
+            print(f"\n>> {pending_label}")
+        elif isinstance(event, ToolEnd):
+            entries = _episode_entries(event.result)
+            if entries is None:
+                sessions.log_output(session_id, event.result.text, label=pending_label)
+            else:
+                for name, text, episode_id in entries:
+                    if episode_id:
+                        sessions.log_episode_ref(session_id, name, episode_id)
+                    else:
+                        sessions.log_output(session_id, text, label=name)
+            for line in _episode_lines(event.result):
+                print(line)
+            print()
+        elif isinstance(event, AssistantEnd):
+            if event.text.strip():
+                sessions.log_output(session_id, event.text.strip())
+        elif isinstance(event, TextDelta):
+            print(event.delta, end="", flush=True)
+        elif isinstance(event, AgentError):
+            print(f"error: {event.message}", file=sys.stderr)
+
+    print(f"\nsession: {sessions.path_of(session_id)}")
+
+
+def _redact(value: str) -> str:
+    return f"****{value[-4:]}" if len(value) > 4 else "****" if value else "(not set)"
+
+
+def _run_setup() -> None:
+    import getpass
+
+    current = load_credentials()
+    print(f"loom setup (saves to {credential_path()}, mode 600)\n")
+
+    def ask(label: str, key: str, *, secret: bool = False) -> str:
+        existing = current.get(key, "")
+        hint = _redact(existing) if secret else existing or "(not set)"
+        prompt = f"{label} [{hint}]: "
+        value = (getpass.getpass(prompt) if secret else input(prompt)).strip()
+        return value or existing
+
+    try:
+        data = {
+            "base_url": ask("Provider base URL", "base_url"),
+            "api_key": ask("Provider API key", "api_key", secret=True),
+            "model": ask("Model (provider:model)", "model"),
+            "provider": ask("Provider override (optional)", "provider"),
+        }
+    except (EOFError, KeyboardInterrupt):
+        print("\nsetup cancelled.")
+        return
+    path = save_credentials({k: v for k, v in data.items() if v})
+    print(f"saved to {path}")
+
+
+def main(argv: list[str] | None = None) -> None:
+    argv = sys.argv[1:] if argv is None else argv
+    if argv and argv[0] == "setup":
+        _run_setup()
+        return
+    args = _parse_args(argv)
+    asyncio.run(_run(args))
+
+
+if __name__ == "__main__":
+    main()

loom/coding.py

@@ -0,0 +1,216 @@
+"""Worker coding tools: `read`/`write`/`edit`/`bash`.
+Text-only, cwd-jailed, truncated.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+from typing import Any
+
+from loom.agent import Tool, ToolResult
+
+MAX_BYTES = 50 * 1024
+MAX_LINES = 2_000
+
+_locks: dict[Path, asyncio.Lock] = {}
+
+
+def _lock(path: Path) -> asyncio.Lock:
+    lock = _locks.get(path)
+    if lock is None:
+        lock = asyncio.Lock()
+        _locks[path] = lock
+    return lock
+
+
+def _resolve(cwd: Path, raw: Any) -> Path:
+    if not isinstance(raw, str) or not raw:
+        raise ValueError("path must be a non-empty string")
+    p = Path(raw)
+    resolved = (cwd / p).resolve() if not p.is_absolute() else p.resolve()
+    # ponytail: cwd jail is security, never simplify away
+    if resolved != cwd.resolve() and cwd.resolve() not in resolved.parents:
+        raise ValueError(f"path escapes working directory: {raw}")
+    return resolved
+
+
+def _truncate(text: str) -> str:
+    lines = text.splitlines()
+    if len(lines) > MAX_LINES:
+        lines = lines[-MAX_LINES:]
+        return (
+            "\n".join(lines)
+            + f"\n\n[{len(text.splitlines())} lines total, showing last {MAX_LINES}]"
+        )
+    encoded = text.encode("utf-8", errors="replace")
+    if len(encoded) > MAX_BYTES:
+        cut = text.encode("utf-8", errors="replace")[-MAX_BYTES:].decode("utf-8", errors="replace")
+        return cut + f"\n\n[output truncated to last {MAX_BYTES // 1024}KB]"
+    return text
+
+
+def create_coding_tools(cwd: str | Path | None = None) -> list[Tool]:
+    root = Path(cwd).resolve() if cwd else Path.cwd().resolve()
+
+    async def read_fn(args: dict[str, Any]) -> ToolResult:
+        try:
+            path = _resolve(root, args.get("path"))
+        except ValueError as exc:
+            return ToolResult(text=f"Error: {exc}", is_error=True)
+        if not path.exists():
+            return ToolResult(text=f"Error: file not found: {path}", is_error=True)
+        if path.is_dir():
+            return ToolResult(text=f"Error: path is a directory: {path}", is_error=True)
+        try:
+            text = path.read_text(encoding="utf-8")
+        except UnicodeDecodeError:
+            return ToolResult(text=f"Error: not a UTF-8 text file: {path}", is_error=True)
+        lines = text.splitlines()
+        offset = args.get("offset")
+        limit = args.get("limit")
+        start = max(int(offset) - 1, 0) if isinstance(offset, int) and offset > 0 else 0
+        end = start + int(limit) if isinstance(limit, int) and limit > 0 else None
+        return ToolResult(text=_truncate("\n".join(lines[start:end])) or "(empty file)")
+
+    async def write_fn(args: dict[str, Any]) -> ToolResult:
+        content = args.get("content")
+        if not isinstance(content, str):
+            return ToolResult(text="Error: content must be a string", is_error=True)
+        try:
+            path = _resolve(root, args.get("path"))
+        except ValueError as exc:
+            return ToolResult(text=f"Error: {exc}", is_error=True)
+        async with _lock(path):
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_text(content, encoding="utf-8")
+        return ToolResult(text=f"Successfully wrote to {path}.")
+
+    async def edit_fn(args: dict[str, Any]) -> ToolResult:
+        edits = args.get("edits")
+        if not isinstance(edits, list) or not edits:
+            return ToolResult(text="Error: edits must be a non-empty list", is_error=True)
+        try:
+            path = _resolve(root, args.get("path"))
+        except ValueError as exc:
+            return ToolResult(text=f"Error: {exc}", is_error=True)
+        if not path.exists() or path.is_dir():
+            return ToolResult(text=f"Error: file not found: {path}", is_error=True)
+        async with _lock(path):
+            content = path.read_text(encoding="utf-8")
+            for i, edit in enumerate(edits):
+                e: Any = edit
+                if not isinstance(e, dict):
+                    return ToolResult(text=f"Error: edit {i} must be an object", is_error=True)
+                old, new = e.get("oldText"), e.get("newText")
+                if not isinstance(old, str) or not old or not isinstance(new, str):
+                    return ToolResult(
+                        text=f"Error: edit {i} needs non-empty oldText + newText", is_error=True
+                    )
+                n = content.count(old)
+                if n != 1:
+                    return ToolResult(
+                        text=f"Error: edit {i} matches {n}x (need 1)",
+                        is_error=True,
+                    )
+                content = content.replace(old, new, 1)
+            path.write_text(content, encoding="utf-8")
+        return ToolResult(text=f"Successfully edited {path} ({len(edits)} edits).")
+
+    async def bash_fn(args: dict[str, Any]) -> ToolResult:
+        command = args.get("command")
+        if not isinstance(command, str) or not command.strip():
+            return ToolResult(text="Error: command must be a non-empty string", is_error=True)
+        timeout = args.get("timeout")
+        if timeout is not None and (not isinstance(timeout, (int, float)) or timeout <= 0):
+            return ToolResult(text="Error: timeout must be > 0", is_error=True)
+        try:
+            proc = await asyncio.create_subprocess_shell(
+                command,
+                cwd=root,
+                stdin=asyncio.subprocess.DEVNULL,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.STDOUT,
+            )
+            try:
+                out, _ = await asyncio.wait_for(
+                    proc.communicate(), timeout=float(timeout) if timeout else 120.0
+                )
+            except TimeoutError:
+                proc.kill()
+                return ToolResult(text="Error: command timed out", is_error=True)
+        except Exception as exc:
+            return ToolResult(text=f"Error: {exc}", is_error=True)
+        text_out = _truncate(out.decode(errors="replace")) or "(no output)"
+        if proc.returncode != 0:
+            return ToolResult(text=f"{text_out}\n\n[exit {proc.returncode}]", is_error=True)
+        return ToolResult(text=text_out)
+
+    return [
+        Tool(
+            name="read",
+            description="Read a UTF-8 text file. Use offset/limit for large files.",
+            parameters={
+                "type": "object",
+                "properties": {
+                    "path": {"type": "string"},
+                    "offset": {"type": "integer"},
+                    "limit": {"type": "integer"},
+                },
+                "required": ["path"],
+            },
+            execute_fn=read_fn,
+        ),
+        Tool(
+            name="write",
+            description="Write content to a file. Creates parents, overwrites existing.",
+            parameters={
+                "type": "object",
+                "properties": {
+                    "path": {"type": "string"},
+                    "content": {"type": "string"},
+                },
+                "required": ["path", "content"],
+            },
+            execute_fn=write_fn,
+        ),
+        Tool(
+            name="edit",
+            description="Exact oldText->newText replacement. Each oldText must match exactly once.",
+            parameters={
+                "type": "object",
+                "properties": {
+                    "path": {"type": "string"},
+                    "edits": {
+                        "type": "array",
+                        "items": {
+                            "type": "object",
+                            "properties": {
+                                "oldText": {"type": "string"},
+                                "newText": {"type": "string"},
+                            },
+                            "required": ["oldText", "newText"],
+                        },
+                    },
+                },
+                "required": ["path", "edits"],
+            },
+            execute_fn=edit_fn,
+        ),
+        Tool(
+            name="bash",
+            description="Run a shell command in the working directory.",
+            parameters={
+                "type": "object",
+                "properties": {
+                    "command": {"type": "string"},
+                    "timeout": {"type": "number"},
+                },
+                "required": ["command"],
+            },
+            execute_fn=bash_fn,
+        ),
+    ]
+
+
+__all__ = ["create_coding_tools"]