loom-os 0.2.0__tar.gz

loom_os-0.2.0/PKG-INFO

@@ -0,0 +1,222 @@
+Metadata-Version: 2.4
+Name: loom-os
+Version: 0.2.0
+Summary: Loom OS — unified agent memory fabric for multi-agent coding
+Author: Mohamed Hussien
+License: MIT
+Project-URL: Homepage, https://github.com/mohamedhusseinios/Loom-OS
+Project-URL: Repository, https://github.com/mohamedhusseinios/Loom-OS
+Project-URL: Issues, https://github.com/mohamedhusseinios/Loom-OS/issues
+Keywords: ai-agents,knowledge-graph,agent-memory,mcp,code-graph
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: uvicorn[standard]>=0.30.0
+Requires-Dist: watchdog>=5.0.0
+Requires-Dist: graphifyy>=0.8.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: aiosqlite>=0.20.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: llm
+Requires-Dist: openai>=1.0; extra == "llm"
+Requires-Dist: anthropic>=0.39; extra == "llm"
+Requires-Dist: httpx>=0.27; extra == "llm"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24.0; extra == "dev"
+Requires-Dist: httpx>=0.27.0; extra == "dev"
+
+<div align="center">
+
+<img src="docs/branding/loom-icon-warp-256.png" alt="Loom OS" width="120" height="120" />
+
+# Loom OS
+
+**Unified agent memory fabric**
+
+</div>
+
+**Loom OS** is a unified agent memory fabric that weaves multiple AI coding agents — Claude Code, Codex, Hermes, Cursor, and more — into one shared, [Graphify](https://github.com/nousresearch/graphify)-powered knowledge graph per project. Agents talk to Loom OS **only through the filesystem**: they drop files into a per-project inbox and the daemon does the rest. There is no SDK, no API client, and no auth. A Next.js dashboard is the control plane for browsing the graph, managing agents, and dispatching work.
+
+> **Naming.** The product is **Loom OS**. The installable package and CLI are **`loom`** (`pip install loom`). The repository directory and design/plan docs are named **`agentic-os`**. They all refer to the same project.
+
+---
+
+## Quick Start
+
+```bash
+pip install loom                            # base install — no LLM keys required
+loom start                                  # starts daemon on http://127.0.0.1:8472
+loom init --project my-app --project-path . # bootstraps inbox + starter register.json
+# (or register a specific agent instead of init):
+#   loom register --agent claude-code --project my-app --project-path /abs/path
+open http://localhost:3000                  # dashboard (run the Next.js app — see below)
+```
+
+The dashboard is a Next.js app under `dashboard/`. Start it with:
+
+```bash
+cd dashboard && npm install && npm run dev   # http://localhost:3000
+```
+
+| What | Where |
+|------|-------|
+| Daemon (REST + WebSocket) | `http://127.0.0.1:8472` |
+| Dashboard | `http://localhost:3000` |
+
+**Prerequisites:** Python 3.11+, Node.js 20+. Graphify ships as a dependency (`graphifyy`).
+
+> Want optional LLM-powered extraction (Ollama / OpenAI / Claude)?  
+> `pip install loom[llm]` — the base install works without any LLM.
+
+---
+
+## Capabilities
+
+- **Multi-agent knowledge graph** — Graphify parses your codebase AST (zero API keys, code-only builds) and builds a per-project graph of files, functions, classes, communities, and execution flows. An optional LLM extraction layer can enrich the graph with semantic edges.
+- **Filesystem inbox protocol** — agents never call an API. They write files into `~/.loom/inbox/<project>/`: `register.json`, `heartbeat.json`, `finding-*.md` (markdown + YAML frontmatter), `decision-*.md` (ADRs), `task-*.json` (dispatched tasks). The daemon watches, processes, and moves each file to `.processed/`.
+- **Next.js dashboard** — interactive graph visualization (reagraph/cytoscape), agent management with live status, a Kanban task board (Todo · Ready · Running · Blocked · Done), project CRUD, knowledge-source discovery, and hybrid search. Bilingual (en/ar) with RTL support.
+- **Task dispatch + worker execution** — dispatch tasks from the dashboard; a `loom worker` process picks up Running tasks, executes them in an isolated **git worktree**, and enforces a per-task USD budget cap. Results flow back as findings.
+- **Hybrid search** — text (FTS) + vector embeddings + graph traversal in a single query path.
+- **Optional LLM backends** — Ollama (default, local), OpenAI, or Anthropic Claude. Install with `pip install loom[llm]`. The base package needs no LLM at all.
+- **MCP server** — `loom-mcp` exposes graph queries and finding ingestion over the Model Context Protocol so any MCP-aware agent can read from and write to Loom OS.
+- **Single-process daemon, zero infrastructure** — no Docker, no Neo4j, no cloud. One Python process (FastAPI + uvicorn) plus the Next.js dashboard. State lives in SQLite (`~/.loom/state.db`).
+
+---
+
+## Architecture
+
+```
+Browser :3000 ──▶  ┌──────────────────────────────────┐
+                   │       Next.js Dashboard          │
+                   └──────────────┬───────────────────┘
+                                  │ REST + WebSocket
+┌─────────────────────────────────┼───────────────────┐
+│                  Loom Daemon (Python, :8472)          │
+│                                                       │
+│  watcher ──▶ router ──▶ registry / graph_engine ──▶ api
+│                │              │                       │
+│           (SQLite)      (Graphify CLI subprocess,     │
+│           ~/.loom/       graph.json sidecar)          │
+│            state.db                                     │
+└───────────────────────────────────────────────────────┘
+     ▲                  ▲                  ▲
+     │                  │                  │
+~/.loom/inbox/proj   ~/.loom/inbox/proj   ~/.loom/inbox/proj
+  Claude Code           Codex              Hermes
+```
+
+**Two processes:**
+
+1. **Python daemon** (`daemon/`) — FastAPI + uvicorn on `127.0.0.1:8472`. REST routes plus a single `/ws` WebSocket for live updates. CORS allows `http://localhost:3000`.
+2. **Next.js dashboard** (`dashboard/`) — App Router on `:3000`. Talks to the daemon over REST + WebSocket.
+
+**Filesystem protocol.** Agents write files into `~/.loom/inbox/<project>/`. The daemon watches the inbox, dispatches by filename, builds/updates the knowledge graph, and pushes live events to the dashboard.
+
+**Daemon module map & data flow:**
+
+```
+watcher.py        watchdog observer on ~/.loom/inbox (recursive).
+                  Marshals filesystem events onto the asyncio loop.
+    ↓
+router.py         Dispatches by filename → _handle_register, _handle_heartbeat,
+                  _handle_finding, _handle_decision, _handle_task.
+                  Moves processed files to .processed/. Rate-limits graph
+                  updates (1 / 30s / project). Emits WsEvents to a queue.
+    ↓
+registry.py       AgentRegistry: aiosqlite over ~/.loom/state.db.
+                  Tables: agents, projects, tasks. CRUD + graph-stat persistence.
+graph_engine.py   GraphEngine: build / update / query / stats / topology /
+                  communities / flows. Invokes `graphify` as a CLI subprocess
+                  (asyncio.to_thread); reads <project>/graphify-out/graph.json.
+extractors.py     Optional LLM extraction layer (injectable backend).
+extracted_store.py  Sidecar store for LLM-extracted semantic edges.
+api.py            FastAPI routes + WebSocket fan-out.
+mcp_server.py     MCP server (loom-mcp entry point).
+worker.py         Worker: executes Running tasks in git-worktree isolation.
+```
+
+---
+
+## CLI Reference
+
+| Command | Description |
+|---------|-------------|
+| `loom start` | Start the daemon (FastAPI + uvicorn on `:8472`) |
+| `loom init --project <name> --project-path <path>` | Bootstrap a project: create inbox + starter `register.json` |
+| `loom register --agent <name> --project <name> --project-path <path>` | Register a coding agent with a project |
+| `loom unregister --agent <name> --project <name>` | Remove an agent from a project |
+| `loom detect-agents` | List coding agents detected on this machine |
+| `loom worker --project <name> --agent <name> --project-path <path>` | Run a worker that executes Running tasks (git worktree isolation, `--max-budget-usd` cap) |
+| `loom-mcp` | Start the MCP server |
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/mohamedhusseinios/Loom-OS.git
+cd Loom-OS
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+
+pytest tests/ -v              # full test suite (pytest-asyncio)
+bash scripts/smoke-test.sh    # end-to-end: daemon + agent + API
+cd dashboard && npm run dev   # dashboard hot-reload
+```
+
+See the [Development Guide](docs/DEVELOPMENT.md) for project structure, test patterns, and contribution conventions.
+
+---
+
+## Documentation
+
+| Guide | Covers |
+|-------|--------|
+| [Architecture](docs/ARCHITECTURE.md) | Two-process design, module map, data flow, design principles |
+| [Filesystem Protocol](docs/FILESYSTEM-PROTOCOL.md) | Full inbox protocol spec — every file type, format, processing rule |
+| [API Reference](docs/API.md) | Complete REST + WebSocket API, all endpoints and event types |
+| [Dashboard Guide](docs/DASHBOARD.md) | Page-by-page tour, tech stack, i18n, component map |
+| [Task Board & Worker](docs/TASK-BOARD.md) | Kanban lifecycle, worker execution model, git worktree isolation |
+| [Agent Lifecycle](docs/AGENT-LIFECYCLE.md) | Registration → contribution → dispatch flow, agent status, shared context |
+| [Development Guide](docs/DEVELOPMENT.md) | Setup, project structure, test suite, daemon patterns, contribution conventions |
+
+### Design specs & implementation plans
+
+- [Design spec](docs/superpowers/specs/2026-06-25-agentic-os-design.md) — original system design
+- [Dashboard features design](docs/superpowers/specs/2026-06-26-agentic-os-dashboard-features-design.md)
+- [Kanban task board design](docs/superpowers/specs/2026-06-27-agentic-os-kanban-task-board-design.md)
+- [Live task execution design](docs/superpowers/specs/2026-06-27-agentic-os-live-task-execution-design.md)
+- [Multi-agent worker runners design](docs/superpowers/specs/2026-06-28-multi-agent-worker-runners-design.md)
+- [Post-parity roadmap design](docs/superpowers/specs/2026-06-29-loom-post-parity-roadmap-design.md)
+- [Implementation plan](docs/plans/2026-06-25-agentic-os-implementation.md)
+- [Dashboard features plan](docs/plans/2026-06-26-dashboard-features-implementation.md)
+- [Competitor gap-closure roadmap](docs/plans/2026-06-26-competitor-gap-closure-implementation.md)
+- [Live task execution plan](docs/plans/2026-06-27-agentic-os-live-task-execution-implementation.md)
+- [Post-parity roadmap plan](docs/plans/2026-06-29-post-parity-roadmap-implementation.md)
+
+---
+
+## Brand
+
+Monochrome, geometric. **Warp** (an L woven on a loom) is the primary mark; **Lattice** (an L traced through a knowledge graph) is the alternate.
+
+| | Warp (primary) | Lattice (alternate) |
+|---|---|---|
+| Icon | <img src="docs/branding/loom-icon-warp-256.png" width="64" /> | <img src="docs/branding/loom-icon-lattice-512.png" width="64" /> |
+
+- **Ink** `#141414` · **Paper** `#FFFFFF` · greys `#6F6F6F`, `#E5E5E5`
+- **Wordmark** Space Grotesk 600, tracking −3.5%
+- Full asset kit: [`docs/branding/`](docs/branding/README.md)
+
+---
+
+## License
+
+MIT © Mohamed Hussien

loom_os-0.2.0/README.md

@@ -0,0 +1,188 @@
+<div align="center">
+
+<img src="docs/branding/loom-icon-warp-256.png" alt="Loom OS" width="120" height="120" />
+
+# Loom OS
+
+**Unified agent memory fabric**
+
+</div>
+
+**Loom OS** is a unified agent memory fabric that weaves multiple AI coding agents — Claude Code, Codex, Hermes, Cursor, and more — into one shared, [Graphify](https://github.com/nousresearch/graphify)-powered knowledge graph per project. Agents talk to Loom OS **only through the filesystem**: they drop files into a per-project inbox and the daemon does the rest. There is no SDK, no API client, and no auth. A Next.js dashboard is the control plane for browsing the graph, managing agents, and dispatching work.
+
+> **Naming.** The product is **Loom OS**. The installable package and CLI are **`loom`** (`pip install loom`). The repository directory and design/plan docs are named **`agentic-os`**. They all refer to the same project.
+
+---
+
+## Quick Start
+
+```bash
+pip install loom                            # base install — no LLM keys required
+loom start                                  # starts daemon on http://127.0.0.1:8472
+loom init --project my-app --project-path . # bootstraps inbox + starter register.json
+# (or register a specific agent instead of init):
+#   loom register --agent claude-code --project my-app --project-path /abs/path
+open http://localhost:3000                  # dashboard (run the Next.js app — see below)
+```
+
+The dashboard is a Next.js app under `dashboard/`. Start it with:
+
+```bash
+cd dashboard && npm install && npm run dev   # http://localhost:3000
+```
+
+| What | Where |
+|------|-------|
+| Daemon (REST + WebSocket) | `http://127.0.0.1:8472` |
+| Dashboard | `http://localhost:3000` |
+
+**Prerequisites:** Python 3.11+, Node.js 20+. Graphify ships as a dependency (`graphifyy`).
+
+> Want optional LLM-powered extraction (Ollama / OpenAI / Claude)?  
+> `pip install loom[llm]` — the base install works without any LLM.
+
+---
+
+## Capabilities
+
+- **Multi-agent knowledge graph** — Graphify parses your codebase AST (zero API keys, code-only builds) and builds a per-project graph of files, functions, classes, communities, and execution flows. An optional LLM extraction layer can enrich the graph with semantic edges.
+- **Filesystem inbox protocol** — agents never call an API. They write files into `~/.loom/inbox/<project>/`: `register.json`, `heartbeat.json`, `finding-*.md` (markdown + YAML frontmatter), `decision-*.md` (ADRs), `task-*.json` (dispatched tasks). The daemon watches, processes, and moves each file to `.processed/`.
+- **Next.js dashboard** — interactive graph visualization (reagraph/cytoscape), agent management with live status, a Kanban task board (Todo · Ready · Running · Blocked · Done), project CRUD, knowledge-source discovery, and hybrid search. Bilingual (en/ar) with RTL support.
+- **Task dispatch + worker execution** — dispatch tasks from the dashboard; a `loom worker` process picks up Running tasks, executes them in an isolated **git worktree**, and enforces a per-task USD budget cap. Results flow back as findings.
+- **Hybrid search** — text (FTS) + vector embeddings + graph traversal in a single query path.
+- **Optional LLM backends** — Ollama (default, local), OpenAI, or Anthropic Claude. Install with `pip install loom[llm]`. The base package needs no LLM at all.
+- **MCP server** — `loom-mcp` exposes graph queries and finding ingestion over the Model Context Protocol so any MCP-aware agent can read from and write to Loom OS.
+- **Single-process daemon, zero infrastructure** — no Docker, no Neo4j, no cloud. One Python process (FastAPI + uvicorn) plus the Next.js dashboard. State lives in SQLite (`~/.loom/state.db`).
+
+---
+
+## Architecture
+
+```
+Browser :3000 ──▶  ┌──────────────────────────────────┐
+                   │       Next.js Dashboard          │
+                   └──────────────┬───────────────────┘
+                                  │ REST + WebSocket
+┌─────────────────────────────────┼───────────────────┐
+│                  Loom Daemon (Python, :8472)          │
+│                                                       │
+│  watcher ──▶ router ──▶ registry / graph_engine ──▶ api
+│                │              │                       │
+│           (SQLite)      (Graphify CLI subprocess,     │
+│           ~/.loom/       graph.json sidecar)          │
+│            state.db                                     │
+└───────────────────────────────────────────────────────┘
+     ▲                  ▲                  ▲
+     │                  │                  │
+~/.loom/inbox/proj   ~/.loom/inbox/proj   ~/.loom/inbox/proj
+  Claude Code           Codex              Hermes
+```
+
+**Two processes:**
+
+1. **Python daemon** (`daemon/`) — FastAPI + uvicorn on `127.0.0.1:8472`. REST routes plus a single `/ws` WebSocket for live updates. CORS allows `http://localhost:3000`.
+2. **Next.js dashboard** (`dashboard/`) — App Router on `:3000`. Talks to the daemon over REST + WebSocket.
+
+**Filesystem protocol.** Agents write files into `~/.loom/inbox/<project>/`. The daemon watches the inbox, dispatches by filename, builds/updates the knowledge graph, and pushes live events to the dashboard.
+
+**Daemon module map & data flow:**
+
+```
+watcher.py        watchdog observer on ~/.loom/inbox (recursive).
+                  Marshals filesystem events onto the asyncio loop.
+    ↓
+router.py         Dispatches by filename → _handle_register, _handle_heartbeat,
+                  _handle_finding, _handle_decision, _handle_task.
+                  Moves processed files to .processed/. Rate-limits graph
+                  updates (1 / 30s / project). Emits WsEvents to a queue.
+    ↓
+registry.py       AgentRegistry: aiosqlite over ~/.loom/state.db.
+                  Tables: agents, projects, tasks. CRUD + graph-stat persistence.
+graph_engine.py   GraphEngine: build / update / query / stats / topology /
+                  communities / flows. Invokes `graphify` as a CLI subprocess
+                  (asyncio.to_thread); reads <project>/graphify-out/graph.json.
+extractors.py     Optional LLM extraction layer (injectable backend).
+extracted_store.py  Sidecar store for LLM-extracted semantic edges.
+api.py            FastAPI routes + WebSocket fan-out.
+mcp_server.py     MCP server (loom-mcp entry point).
+worker.py         Worker: executes Running tasks in git-worktree isolation.
+```
+
+---
+
+## CLI Reference
+
+| Command | Description |
+|---------|-------------|
+| `loom start` | Start the daemon (FastAPI + uvicorn on `:8472`) |
+| `loom init --project <name> --project-path <path>` | Bootstrap a project: create inbox + starter `register.json` |
+| `loom register --agent <name> --project <name> --project-path <path>` | Register a coding agent with a project |
+| `loom unregister --agent <name> --project <name>` | Remove an agent from a project |
+| `loom detect-agents` | List coding agents detected on this machine |
+| `loom worker --project <name> --agent <name> --project-path <path>` | Run a worker that executes Running tasks (git worktree isolation, `--max-budget-usd` cap) |
+| `loom-mcp` | Start the MCP server |
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/mohamedhusseinios/Loom-OS.git
+cd Loom-OS
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+
+pytest tests/ -v              # full test suite (pytest-asyncio)
+bash scripts/smoke-test.sh    # end-to-end: daemon + agent + API
+cd dashboard && npm run dev   # dashboard hot-reload
+```
+
+See the [Development Guide](docs/DEVELOPMENT.md) for project structure, test patterns, and contribution conventions.
+
+---
+
+## Documentation
+
+| Guide | Covers |
+|-------|--------|
+| [Architecture](docs/ARCHITECTURE.md) | Two-process design, module map, data flow, design principles |
+| [Filesystem Protocol](docs/FILESYSTEM-PROTOCOL.md) | Full inbox protocol spec — every file type, format, processing rule |
+| [API Reference](docs/API.md) | Complete REST + WebSocket API, all endpoints and event types |
+| [Dashboard Guide](docs/DASHBOARD.md) | Page-by-page tour, tech stack, i18n, component map |
+| [Task Board & Worker](docs/TASK-BOARD.md) | Kanban lifecycle, worker execution model, git worktree isolation |
+| [Agent Lifecycle](docs/AGENT-LIFECYCLE.md) | Registration → contribution → dispatch flow, agent status, shared context |
+| [Development Guide](docs/DEVELOPMENT.md) | Setup, project structure, test suite, daemon patterns, contribution conventions |
+
+### Design specs & implementation plans
+
+- [Design spec](docs/superpowers/specs/2026-06-25-agentic-os-design.md) — original system design
+- [Dashboard features design](docs/superpowers/specs/2026-06-26-agentic-os-dashboard-features-design.md)
+- [Kanban task board design](docs/superpowers/specs/2026-06-27-agentic-os-kanban-task-board-design.md)
+- [Live task execution design](docs/superpowers/specs/2026-06-27-agentic-os-live-task-execution-design.md)
+- [Multi-agent worker runners design](docs/superpowers/specs/2026-06-28-multi-agent-worker-runners-design.md)
+- [Post-parity roadmap design](docs/superpowers/specs/2026-06-29-loom-post-parity-roadmap-design.md)
+- [Implementation plan](docs/plans/2026-06-25-agentic-os-implementation.md)
+- [Dashboard features plan](docs/plans/2026-06-26-dashboard-features-implementation.md)
+- [Competitor gap-closure roadmap](docs/plans/2026-06-26-competitor-gap-closure-implementation.md)
+- [Live task execution plan](docs/plans/2026-06-27-agentic-os-live-task-execution-implementation.md)
+- [Post-parity roadmap plan](docs/plans/2026-06-29-post-parity-roadmap-implementation.md)
+
+---
+
+## Brand
+
+Monochrome, geometric. **Warp** (an L woven on a loom) is the primary mark; **Lattice** (an L traced through a knowledge graph) is the alternate.
+
+| | Warp (primary) | Lattice (alternate) |
+|---|---|---|
+| Icon | <img src="docs/branding/loom-icon-warp-256.png" width="64" /> | <img src="docs/branding/loom-icon-lattice-512.png" width="64" /> |
+
+- **Ink** `#141414` · **Paper** `#FFFFFF` · greys `#6F6F6F`, `#E5E5E5`
+- **Wordmark** Space Grotesk 600, tracking −3.5%
+- Full asset kit: [`docs/branding/`](docs/branding/README.md)
+
+---
+
+## License
+
+MIT © Mohamed Hussien

loom_os-0.2.0/daemon/__init__.py

@@ -0,0 +1 @@
+"""Loom — unified agent memory fabric."""