robot_lab 0.1.0 → 0.2.6

data/simple_acp_review.md

@@ -0,0 +1,298 @@
+# Review: `simple_acp` Ruby Library
+
+**Path:** `/Users/dewayne/sandbox/git_repos/madbomber/simple_acp`
+**Version:** 0.0.1
+**Protocol:** ACP (Agent Communication Protocol) — Bee AI community standard, not Google's A2A
+**Reviewed:** 2026-05-05
+
+---
+
+## What It Is
+
+A complete Ruby implementation of ACP — an HTTP+SSE protocol for communication between AI agents, applications, and humans. Provides both a server (Roda/Falcon) and a client (Faraday), with pluggable storage backends, streaming, stateful sessions, and an await/resume pattern for interactive multi-turn flows.
+
+---
+
+## Wire Protocol
+
+| Endpoint | Purpose |
+|---|---|
+| `GET /ping` | Health check |
+| `GET /agents` | List registered agents (params: limit, offset) |
+| `GET /agents/:name` | Agent manifest (capabilities, MIME types) |
+| `POST /runs` | Create a run (body: agent_name, input[], mode, session_id) |
+| `GET /runs/:id` | Run status |
+| `POST /runs/:id` | Resume an awaited run (body: await_resume, mode) |
+| `POST /runs/:id/cancel` | Cancel a run |
+| `GET /runs/:id/events` | Full SSE event history (params: limit, offset) |
+| `GET /session/:id` | Session state and history |
+
+### Run Modes
+
+- `SYNC` — wait for completion, return finished run
+- `ASYNC` — return immediately with run ID, poll for completion
+- `STREAM` — SSE event stream for real-time progress
+
+### Task State Machine
+
+`CREATED → IN_PROGRESS → AWAITING → COMPLETED / FAILED / CANCELLED / CANCELLING`
+
+### Message Format (JSON)
+
+```json
+{
+  "role": "user|agent|agent/name",
+  "parts": [
+    {
+      "name": "optional",
+      "content_type": "text/plain|application/json|image/*",
+      "content": "string or base64",
+      "content_encoding": "plain|base64",
+      "content_url": "https://...",
+      "metadata": { "kind": "citation|trajectory", ... }
+    }
+  ],
+  "created_at": "ISO8601",
+  "completed_at": "ISO8601"
+}
+```
+
+### Run Response (JSON)
+
+```json
+{
+  "run_id": "uuid",
+  "agent_name": "string",
+  "session_id": "uuid|null",
+  "status": "created|in-progress|awaiting|completed|failed|cancelled|cancelling",
+  "output": [{ "role": "agent", "parts": [...] }],
+  "error": { "code": "server_error|invalid_input|not_found", "message": "...", "data": null },
+  "await_request": { "type": "message", "message": { ... } },
+  "created_at": "ISO8601",
+  "finished_at": "ISO8601"
+}
+```
+
+### SSE Event Types (11)
+
+`message.created`, `message.part`, `message.completed`, `run.created`, `run.in_progress`, `run.awaiting`, `run.completed`, `run.cancelled`, `run.failed`, `generic`, `error`
+
+---
+
+## Key Classes and Their Roles
+
+### Server
+
+| Class | Role |
+|---|---|
+| `SimpleAcp::Server::Base` | Main server; registers agents, drives all execution modes |
+| `SimpleAcp::Server::App` | Roda HTTP router — maps endpoints to server methods |
+| `SimpleAcp::Server::Agent` | Wraps handler block; normalizes return types (String/Message/Array/Enumerator → consistent enumerable) |
+| `SimpleAcp::Server::Context` | Passed to handler blocks; provides `await_message`, `cancel!`, `history`, `state`, `log` |
+| `SimpleAcp::Server::FalconRunner` | Fiber-based Falcon server runner |
+
+### Client
+
+| Class | Role |
+|---|---|
+| `SimpleAcp::Client::Base` | Faraday-based; all endpoints as snake_case methods |
+| `SimpleAcp::Client::SSE` | SSE event stream parser (event type + JSON data) |
+
+**Client methods:** `ping`, `agents`, `agent(name)`, `run_sync`, `run_async`, `run_stream`, `run_resume_sync`, `run_resume_stream`, `run_status`, `run_events`, `run_cancel`, `wait_for_run`, `use_session`, `clear_session`, `session(id)`
+
+### Models
+
+| Class | Role |
+|---|---|
+| `SimpleAcp::Models::Message` | Role + array of `MessagePart`s; factory: `Message.user(...)`, `Message.agent(...)` |
+| `SimpleAcp::Models::MessagePart` | Content unit: text, JSON, image, URL; factory: `.text(s)`, `.json(h)`, `.image(data, mime)`, `.from_url(url, ct)` |
+| `SimpleAcp::Models::Run` | Execution lifecycle with state transitions: `start!`, `await!`, `complete!`, `fail!`, `cancel!` |
+| `SimpleAcp::Models::Session` | Conversation history (Message array) + arbitrary state dict; `add_to_history`, `set_state` |
+| `SimpleAcp::Models::AgentManifest` | Discovery: name, description, input/output MIME types, status, metadata |
+| `SimpleAcp::Models::AwaitRequest` | Prompt to display when agent pauses |
+| `SimpleAcp::Models::AwaitResume` | Client's response when resuming a paused run |
+| `SimpleAcp::Models::Events` | SSE event hierarchy (all 11 types); `sse_format` for wire encoding |
+| `SimpleAcp::Models::Error` | Structured error: code, message, data; factory: `.server_error`, `.invalid_input`, `.not_found` |
+| `SimpleAcp::Models::Metadata` | Agent metadata: citations, trajectory, authors, links, dependencies, capabilities |
+
+### Storage (pluggable — duck-typed interface)
+
+| Class | Backend |
+|---|---|
+| `SimpleAcp::Storage::Memory` | `Concurrent::Map` — default, thread-safe |
+| `SimpleAcp::Storage::Redis` | Redis backend |
+| `SimpleAcp::Storage::PostgreSQL` | PostgreSQL via Sequel |
+
+**Interface:** `get_run`, `save_run`, `delete_run`, `list_runs`, `get_session`, `save_session`, `delete_session`, `add_event`, `get_events`, `close`, `ping`
+
+---
+
+## Agent DSL
+
+```ruby
+server = SimpleAcp::Server::Base.new
+
+server.agent("assistant",
+  description: "A helpful assistant",
+  input_content_types: ["text/plain"],
+  output_content_types: ["text/plain"]
+) do |context|
+  input = context.input.text_content
+  result = my_robot.run(input).reply
+  SimpleAcp::Models::Message.agent(result)
+end
+
+server.run(port: 9292)
+```
+
+### Streaming Agent
+
+```ruby
+server.agent("streamer", description: "Streams responses") do |context|
+  Enumerator.new do |yielder|
+    my_robot.run(context.input.text_content) do |chunk|
+      yielder << SimpleAcp::Models::MessagePart.text(chunk.content)
+    end
+  end
+end
+```
+
+### Await/Resume Agent (interactive)
+
+```ruby
+server.agent("interactive", description: "Asks for clarification") do |context|
+  clarification = context.await_message("Please clarify your intent:")
+  answer = clarification.text_content
+  result = my_robot.run("#{context.input.text_content} (clarification: #{answer})").reply
+  SimpleAcp::Models::Message.agent(result)
+end
+```
+
+### Client Usage
+
+```ruby
+client = SimpleAcp::Client::Base.new("http://localhost:9292")
+
+# Synchronous
+run = client.run_sync("assistant", input: "Hello")
+puts run.output.first.text_content
+
+# Streaming
+client.run_stream("streamer", input: "Tell me a story") do |event|
+  print event.part.content if event.is_a?(SimpleAcp::Models::Events::MessagePartEvent)
+end
+
+# Async with polling
+run = client.run_async("assistant", input: "Long task")
+completed = client.wait_for_run(run.run_id, timeout: 60)
+```
+
+---
+
+## Dependencies
+
+**Runtime:**
+- `roda (~> 3.0)` — Rack web framework
+- `falcon (~> 0.47)` — Fiber-based async HTTP server
+- `async (~> 2.0)` — Async I/O primitives
+- `async-http (~> 0.66)` — Async HTTP adapter
+- `faraday (~> 2.0)` — HTTP client
+- `concurrent-ruby (~> 1.2)` — Thread-safe data structures
+- `json_schemer (~> 2.0)` — JSON schema validation
+- `base64`, `uri` — stdlib backports for Ruby 3.4+
+
+**Optional storage:**
+- `redis (~> 5.0)`, `pg (~> 1.5)`, `sequel (~> 5.0)`
+
+**Development:**
+- `minitest (~> 5.0)`, `minitest-reporters`, `rack-test (~> 2.0)`, `webmock (~> 3.0)`
+- `rubocop (~> 1.0)`, `rake`, `bundler`, `debug_me`, `aigcm`
+
+---
+
+## Comparison: `simple_acp` vs. `agent2agent` (GIS gem)
+
+| Feature | `simple_acp` (yours) | `agent2agent` (GIS) |
+|---|---|---|
+| **Protocol** | ACP (Bee AI community) | A2A (Google) |
+| **Await/Resume** | First-class — agents pause, client resumes | `INPUT_REQUIRED` state only |
+| **Session state** | Arbitrary state dict + full history | Task-scoped only |
+| **Storage backends** | Memory, Redis, PostgreSQL | Memory, SQLite |
+| **HTTP framework** | Roda + Falcon | Pure Rack + Falcon |
+| **Client** | Faraday-based, full API surface | `async-http`, fiber-only |
+| **Content types** | Multimodal: text, JSON, image, URL refs | Text/JSON focused |
+| **Agent DSL** | Block-based, normalized return types | Block-based |
+| **Tests** | Minitest in `test/` | `scampi` inline |
+| **Proto/Schema** | JSON Schema via `json_schemer` | `.proto` file + 47-type JSON schema |
+
+---
+
+## Applicability to RobotLab
+
+### High Value — Natural Fit
+
+**Robot-as-ACP-Agent:**
+Each `Robot` maps directly to an ACP agent registration:
+
+```ruby
+server.agent(robot.name, description: robot.description) do |context|
+  result = robot.run(context.input.text_content)
+  SimpleAcp::Models::Message.agent(result.reply)
+end
+```
+
+**Streaming robot output:**
+`run_stream` + SSE `message.part` events maps onto RubyLLM's streaming callbacks — emit one `MessagePartEvent` per chunk. Real-time progress for free.
+
+**Await/Resume ↔ AskUser:**
+`ctx.await_message(prompt)` / `ctx.resume_message` is a network-protocol equivalent of RobotLab's `AskUser` tool. Exposes interactive robot flows to web and API clients without a terminal dependency. This is the most direct protocol-level replacement for `AskUser`.
+
+**Session ↔ Memory:**
+`Session#state` (arbitrary dict) mirrors `Memory#data` (StateProxy). `Session#history` mirrors `Memory#messages`. A thin bridge adapter could keep them in sync, giving RobotLab robots persistent cross-request state without Redis.
+
+**Async runs ↔ background jobs:**
+`run_async` returns a run ID immediately; `wait_for_run` polls. Maps cleanly onto `RobotLab::Job` (ActiveJob) — the job creates the run, Turbo Streams broadcast `message.part` events as SSE.
+
+**Network-as-single-agent:**
+Expose an entire `Network` pipeline as one ACP agent — clients send one message, the network orchestrates internally across all robots, the final result comes back as one response. Callers don't need to know the internal topology.
+
+**PostgreSQL storage:**
+`SimpleAcp::Storage::PostgreSQL` aligns with RobotLab's Rails integration and existing ActiveRecord setup. No new infrastructure required.
+
+**Multimodal inputs:**
+`MessagePart` supports images, JSON blobs, and URL references out of the box — richer than plain text, useful for vision-capable robots or structured-data workflows.
+
+### Integration Pattern
+
+```ruby
+# Expose a RobotLab Network as an ACP server
+network = RobotLab.create_network(name: "support") { ... }
+
+server = SimpleAcp::Server::Base.new(
+  storage: SimpleAcp::Storage::PostgreSQL.new(db_url)
+)
+
+server.agent("support",
+  description: "Multi-robot support pipeline",
+  input_content_types: ["text/plain"],
+  output_content_types: ["text/plain"]
+) do |context|
+  memory = RobotLab.create_memory(
+    data: { session_id: context.session_id }
+  )
+  result = network.run(message: context.input.text_content, memory: memory)
+  SimpleAcp::Models::Message.agent(result.reply)
+end
+```
+
+---
+
+## Bottom Line
+
+`simple_acp` is a cleaner fit for RobotLab than the `agent2agent` gem for three reasons:
+
+1. **Await/resume directly replaces `AskUser`'s terminal dependency** with a proper HTTP protocol state — robots can request human input without blocking a terminal session
+2. **PostgreSQL backend** aligns with the existing Rails integration — no SQLite impedance mismatch
+3. **Multimodal message parts** (image, JSON, URL) give RobotLab robots richer input/output than plain text
+
+The most impactful integration would be a `RobotLab::ACPServer` adapter class that wraps any `Robot` or `Network` as an ACP agent, mapping `AskUser` calls to `await_message`, streaming callbacks to `message.part` events, and `RobotResult` to a completed `Message`.

