Metadata-Version: 2.4
Name: loom-run
Version: 0.2.0
Summary: Official Loom stack showcase: local-first durable chat agent with checkpoint/resume, multi-agent supervisor, MCP tools, and offline traces.
Author: kroq86
License-Expression: MIT
Project-URL: Homepage, https://github.com/kroq86/loom-run
Project-URL: Repository, https://github.com/kroq86/loom-run
Project-URL: Documentation, https://kroq86.github.io/loom-stack/
Project-URL: Issues, https://github.com/kroq86/loom-run/issues
Project-URL: Changelog, https://github.com/kroq86/loom-run/commits/main
Project-URL: Loom stack (showcase hub), https://kroq86.github.io/loom-stack/
Project-URL: loom-runner (runtime), https://github.com/kroq86/loom-runner
Project-URL: flow-xray (traces), https://github.com/kroq86/flow-xray
Project-URL: agents_architecture (reference), https://github.com/kroq86/agents_architecture
Keywords: agents,ai-agents,async,checkpoint,durable-execution,flow-xray,langgraph-alternative,local-first,loom,loom-runner,loom-stack,mcp,model-context-protocol,multi-agent,multi-agent-orchestration,resumable-agents,sqlite,supervisor
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: loom-runner>=0.1.1
Requires-Dist: loom-tailcalls>=0.2.1
Requires-Dist: flow-xray>=0.3.4
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: httpx>=0.27; extra == "dev"
Provides-Extra: openai
Requires-Dist: openai>=1.0; extra == "openai"
Provides-Extra: api
Requires-Dist: fastapi>=0.100; extra == "api"
Requires-Dist: uvicorn[standard]>=0.23; extra == "api"
Dynamic: license-file

