robot_lab 0.0.1 → 0.0.4

data/docs/guides/creating-networks.md

@@ -38,6 +38,20 @@ network = RobotLab.create_network(name: "parallel", concurrency: :threads) do
 end
 ```
 
+### Shared Memory
+
+Networks provide a shared memory accessible to all robots:
+
+```ruby
+network = RobotLab.create_network(name: "pipeline") do
+  task :first, robot1, depends_on: :none
+end
+
+# Pre-populate shared memory
+network.memory[:project] = "Q4 Report"
+network.memory[:user_id] = 123
+```
+
 ## Adding Tasks
 
 ### Sequential Tasks
@@ -72,7 +86,7 @@ end
 
 ### Optional Tasks
 
-Optional tasks only run when explicitly activated:
+Optional tasks only run when explicitly activated by a preceding robot:
 
 ```ruby
 network = RobotLab.create_network(name: "router") do
@@ -85,7 +99,7 @@ end
 
 ## Per-Task Configuration
 
-Tasks can have individual context and configuration that's deep-merged with the network's run parameters:
+Tasks can have individual context and configuration that is deep-merged with the network's run parameters:
 
 ```ruby
 network = RobotLab.create_network(name: "support") do
@@ -105,8 +119,8 @@ end
 | Option | Description |
 |--------|-------------|
 | `context` | Hash merged with run params (task values override) |
-| `mcp` | MCP servers for this task |
-| `tools` | Tools available to this task |
+| `mcp` | MCP servers for this task (`:none`, `:inherit`, or array) |
+| `tools` | Tools available to this task (`:none`, `:inherit`, or array) |
 | `memory` | Task-specific memory |
 | `depends_on` | `:none`, `[:task1]`, or `:optional` |
 
@@ -117,7 +131,9 @@ Use optional tasks with custom Robot subclasses for intelligent routing:
 ```ruby
 class ClassifierRobot < RobotLab::Robot
   def call(result)
-    robot_result = run(**extract_run_context(result))
+    context = extract_run_context(result)
+    message = context.delete(:message)
+    robot_result = run(message, **context)
 
     new_result = result
       .with_context(@name.to_sym, robot_result)
@@ -194,6 +210,25 @@ result.halted?    # Whether execution was halted early
 result.continued? # Whether execution continued normally
 ```
 
+## Broadcasting
+
+Networks support a broadcast channel for network-wide announcements:
+
+```ruby
+# Register a broadcast handler
+network.on_broadcast do |message|
+  case message[:payload][:event]
+  when :pause
+    puts "Pausing: #{message[:payload][:reason]}"
+  when :phase_complete
+    puts "Phase complete: #{message[:payload][:phase]}"
+  end
+end
+
+# Send broadcasts during execution
+network.broadcast(event: :phase_complete, phase: "analysis")
+```
+
 ## Patterns
 
 ### Classifier Pattern
@@ -203,7 +238,10 @@ Route to specialists based on classification:
 ```ruby
 class SupportClassifier < RobotLab::Robot
   def call(result)
-    robot_result = run(**extract_run_context(result))
+    context = extract_run_context(result)
+    message = context.delete(:message)
+    robot_result = run(message, **context)
+
     new_result = result
       .with_context(@name.to_sym, robot_result)
       .continue(robot_result)
@@ -259,7 +297,9 @@ A robot can halt execution early:
 ```ruby
 class ValidatorRobot < RobotLab::Robot
   def call(result)
-    robot_result = run(**extract_run_context(result))
+    context = extract_run_context(result)
+    message = context.delete(:message)
+    robot_result = run(message, **context)
 
     if robot_result.last_text_content.include?("INVALID")
       # Stop the pipeline
@@ -274,6 +314,30 @@ class ValidatorRobot < RobotLab::Robot
 end
 ```
 
+### Data Passing Between Tasks
+
+Access previous task results via context:
+
+```ruby
+class ResponderRobot < RobotLab::Robot
+  def call(result)
+    # Get classifier's output
+    classification = result.context[:classifier]&.last_text_content
+
+    context = extract_run_context(result)
+    message = context.delete(:message)
+
+    # Use classification in the message or context
+    robot_result = run(
+      "Classification: #{classification}\n\nUser message: #{message}",
+      **context
+    )
+
+    result.with_context(@name.to_sym, robot_result).continue(robot_result)
+  end
+end
+```
+
 ## Visualization
 
 ### ASCII Visualization
