loom-threads 0.1.0__tar.gz

loom_threads-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+__pycache__/
+*.egg-info/
+.loom/
+.coverage
+.env

loom_threads-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

loom_threads-0.1.0/AGENTS.md

@@ -0,0 +1,11 @@
+## Wiki
+
+This repository has documentation located in the /wiki directory.
+
+Start here:
+
+- [Wiki quickstart](wiki/quickstart.md)
+
+Wiki includes repository overview, architecture notes, workflows, domain concepts, operations, integrations, testing guidance, and source maps.
+
+When working in this repository, read the Wiki quickstart first, then follow its links to the relevant architecture, workflow, domain, operation, and testing notes.

loom_threads-0.1.0/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2026 Dheerapat Tookkane
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

loom_threads-0.1.0/PKG-INFO

@@ -0,0 +1,23 @@
+Metadata-Version: 2.5
+Name: loom-threads
+Version: 0.1.0
+Summary: Thread-and-episode orchestration on its own any-llm engine.
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: any-llm-sdk
+Requires-Dist: rich>=13.0
+Description-Content-Type: text/markdown
+
+# Loom
+
+Thread-and-episode orchestration on its own minimal engine (any-llm providers).
+
+Orchestrator dispatches **threads**; each thread runs a bounded action in a worker context and returns an **episode**. Episodes are the only thing that crosses between threads.
+
+```sh
+uv sync
+uv run loom "add rate limiting to the API"
+uv run loom setup  # provider config
+```
+
+Docs: [wiki/quickstart.md](wiki/quickstart.md)

loom_threads-0.1.0/README.md

@@ -0,0 +1,13 @@
+# Loom
+
+Thread-and-episode orchestration on its own minimal engine (any-llm providers).
+
+Orchestrator dispatches **threads**; each thread runs a bounded action in a worker context and returns an **episode**. Episodes are the only thing that crosses between threads.
+
+```sh
+uv sync
+uv run loom "add rate limiting to the API"
+uv run loom setup  # provider config
+```
+
+Docs: [wiki/quickstart.md](wiki/quickstart.md)

loom_threads-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[project]
+name = "loom-threads"
+version = "0.1.0"
+description = "Thread-and-episode orchestration on its own any-llm engine."
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = ["any-llm-sdk", "rich>=13.0"]
+
+[project.scripts]
+loom = "loom.cli:main"
+
+[build-system]
+requires = ["hatchling>=1.26"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/loom"]
+
+[dependency-groups]
+dev = [
+    "ty",
+    "pytest>=8.0",
+    "ruff>=0.5",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.ruff.lint.per-file-ignores]
+# Prompt prose is wrapped by the model, not the formatter.
+"src/loom/prompts.py" = ["E501"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

loom_threads-0.1.0/src/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_threads-0.1.0/src/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_threads-0.1.0/src/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()