[![Loom Stack](https://kroq86.github.io/loom-stack/assets/loom-stack-banner.png)](https://kroq86.github.io/loom-stack/)

# loom-run — official Loom stack showcase

[![PyPI](https://img.shields.io/pypi/v/loom-run)](https://pypi.org/project/loom-run/)
[![GitHub](https://img.shields.io/github/stars/kroq86/loom-run?style=social)](https://github.com/kroq86/loom-run)
[![Loom stack docs](https://img.shields.io/badge/Loom_stack-showcase-8B7355)](https://kroq86.github.io/loom-stack/)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Tests](https://github.com/kroq86/loom-run/actions/workflows/tests.yml/badge.svg)](https://github.com/kroq86/loom-run/actions/workflows/tests.yml)

> **Official reference product** for the [Loom stack](https://kroq86.github.io/loom-stack/) — not a generic agent framework, but the **runnable demo** that wires [loom-runner](https://github.com/kroq86/loom-runner) + [flow-xray](https://github.com/kroq86/flow-xray) into a local-first durable chat agent with multi-agent supervisor.

**Keywords:** durable agents · checkpoint resume · multi-agent orchestration · MCP tools · local-first · SQLite · inspectable runs · LangGraph alternative (runtime slice)

| | |
|---|---|
| **Showcase hub** | [kroq86.github.io/loom-stack](https://kroq86.github.io/loom-stack/) |
| **This repo** | [github.com/kroq86/loom-run](https://github.com/kroq86/loom-run) |
| **Runtime layer** | [github.com/kroq86/loom-runner](https://github.com/kroq86/loom-runner) |
| **Local traces** | [github.com/kroq86/flow-xray](https://github.com/kroq86/flow-xray) |
| **Ops product** | [github.com/kroq86/loom-ops](https://github.com/kroq86/loom-ops) — runbooks, HITL, incident response |

```text
User message  →  coordinator (LLM + tools)  →  loom-runner checkpoint/resume  →  flow-xray --trace
                      ↑ supervise → subagent runs (v0.2)
```

## What this repo is

| Role | Explanation |
|------|-------------|
| **Showcase / reference product** | End-to-end proof that the Loom stack works: CLI, mock LLM (CI-safe), tools, supervisor, E2E tests |
| **Not** | LangGraph, CrewAI, or a hosted agent platform |
| **Built on** | [loom-runner](https://github.com/kroq86/loom-runner) (durability), [loom-tailcalls](https://github.com/kroq86/loom-tailcalls) (loop shape), [flow-xray](https://github.com/kroq86/flow-xray) (HTML traces) |
| **Pattern from** | [agents_architecture](https://github.com/kroq86/agents_architecture) — coordinator loop only, not full backend |

If you want **libraries to compose** → start with [loom-runner](https://github.com/kroq86/loom-runner).  
If you want **see it all working in 30 seconds** → clone this repo.  
If you want **incident/deploy runbooks** (not dev chat) → [loom-ops](https://github.com/kroq86/loom-ops).

More: [Showcase guide](docs/SHOWCASE.md) · [Architecture](docs/ARCHITECTURE.md)

## Install

**From PyPI:**

```bash
pip install "loom-run[api,openai]"
loom-run chat "explain checkpoint policy" --run-id demo --db runs.sqlite --mock-llm
```

**From source:**

```bash
git clone https://github.com/kroq86/loom-run.git
cd loom-run
python3.13 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev,api,openai]"
```

Ecosystem map: [loom-stack ECOSYSTEM.md](https://github.com/kroq86/loom-stack/blob/main/docs/ECOSYSTEM.md)

## Demo commands (copy-paste)

**Single agent (mock LLM, no API key):**

```bash
loom-run chat "explain checkpoint policy" --run-id demo --db runs.sqlite --mock-llm
loom-run resume --run-id demo --db runs.sqlite --max-steps 20
loom-run explain --run-id demo --db runs.sqlite
loom-run chat "explain checkpoint policy" --run-id demo2 --db runs.sqlite --mock-llm --trace trace.html
```

**Multi-agent supervisor (v0.2):**

```bash
loom-run supervise "explain checkpoint policy" --run-id team-demo --db runs.sqlite --mock-llm
loom-run explain --run-id team-demo:sub:researcher --db runs.sqlite
```

**HTTP SSE (optional):**

```bash
loom-run serve --db runs.sqlite --mock-llm
curl -N -X POST http://127.0.0.1:8765/chat \
  -H 'Content-Type: application/json' \
  -d '{"message":"explain checkpoint policy","run_id":"demo","max_steps":20}'
```

## Tools

| Tool | Default | With MCP |
|------|---------|----------|
| `read_file` | local workspace read | [rule-based-verifier](https://github.com/kroq86/rule-based-verifier) → `read_repo_file` |
| `search_docs` | grep `*.md` in workspace | [mcp-docs-memory](https://github.com/kroq86/mcp-docs-memory) → `docs_search` |
| `run_tests` | `pytest -q` in workspace | rule-based-verifier → `run_tests` |
| `delegate_subagent` | supervisor → child chat run | — |

MCP config: [`mcp.servers.example.json`](mcp.servers.example.json) · env: [docs/ENV.md](docs/ENV.md)

## Full Loom stack map

| Layer | Repo | Role |
|-------|------|------|
| **Dev showcase (this repo)** | [loom-run](https://github.com/kroq86/loom-run) | Reference chat agent + supervisor |
| **Ops product** | [loom-ops](https://github.com/kroq86/loom-ops) | Runbook supervisor (planner / executor / verifier) |
| Durability | [loom-runner](https://github.com/kroq86/loom-runner) | SQLite checkpoint, resume, idempotent tools |
| Transitions | [loom-tailcalls](https://github.com/kroq86/loom-tailcalls) | Stack-safe `@tailrec` driver |
| Traces | [flow-xray](https://github.com/kroq86/flow-xray) | Offline HTML execution traces |
| Coordinator reference | [agents_architecture](https://github.com/kroq86/agents_architecture) | Production backend patterns |
| Verification MCP | [rule-based-verifier](https://github.com/kroq86/rule-based-verifier) | Tests, lint, repo read |
| Docs/memory MCP | [mcp-docs-memory](https://github.com/kroq86/mcp-docs-memory) | Semantic docs search |

## Tests

```bash
python -m pytest -q              # 21 tests incl. subprocess E2E
python -m pytest -q tests/test_e2e.py
```

## Docs

- [Showcase & discovery](docs/SHOWCASE.md) — SEO, links, positioning
- [Architecture](docs/ARCHITECTURE.md)
- [Environment variables](docs/ENV.md)

## License

MIT · [kroq86](https://github.com/kroq86)