@@ -290,6 +354,13 @@ puts network.to_mermaid
 # => Mermaid graph definition
 ```
 
+### DOT Format (Graphviz)
+
+```ruby
+puts network.to_dot
+# => Graphviz DOT format
+```
+
 ### Execution Plan
 
 ```ruby
@@ -305,6 +376,7 @@ network.robots            # => Hash of name => Robot
 network.robot(:billing)   # => Robot instance
 network["billing"]        # => Robot instance (alias)
 network.available_robots  # => Array of Robot instances
+network.memory            # => Memory instance (shared)
 network.to_h              # => Hash representation
 ```
 
@@ -323,25 +395,14 @@ task :respond, responder, depends_on: [:classify]
 task :do_everything, mega_robot, depends_on: :none
 ```
 
-### 2. Use Context for Data Passing
+### 2. Use Per-Task Context
 
-Access previous results via context:
+Pass task-specific configuration through context:
 
 ```ruby
-class ResponderRobot < RobotLab::Robot
-  def call(result)
-    # Get classifier's output
-    classification = result.context[:classifier]&.last_text_content
-
-    # Use it in this robot's run
-    robot_result = run(
-      **extract_run_context(result),
-      classification: classification
-    )
-
-    result.with_context(@name.to_sym, robot_result).continue(robot_result)
-  end
-end
+task :billing, billing_robot,
+     context: { department: "billing", max_refund: 500 },
+     depends_on: :optional
 ```
 
 ### 3. Handle Missing Results
@@ -359,8 +420,17 @@ def call(result)
 end
 ```
 
+### 4. Reset Memory Between Runs
+
+If reusing a network, reset shared memory between runs:
+
+```ruby
+network.reset_memory
+result = network.run(message: "New request")
+```
+
 ## Next Steps
 
 - [Using Tools](using-tools.md) - Add capabilities to robots
-- [Memory Guide](memory.md) - Persistent memory across runs
+- [Memory Guide](memory.md) - Shared memory patterns
 - [API Reference: Network](../api/core/network.md) - Complete API

data/docs/guides/mcp-integration.md

@@ -12,13 +12,15 @@ MCP is a protocol that allows LLM applications to connect to external servers th
 
 ## Configuring MCP Servers
 
-### At Network Level
+### At Robot Level
 
-```ruby
-network = RobotLab.create_network do
-  name "dev_assistant"
+Use the `mcp:` parameter on `RobotLab.build` to connect a robot to MCP servers:
 
