ramure 0.0.1__tar.gz

ramure-0.0.1/.gitignore

@@ -0,0 +1,4 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+logs/

ramure-0.0.1/PKG-INFO

@@ -0,0 +1,207 @@
+Metadata-Version: 2.4
+Name: ramure
+Version: 0.0.1
+Summary: A multi-agent orchestration runtime
+Requires-Python: >=3.11
+Requires-Dist: typer>=0.12
+Requires-Dist: websockets>=13.0
+Description-Content-Type: text/markdown
+
+# ramure
+
+A lightweight async multi-agent orchestration library. Agents run as [pi](https://github.com/mariozechner/pi-coding-agent) instances in tmux sessions, coordinated by Python process functions.
+
+## Quick start
+
+```python
+import asyncio
+from ramure import LocalImage, agent, agent_process, done, wait
+
+
+@agent_process(image=LocalImage(), timeout=30)
+async def summarize(text: str) -> str:
+    worker = await agent("worker")
+
+    @worker.on("finish")
+    async def on_finish(summary: str) -> str:
+        """Call this with your summary when done."""
+        done(summary)
+        return "Done."
+
+    await worker.send(f"Summarize this text, then call finish:\n\n{text}")
+    return await wait()
+
+
+asyncio.run(summarize("The quick brown fox jumped over the lazy dog. " * 20))
+```
+
+## Core concepts
+
+### Processes
+
+The unit of composition is a **process function** — an async function decorated with `@agent_process` that creates agents, wires them up, and returns a result.
+
+```python
+@agent_process
+async def build_and_review(spec: str) -> str:
+    builder = await agent("builder")
+    auditor = await agent("auditor")
+    connect(builder, auditor)
+
+    @builder.on("submit")
+    async def on_submit(code: str):
+        await auditor.send(f"Review:\n{code}")
+        return "Submitted"
+
+    @auditor.on("approve")
+    async def on_approve(code: str):
+        done(code)
+        return "Approved"
+
+    @auditor.on("reject")
+    async def on_reject(feedback: str):
+        await builder.send(f"Fix: {feedback}")
+        return "Sent back"
+
+    await builder.send(f"Implement: {spec}")
+    await auditor.send("Review the builder's work.")
+    return await wait()
+```
+
+- **Root process** (no active runtime): creates a `Runtime` and websocket server, tears them down on return.
+- **Nested process** (runtime already active): creates a child scope, inherits the runtime.
+- `done(value)` / `fail(reason)` signal completion from tool handlers.
+- `await wait()` blocks until `done()` or `fail()` is called.
+- Agents are cleaned up automatically when their owning process returns.
+
+### Composition
+
+Processes compose by calling each other:
+
+```python
+@agent_process(image=LocalImage())
+async def main():
+    code = await write_code("fibonacci function")
+    review = await review_code(code)
+    return code
+```
+
+Concurrent fan-out with `asyncio.gather`:
+
+```python
+@agent_process(image=LocalImage())
+async def main():
+    results = await asyncio.gather(
+        research("Rust"),
+        research("Python"),
+    )
+    return results
+```
+
+### Observation and retry
+
+`spawn()` runs a process in the background and returns a handle with an event stream:
+
+```python
+@agent_process(image=LocalImage())
+async def main():
+    handle = spawn(flaky_task, "write a haiku")
+
+    async for event in handle.events:
+        if event.type == "failed":
+            handle = spawn(flaky_task, "write a haiku")
+        if event.type == "done":
+            return event.data
+```
+
+Processes can emit custom events with `emit(type, data)`. Agent event logs are also async-iterable via `agent.events`.
+
+### Endpoints
+
+A process can expose endpoints to its parent. The parent can call them
+directly, or attach them to an agent as tools. A child's agents are
+available to the parent via ``handle.agents`` without any extra step.
+
+```python
+@agent_process
+async def worker_pool():
+    @expose
+    async def submit_task(task: str) -> str:
+        w = await agent(f"worker-{uuid.uuid4().hex[:8]}")
+        await w.send(f"Do: {task}")
+        return w.name
+
+    return await wait()
+
+handle = spawn(worker_pool)
+name = await handle.call("submit_task", task="build a server")
+worker = handle.agents[name]
+```
+
+To let an agent consume a process's endpoints, attach the handle:
+
+```python
+@agent_process
+async def main():
+    pool = spawn(worker_pool)
+    dispatcher = await agent("dispatcher")
+    await pool.attach(dispatcher)          # all endpoints as tools
+    # or: await pool.attach(dispatcher, only=["submit_task"], prefix="pool_")
+    await dispatcher.send("Use submit_task to delegate jobs.")
+    return await wait()
+```
+
+Endpoints run inside the child process's scope, so calls to `emit`,
+`done`, and `fail` inside an endpoint affect the child.
+
+## API
+
+### Decorator
+
+- `@agent_process(image=, timeout=, log_dir=)` — wrap an async function as a process
+
+### Ambient functions
+
+- `await agent(name, system_prompt=, image=, machine=)` — create an agent
+- `await machine(image=)` — spawn a standalone machine
+- `connect(a, b, direction=)` — allow agents to message/send files
+- `done(result)` — signal process success
+- `fail(reason)` — signal process failure
+- `await wait()` — block until `done()` or `fail()`
+- `emit(type, data)` — emit a process event
+- `spawn(fn, *args, **kwargs)` — run a process in background, returns `ProcessHandle`
+- `@expose` — register an async function as an endpoint callable via `handle.call()` or attachable via `handle.attach()`
+- `current_runtime()` — access the runtime (rarely needed)
+
+### Agent methods
+
+- `agent.on(tool_name)` — decorator to register a tool handler
+- `agent.send(message)` — send a message to the agent
+- `agent.exec(command)` — run a shell command on the agent's machine
+- `agent.events` — async-iterable log of raw agent events
+
+### ProcessHandle
+
+- `handle.events` — async-iterable stream of process events
+- `handle.agents` — dict of the child's agents
+- `await handle.call(name, **kwargs)` — call an endpoint
+- `await handle.attach(agent, only=, prefix=)` — register endpoints as tools on an agent
+- `handle.cancel()` — cancel the process
+
+## CLI
+
+Running an `@agent_process` opens a Unix socket at
+`~/.ramure/runtimes/{execution_id}.sock` and writes a per-run log tree
+under `~/.ramure/logs/{execution_id}/`. The `ramure` CLI uses these:
+
+```
+ramure ls                         # live runs
+ramure status [--id <prefix>]     # agents, machines, connections
+ramure send <agent> <msg> [--id <prefix>]
+ramure connect <agent> [--id <prefix>]  # tmux attach
+ramure ssh <agent> [--id <prefix>]      # shell on the agent's machine
+```
+
+`--id` takes an execution-id prefix. Omit when there's one live run.
+All commands require the run to be live (socket present). Finished-run
+logs are at `~/.ramure/logs/{execution_id}/` — read them directly.

ramure-0.0.1/README.md

@@ -0,0 +1,198 @@
+# ramure
+
+A lightweight async multi-agent orchestration library. Agents run as [pi](https://github.com/mariozechner/pi-coding-agent) instances in tmux sessions, coordinated by Python process functions.
+
+## Quick start
+
+```python
+import asyncio
+from ramure import LocalImage, agent, agent_process, done, wait
+
+
+@agent_process(image=LocalImage(), timeout=30)
+async def summarize(text: str) -> str:
+    worker = await agent("worker")
+
+    @worker.on("finish")
+    async def on_finish(summary: str) -> str:
+        """Call this with your summary when done."""
+        done(summary)
+        return "Done."
+
+    await worker.send(f"Summarize this text, then call finish:\n\n{text}")
+    return await wait()
+
+
+asyncio.run(summarize("The quick brown fox jumped over the lazy dog. " * 20))
+```
+
+## Core concepts
+
+### Processes
+
+The unit of composition is a **process function** — an async function decorated with `@agent_process` that creates agents, wires them up, and returns a result.
+
+```python
+@agent_process
+async def build_and_review(spec: str) -> str:
+    builder = await agent("builder")
+    auditor = await agent("auditor")
+    connect(builder, auditor)
+
+    @builder.on("submit")
+    async def on_submit(code: str):
+        await auditor.send(f"Review:\n{code}")
+        return "Submitted"
+
+    @auditor.on("approve")
+    async def on_approve(code: str):
+        done(code)
+        return "Approved"
+
+    @auditor.on("reject")
+    async def on_reject(feedback: str):
+        await builder.send(f"Fix: {feedback}")
+        return "Sent back"
+
+    await builder.send(f"Implement: {spec}")
+    await auditor.send("Review the builder's work.")
+    return await wait()
+```
+
+- **Root process** (no active runtime): creates a `Runtime` and websocket server, tears them down on return.
+- **Nested process** (runtime already active): creates a child scope, inherits the runtime.
+- `done(value)` / `fail(reason)` signal completion from tool handlers.
+- `await wait()` blocks until `done()` or `fail()` is called.
+- Agents are cleaned up automatically when their owning process returns.
+
+### Composition
+
+Processes compose by calling each other:
+
+```python
+@agent_process(image=LocalImage())
+async def main():
+    code = await write_code("fibonacci function")
+    review = await review_code(code)
+    return code
+```
+
+Concurrent fan-out with `asyncio.gather`:
+
+```python
+@agent_process(image=LocalImage())
+async def main():
+    results = await asyncio.gather(
+        research("Rust"),
+        research("Python"),
+    )
+    return results
+```
+
+### Observation and retry
+
+`spawn()` runs a process in the background and returns a handle with an event stream:
+
+```python
+@agent_process(image=LocalImage())
+async def main():
+    handle = spawn(flaky_task, "write a haiku")
+
+    async for event in handle.events:
+        if event.type == "failed":
+            handle = spawn(flaky_task, "write a haiku")
+        if event.type == "done":
+            return event.data
+```
+
+Processes can emit custom events with `emit(type, data)`. Agent event logs are also async-iterable via `agent.events`.
+
+### Endpoints
+
+A process can expose endpoints to its parent. The parent can call them
+directly, or attach them to an agent as tools. A child's agents are
+available to the parent via ``handle.agents`` without any extra step.
+
+```python
+@agent_process
+async def worker_pool():
+    @expose
+    async def submit_task(task: str) -> str:
+        w = await agent(f"worker-{uuid.uuid4().hex[:8]}")
+        await w.send(f"Do: {task}")
+        return w.name
+
+    return await wait()
+
+handle = spawn(worker_pool)
+name = await handle.call("submit_task", task="build a server")
+worker = handle.agents[name]
+```
+
+To let an agent consume a process's endpoints, attach the handle:
+
+```python
+@agent_process
+async def main():
+    pool = spawn(worker_pool)
+    dispatcher = await agent("dispatcher")
+    await pool.attach(dispatcher)          # all endpoints as tools
+    # or: await pool.attach(dispatcher, only=["submit_task"], prefix="pool_")
+    await dispatcher.send("Use submit_task to delegate jobs.")
+    return await wait()
+```
+
+Endpoints run inside the child process's scope, so calls to `emit`,
+`done`, and `fail` inside an endpoint affect the child.
+
+## API
+
+### Decorator
+
+- `@agent_process(image=, timeout=, log_dir=)` — wrap an async function as a process
+
+### Ambient functions
+
+- `await agent(name, system_prompt=, image=, machine=)` — create an agent
+- `await machine(image=)` — spawn a standalone machine
+- `connect(a, b, direction=)` — allow agents to message/send files
+- `done(result)` — signal process success
+- `fail(reason)` — signal process failure
+- `await wait()` — block until `done()` or `fail()`
+- `emit(type, data)` — emit a process event
+- `spawn(fn, *args, **kwargs)` — run a process in background, returns `ProcessHandle`
+- `@expose` — register an async function as an endpoint callable via `handle.call()` or attachable via `handle.attach()`
+- `current_runtime()` — access the runtime (rarely needed)
+
+### Agent methods
+
+- `agent.on(tool_name)` — decorator to register a tool handler
+- `agent.send(message)` — send a message to the agent
+- `agent.exec(command)` — run a shell command on the agent's machine
+- `agent.events` — async-iterable log of raw agent events
+
+### ProcessHandle
+
+- `handle.events` — async-iterable stream of process events
+- `handle.agents` — dict of the child's agents
+- `await handle.call(name, **kwargs)` — call an endpoint
+- `await handle.attach(agent, only=, prefix=)` — register endpoints as tools on an agent
+- `handle.cancel()` — cancel the process
+
+## CLI
+
+Running an `@agent_process` opens a Unix socket at
+`~/.ramure/runtimes/{execution_id}.sock` and writes a per-run log tree
+under `~/.ramure/logs/{execution_id}/`. The `ramure` CLI uses these:
+
+```
+ramure ls                         # live runs
+ramure status [--id <prefix>]     # agents, machines, connections
+ramure send <agent> <msg> [--id <prefix>]
+ramure connect <agent> [--id <prefix>]  # tmux attach
+ramure ssh <agent> [--id <prefix>]      # shell on the agent's machine
+```
+
+`--id` takes an execution-id prefix. Omit when there's one live run.
+All commands require the run to be live (socket present). Finished-run
+logs are at `~/.ramure/logs/{execution_id}/` — read them directly.

ramure-0.0.1/cli-plan.md

@@ -0,0 +1,134 @@
+# CLI plan for interacting with live ramure runtimes
+
+## What the old CLI does, what's relevant
+
+Ignoring everything that's about "remote server, auth, billing, devboxes,
+repos, PRs, SSH":
+
+| Old command | What it does | Analog in new ramure |
+|---|---|---|
+| `ramure execution ls` | list running executions | `ramure ls` — list live runtimes |
+| `ramure execution status <slug>` | show status (agents, connections, machines) | `ramure status <id>` |
+| `ramure execution activity <slug> -n 50` | recent events | `ramure tail <id> [--agent X] [-n 50]` |
+| `ramure execution stop <slug>` | stop a run | no need for this |
+| `ramure execution send <slug> <msg> -a <agent>` | send a message to an agent | `ramure send <id> <agent> <msg>` |
+| `ramure execution ssh <slug> -a <agent>` | open shell on agent VM | needed, there can be remote machines |
+| `ramure execution connect <slug> -a <agent>` | resume the pi session | needed |
+| `ramure tool <name> key=value` (inside VM) | call a tool | **interesting** — see below |
+| `ramure tools` (inside VM) | list tools for current agent | same context |
+| `ramure exec program.py` | launch a new run | **unnecessary** — `python program.py` does it. |
+| `ramure apply <slug>` | apply diff to local | not our problem |
+| `ramure auth / init / devbox` | auth, repo setup | not our problem |
+
+So the "translation" of the old CLI into the new world is actually quite
+small: `ls`, `status`, `tail`, `stop`, `send`. Five commands. SSH/connect
+are replaced by `tmux attach`, which is better — more direct, no key
+management.
+
+## The interesting remnant: `ramure tool <name>`
+
+This is different from everything else. In the old model, an agent
+running inside a VM could shell out to the `ramure` CLI to call a tool
+on itself — it was a way to invoke runtime-registered Python handlers
+from bash. Equivalent in the new world would be: if you ssh'd into a
+ramure agent's machine (or cd'd into its tmux), you could type
+`ramure tool submit diff=... summary=...` to call the tool handler.
+
+That's an actual capability to think about: **invoking tools from
+outside the LLM.** In the old code it existed because agents could run
+bash tools that exercised Python handlers. In the new code it could be
+done, but it's not obvious we want it — the whole point of tool handlers
+
+is that the LLM calls them.
+
+I'd shelve this.
+
+no need for this
+
+## What's worth stealing from the old structure
+
+A few concrete things the old CLI got right:
+
+1. **Subcommand grouping by noun.** `ramure execution {ls, status, tail,
+   stop, send}`, `ramure devbox {create, ls, snapshot}`. Discoverable,
+   future-proof. For us: probably just flat (`ramure ls`, `ramure tail`,
+   `ramure send`), because there's only one noun (execution/run).
+
+2. **`--agent` defaults to "first" or "builder".** Instead of erroring
+   when omitted. Saves typing for the common single-agent case. We
+   should do the same: if a command needs an agent and only one exists,
+   use it; if none specified and multiple exist, list them and ask.
+
+3. **`ls` with `--all` to include stopped runs.** Assumes history. In
+   our world "stopped" isn't really a thing — the socket goes away. But
+   we do have the JSONL logs. `ramure ls --all` could list
+   `~/.ramure/runtimes/*.sock` (live) + `~/.ramure/logs/*/` (finished).
+   Probably overkill for now.
+
+4. **Event formatting via a shared `format_event`.** The old CLI had
+   `ramure/display.py` with one function that turns a LogEntry into a
+   pretty line. We want this for `tail`. Important detail because the
+   events we log are the same ones we'd display, and
+   format-once-used-many avoids a bunch of inconsistency.
+
+5. **Execution slugs instead of UUIDs.** Old used `{verb-noun-hash}`
+   slugs, so you could tab-complete or remember them. Our UUIDs are
+   awful to type. Worth considering slug generation on
+   `runtime.start()` — or at least displaying a prefix (`ramure ls`
+   showing first 8 chars, and accepting prefixes when you refer to
+   them).
+
+6. **Streaming semantics in `exec`.** The old `exec` command streamed
+   events to stdout while the run was live. Ours doesn't need a `exec`
+   command since you run Python directly, but: when the user runs
+   `python program.py`, they're staring at whatever the program prints.
+   They may also want the log stream. A `ramure tail <id>` in another
+   terminal covers this. Separate concerns, not the same tool.
+
+## Revised plan
+
+Given what I saw in the old CLI, the minimal useful surface is:
+
+```
+ramure ls                                  list live runtimes
+ramure status [<id>]                       show execution metadata (agents, etc.)
+ramure tail  [<id>] [--agent X] [-n N]     stream or recent events
+ramure send  [<id>] [--agent X] <message>  inject a message
+ramure stop  [<id>]                        stop a run (soft: emit runtime-shutdown; fallback SIGTERM)
+```
+
+Plus:
+- `[<id>]` accepts prefixes (`ramure tail a3f1`).
+- `[<id>]` is optional when only one runtime is live.
+- `--agent` defaults to the only agent, or errors with list.
+- Event formatting lives in a `ramure/display.py` that's imported by
+  `tail` and `status`.
+- Logs go to `~/.ramure/logs/{execution_id}/*.jsonl` by default (same
+  base as the socket, so discovery is symmetrical).
+
+The transport question: **let's do registry + loopback WebSocket, not
+Unix socket.** Reason: the server already speaks WS, adding Unix would
+mean a second dispatcher. Registry file at
+`~/.ramure/runtimes/{execution_id}.json` has
+`{pid, server_url, program, started_at}`. CLI reads it. On `close`,
+delete it. On startup, scan for stale entries and clean them up.
+
+Slight downside vs. Unix sockets: a stale JSON is harder to detect than
+a stale socket (you need to check the pid). But you'd check the pid
+anyway for `stop`, so the code is there.
+
+## Suggested build order
+
+1. **Registry file** (`runtime.py`): write on start, delete on close.
+   ~15 lines.
+2. **Default `log_dir`** to `~/.ramure/logs/` if not set. ~3 lines.
+3. **`ramure/display.py`**: `format_event(entry) -> str | None`. Moved
+   or copied from old CLI if patterns match, rewritten if not.
+4. **`ramure/cli.py`**: Typer (or argparse — Typer is fine, small dep)
+   with `ls`, `status`, `tail`, `send`, `stop`. Uses the registry and
+   the WS protocol.
+5. **Entry point** in `pyproject.toml`: `ramure = "ramure.cli:app"`.
+
+Probably ~300 lines of CLI total, plus ~50 in runtime.py.
+
+how does the loopback websocket work? how does it get all these things we need?