data/temp.md

@@ -0,0 +1,6 @@
+
+You: /llms gpt-5 openai
+
+You: /llms gpt-5 openai 5.4
+
+You: /llms gpt-5 openai 5.4 -openrouter

data/tool_manifest_plan.md

@@ -0,0 +1,155 @@
+# ToolManifest Evolution Plan
+
+## Concept: Dynamic Tool Selection in Pipelines
+
+There is a pattern where the total number of tools available within RobotLab numbers in the hundreds -- too many to send to any single LLM call. A pipeline uses a "selector" robot that reviews the next robot's prompt and determines which tools should be made available. The selected subset is then applied to the target robot via `with_tools(...)`.
+
+### Example Flow
+
+```
+Selector Robot (step 1)
+  - Receives the user prompt destined for step 2
+  - Has access to a summary of all available tools (name + description)
+  - Outputs a list of tool names relevant to the task
+
+Target Robot (step 2)
+  - Receives the selected tools via with_tools(...)
+  - Runs with only the relevant subset (e.g., 5-10 tools instead of hundreds)
+```
+
+## Current State
+
+`ToolManifest` (lib/robot_lab/tool_manifest.rb, 218 lines) is a name-keyed Hash wrapper with:
+- Lookup by name (`[]`, `fetch`)
+- `Enumerable` support
+- Merge/replace operations
+- Serialization (`to_h`, `to_json`, `from_hash`)
+
+It is not currently used by any production code path. `Robot` stores tools as plain arrays (`@local_tools`, `@mcp_tools`) and `all_tools` concatenates them.
+
+## What It Needs to Become
+
+### 1. Global Registry Entry Point
+
+A singleton or module-level registry where all available tools accumulate:
+
+```ruby
+RobotLab.tool_registry  # => ToolManifest (global instance)
+RobotLab.tool_registry.add(MyTool)
+RobotLab.tool_registry.names  # => ["my_tool", "weather", "calculator", ...]
+```
+
+### 2. Metadata for Selection
+
+Categories, tags, or other metadata so the selector robot can reason about which tools are relevant without seeing full schemas:
+
+```ruby
+# Registration with metadata
+RobotLab.tool_registry.add(MyTool, tags: [:database, :read_only])
+
+# Filtering
+RobotLab.tool_registry.tagged(:database)  # => subset manifest
+```
+
+### 3. Search-Friendly Summary Output
+
+The selector robot needs a compact summary it can reason over -- name + description pairs, not full JSON schemas:
+
+```ruby
+RobotLab.tool_registry.summary
+# => [{ name: "get_weather", description: "Get current weather for a location" },
+#     { name: "calculate", description: "Performs basic arithmetic" }, ...]
+```
+
+### 4. Subset Extraction by Name
+
+Resolve a list of tool names (the selector robot's output) into actual tool objects:
+
+```ruby
+names = ["get_weather", "calculate"]  # from selector robot
+tools = RobotLab.tool_registry.select_by_names(names)
+target_robot.with_tools(tools)
+```
+
+### 5. Integration with Robot
+
+`Robot#all_tools` and `with_tools(...)` should accept a ToolManifest or be able to pull from the global registry.
+
+## Design Decisions Still Needed
+
+- Should MCP-discovered tools auto-register in the global manifest?
+- How does the selector robot receive the tool summary -- as part of its system prompt, injected into the user message, or via a tool call?
+- Should categories/tags be defined on the Tool class itself (e.g., `Tool.create(name: ..., tags: [...])`), or only at registration time?
+- Does the manifest need versioning or hot-reload support for long-running processes?
+
+---
+
+## Review Notes
+
+### The Problem Statement is Strong
+
+The "selector robot" pattern — an LLM choosing tools from hundreds based on a compact summary — is a real need. Sending 200+ tool schemas in every API call is both expensive and degrades LLM accuracy. The plan correctly identifies that `ToolManifest` as it exists today is a passive container that nothing actually uses.
+
+### What's Solid
+
+- **Global registry** (section 1) — The right call. Tools currently scatter across `@local_tools` and `@mcp_tools` per-robot with no central view. `RobotLab.tool_registry` is the obvious home.
+- **Summary output** (section 3) — Essential for the selector pattern. Name + description pairs are the right granularity for LLM reasoning.
+- **Subset extraction** (section 4) — `select_by_names` maps cleanly to what `ToolConfig.filter_tools` already does, but at the registry level.
+
+### Gaps and Concerns
+
+**1. Tags/metadata may be premature.**
+
+Section 2 proposes tags (`tags: [:database, :read_only]`) and `.tagged(:database)` filtering. This adds a classification system that someone has to maintain. In the selector-robot pattern, the LLM is doing the classification — that's the whole point. If you also hand-tag tools, you're duplicating the selector's job.
+
+A simpler alternative: let `summary` be the only interface the selector sees. If you later want pre-filtering (e.g., "only show the selector database-related tools"), add it then. Right now it's YAGNI.
+
+**2. MCP tool auto-registration is the key decision, not a footnote.**
+
+The plan lists "Should MCP-discovered tools auto-register in the global manifest?" as an open question. This is actually the central architectural decision. Looking at `MCPManagement#discover_mcp_tools`, MCP tools are created dynamically per-robot, per-connection. They hold closures over their specific `mcp_client` instance. If you auto-register them globally, you need to handle:
+
+- **Lifecycle** — MCP tools are only valid while their client is connected. The global registry would hold dead references after `disconnect`.
+- **Duplicates** — Two robots connecting to the same MCP server would register the same tool names with different client closures.
+- **Scope** — An MCP tool created for robot A shouldn't be callable by robot B unless they share the client.
+
+Suggestion: MCP tools should **not** auto-register. The global registry should hold "tool definitions" (name, description, schema) — not live callable instances. The selector robot picks names; the target robot resolves those names against its own live tools.
+
+**3. The plan doesn't address the split between "tool definition" and "tool instance."**
+
+Currently `Tool` is both the definition (name, description, parameters) and the callable (the `execute` method with its closure). For a global registry, you want the definition without the closure. The selector robot doesn't need to call tools — it just needs to read summaries and output names.
+
+This suggests `ToolManifest` should store lightweight descriptors, and `Robot#filtered_tools` continues resolving names to live instances from `all_tools`.
+
+**4. Integration with `Robot#with_tools` needs more thought.**
+
+The plan says "`with_tools(...)` should accept a ToolManifest." But `with_tools` currently delegates to `@chat.with_tools` from RubyLLM, which expects tool class/instance objects. Accepting a manifest means either:
+
+- Converting manifest entries back to tool instances (requires the live tool lookup), or
+- Passing tool names and letting the robot resolve internally (which is what `filtered_tools` already does)
+
+The second path is simpler and already mostly works. The plan could just say: "The selector robot outputs tool names. Pass them to `robot.run(..., tools: names)`." That's the existing `tools:` parameter.
+
+**5. Missing: how the selector robot itself gets built.**
+
+The plan describes the pattern but not the API. Is this a special network task type? A built-in robot template? A method on `ToolManifest`? Something like:
+
+```ruby
+network = RobotLab.create_network(name: "smart_pipeline") do
+  task :selector, selector_robot, depends_on: :none
+  task :worker, worker_robot, tools: :from_selector, depends_on: [:selector]
+end
+```
+
+The `tools: :from_selector` (or similar) is the glue that needs designing.
+
+### Suggested Simplification
+
+Instead of evolving ToolManifest into a full registry with tags, a narrower v1:
+
+1. **`RobotLab.tool_registry`** — Global `ToolManifest` that accumulates tool descriptors (name + description only, no live instances)
+2. **`ToolManifest#summary`** — Returns the compact format for selector prompts
+3. **`ToolManifest#select_by_names(names)`** — Returns a sub-manifest (already close to what exists)
+4. **Auto-registration of local tools at `Robot.new`** — Push descriptors into the registry when robots are created
+5. **No auto-registration of MCP tools** — Too coupled to connection lifecycle
+
+Skip tags, skip `with_tools(manifest)` integration, skip hot-reload. Those can come later if needed.