-  mcp [
+```ruby
+robot = RobotLab.build(
+  name: "coder",
+  template: :developer,
+  mcp: [
     {
       name: "filesystem",
       transport: {
@@ -31,40 +33,72 @@ network = RobotLab.create_network do
       name: "github",
       transport: {
         type: "stdio",
-        command: "mcp-server-github"
+        command: "mcp-server-github",
+        env: { "GITHUB_TOKEN" => ENV["GITHUB_TOKEN"] }
       }
     }
   ]
-end
+)
 ```
 
-### At Robot Level
+### In Template Front Matter
+
+MCP servers can be declared directly in a template's YAML front matter, making the template fully self-contained:
+
+```markdown title="prompts/github_assistant.md"
+---
+description: GitHub assistant with MCP tool access
+mcp:
+  - name: github
+    transport: stdio
+    command: npx
+    args: ["-y", "@modelcontextprotocol/server-github"]
+---
+You are a helpful GitHub assistant with access to GitHub tools via MCP.
+```
 
 ```ruby
-robot = RobotLab.build do
-  name "coder"
+# MCP config comes from the template — no mcp: parameter needed
+robot = RobotLab.build(template: :github_assistant)
+```
 
-  # Use network's MCP servers
-  mcp :inherit
+Constructor `mcp:` overrides frontmatter `mcp:` when provided.
 
-  # Or specific servers
-  mcp [
-    { name: "filesystem", transport: { type: "stdio", command: "mcp-fs" } }
-  ]
+### Hierarchical Configuration
 
-  # Or disable MCP
-  mcp :none
-end
-```
+The `mcp:` parameter supports three modes:
 
-### Global Configuration
+| Value | Behavior |
+|-------|----------|
+| `:none` | No MCP servers (default) |
+| `:inherit` | Inherit from network or global config |
+| `[...]` | Explicit array of server configurations |
 
 ```ruby
-RobotLab.configure do |config|
-  config.mcp = [
-    { name: "common_tools", transport: { type: "stdio", command: "common-mcp" } }
-  ]
-end
+# Inherit from network/config
+robot = RobotLab.build(
+  name: "reader",
+  system_prompt: "You help read files.",
+  mcp: :inherit
+)
+
+# Disable MCP explicitly
+robot = RobotLab.build(
+  name: "calculator",
+  system_prompt: "You do math.",
+  mcp: :none
+)
+```
+
+### Resolution Order
+
+MCP configuration resolves through a hierarchy: **runtime > robot build > network > global config**. Each level can override the previous:
+
+```
+Global (RobotLab.config.mcp)
+  -> Network (task mcp: [...])
+    -> Robot (mcp: :inherit | :none | [...])
+      -> Runtime (robot.run("msg", mcp: [...]))
 ```
 
 ## Transport Types
@@ -134,68 +168,54 @@ Streamable HTTP transport with session support:
 
 ## Using MCP Tools
 
-Once configured, MCP tools are automatically available to robots:
+Once configured, MCP tools are automatically discovered and made available to the robot. The robot connects to MCP servers on its first `run` call and discovers tools dynamically:
 
 ```ruby
-network = RobotLab.create_network do
-  mcp [
+robot = RobotLab.build(
+  name: "helper",
+  system_prompt: <<~PROMPT
+    You can help users with GitHub tasks.
+    Use available tools to search repositories, create issues, etc.
+  PROMPT,
+  mcp: [
     { name: "github", transport: { type: "stdio", command: "mcp-server-github" } }
   ]
+)
 
-  add_robot RobotLab.build {
-    name "helper"
-    template <<~PROMPT
-      You can help users with GitHub tasks.
-      Use available tools to search repositories, create issues, etc.
-    PROMPT
-  }
-end
-
-# The robot can now use GitHub MCP tools
-state = RobotLab.create_state(message: "Find repositories about machine learning")
-network.run(state: state)
+# MCP tools are automatically available
+result = robot.run("Find repositories about machine learning")
+puts result.last_text_content
 ```
 
 ## Filtering MCP Tools
 
-Restrict which MCP tools are available:
+Use the `tools:` parameter to restrict which tools (including MCP-discovered tools) are available to a robot:
 
 ```ruby
-robot = RobotLab.build do
-  name "reader"
-  mcp :inherit
-
-  # Only allow specific MCP tools
-  tools %w[read_file search_code list_directory]
-end
-```
-
-## MCP Server Configuration
-
-### Server Object
-
-```ruby
-server = RobotLab::MCP::Server.new(
-  name: "my_server",
-  transport: {
-    type: "stdio",
-    command: "my-mcp-server"
-  }
+robot = RobotLab.build(
+  name: "reader",
+  system_prompt: "You help read and search files.",
+  mcp: [
+    { name: "filesystem", transport: { type: "stdio", command: "mcp-server-fs" } }
+  ],
+  tools: %w[read_file search_files list_directory]  # Only allow specific tools
 )
-
-server.name           # => "my_server"
-server.transport_type # => "stdio"
-server.to_h           # Hash representation
 ```
 
-### Client Object
+## MCP in Networks
 
-```ruby
-client = RobotLab::MCP::Client.new(server: server)
-client.connect
+When running robots in a network, use per-task MCP configuration:
 
-client.connected?     # => true
-client.to_h           # Client info
+```ruby
+network = RobotLab.create_network(name: "dev_pipeline") do
+  task :planner, planner_robot, depends_on: :none
+  task :coder, coder_robot,
+       mcp: [
+         { name: "filesystem", transport: { type: "stdio", command: "mcp-server-fs" } }
+       ],
+       depends_on: [:planner]
+  task :reviewer, reviewer_robot, depends_on: [:coder]
+end
 ```
 
 ## Common MCP Servers
@@ -245,54 +265,70 @@ Tools: `search_repositories`, `create_issue`, `get_file_contents`, etc.
 
 Tools: `query`, `list_tables`, `describe_table`
 
+## MCP Server and Client Objects
+
+For programmatic access, you can work with MCP objects directly:
+
+```ruby
+# Server configuration
+server = RobotLab::MCP::Server.new(
+  name: "my_server",
+  transport: {
+    type: "stdio",
+    command: "my-mcp-server"
+  }
+)
+
+# Client connection
+client = RobotLab::MCP::Client.new(server)
+client.connect
+
+client.connected?           # => true
+client.list_tools           # => Array of tool definitions
+client.call_tool("search", { query: "ruby" })
+client.list_resources       # => Array of resource definitions
+client.disconnect
+```
+
 ## Error Handling
 
 ### Connection Errors
 
 ```ruby
 begin
-  network.run(state: state)
+  result = robot.run("Search for repos")
 rescue RobotLab::MCPError => e
   puts "MCP Error: #{e.message}"
-  # Handle gracefully
 end
 ```
 
-### Missing Dependencies
-
-```ruby
-# If async-websocket not installed
-rescue RobotLab::MCPError => e
-  if e.message.include?("async-websocket")
-    puts "Install async-websocket gem for WebSocket support"
-  end
-end
-```
+!!! tip
+    MCP connection failures are logged as warnings but do not raise errors by default. The robot will continue without MCP tools if a server is unreachable.
 
 ## Disconnecting
 
-Robots automatically disconnect from MCP servers when done:
+Robots can be manually disconnected from MCP servers:
 
 ```ruby
-robot.disconnect  # Manually disconnect
+robot.disconnect  # Disconnect all MCP clients
 ```
 
-Networks handle this automatically at the end of a run.
-
 ## Patterns
 
 ### Development vs Production
 
 ```ruby
-network = RobotLab.create_network do
-  mcp_config = if Rails.env.development?
-    [{ name: "local_fs", transport: { type: "stdio", command: "mcp-fs", args: ["--root", "."] } }]
-  else
-    [{ name: "s3", transport: { type: "stdio", command: "mcp-s3" } }]
-  end
-
-  mcp mcp_config
+mcp_config = if Rails.env.development?
+  [{ name: "local_fs", transport: { type: "stdio", command: "mcp-fs", args: ["--root", "."] } }]
+else
+  [{ name: "s3", transport: { type: "stdio", command: "mcp-s3" } }]
 end
+
+robot = RobotLab.build(
+  name: "file_handler",
+  system_prompt: "You manage files.",
+  mcp: mcp_config
+)
 ```
 
 ### Dynamic Server Selection
@@ -305,9 +341,11 @@ def mcp_servers_for_user(user)
   servers
 end
 
-network = RobotLab.create_network do
-  mcp mcp_servers_for_user(current_user)
-end
+robot = RobotLab.build(
+  name: "assistant",
+  system_prompt: "You help the user with connected services.",
+  mcp: mcp_servers_for_user(current_user)
+)
 ```
 
 ## Best Practices
@@ -330,24 +368,25 @@ end
 
 ### 2. Limit Tool Access
 
+Restrict which MCP tools are available to a robot using the `tools:` parameter:
+
 ```ruby
-# Don't expose all tools
-robot = RobotLab.build do
-  mcp :inherit
-  tools %w[read_file search_files]  # No write access
-end
+robot = RobotLab.build(
+  name: "reader",
+  system_prompt: "You read and search files.",
+  mcp: [{ name: "fs", transport: { type: "stdio", command: "mcp-fs" } }],
+  tools: %w[read_file search_files]  # No write access
+)
 ```
 
-### 3. Handle Disconnections
+### 3. Use Appropriate Transports
 
-```ruby
-begin
-  result = network.run(state: state)
-rescue RobotLab::MCPError
-  # Retry without MCP
-  result = network.run(state: state, mcp: :none)
-end
-```
+| Transport | Best For |
+|-----------|----------|
+| `stdio` | Local servers, CLI tools |
+| `websocket` | Persistent connections, bidirectional |
+| `sse` | Server push, event streams |
+| `streamable_http` | Remote APIs, session-based |
 
 ## Next Steps