robot_lab 0.0.1

data/docs/guides/index.md

@@ -0,0 +1,68 @@
+# Guides
+
+Practical guides for building applications with RobotLab.
+
+## Getting Started
+
+If you're new to RobotLab, start here:
+
+<div class="grid cards" markdown>
+
+-   [:octicons-cpu-24: **Building Robots**](building-robots.md)
+
+    Create specialized AI agents with personalities and tools
+
+-   [:octicons-git-branch-24: **Creating Networks**](creating-networks.md)
+
+    Orchestrate multiple robots for complex workflows
+
+</div>
+
+## Core Features
+
+<div class="grid cards" markdown>
+
+-   [:octicons-tools-24: **Using Tools**](using-tools.md)
+
+    Give robots custom capabilities to interact with external systems
+
+-   [:octicons-server-24: **MCP Integration**](mcp-integration.md)
+
+    Connect to Model Context Protocol servers
+
+-   [:octicons-broadcast-24: **Streaming Responses**](streaming.md)
+
+    Real-time streaming of LLM responses
+
+-   [:octicons-database-24: **Conversation History**](history.md)
+
+    Persist and restore conversation threads
+
+-   [:octicons-cpu-24: **Memory System**](memory.md)
+
+    Share data between robots with the memory system
+
+</div>
+
+## Framework Integration
+
+<div class="grid cards" markdown>
+
+-   [:material-language-ruby:{ .lg } **Rails Integration**](rails-integration.md)
+
+    Use RobotLab in Ruby on Rails applications
+
+</div>
+
+## Guide Index
+
+| Guide | Description | Time |
+|-------|-------------|------|
+| [Building Robots](building-robots.md) | Create and configure robots | 10 min |
+| [Creating Networks](creating-networks.md) | Multi-robot orchestration | 15 min |
+| [Using Tools](using-tools.md) | Add custom capabilities | 10 min |
+| [MCP Integration](mcp-integration.md) | External tool servers | 10 min |
+| [Streaming](streaming.md) | Real-time responses | 5 min |
+| [History](history.md) | Conversation persistence | 10 min |
+| [Memory](memory.md) | Shared data store | 5 min |
+| [Rails Integration](rails-integration.md) | Rails application setup | 15 min |

data/docs/guides/mcp-integration.md

@@ -0,0 +1,356 @@
+# MCP Integration
+
+RobotLab supports the Model Context Protocol (MCP) for connecting to external tool servers.
+
+## What is MCP?
+
+MCP is a protocol that allows LLM applications to connect to external servers that provide tools, resources, and context. This enables:
+
+- Reusable tool servers across applications
+- Separation of tool logic from AI logic
+- Dynamic tool discovery
+
+## Configuring MCP Servers
+
+### At Network Level
+
+```ruby
+network = RobotLab.create_network do
+  name "dev_assistant"
+
+  mcp [
+    {
+      name: "filesystem",
+      transport: {
+        type: "stdio",
+        command: "mcp-server-filesystem",
+        args: ["--root", "/home/user/projects"]
+      }
+    },
+    {
+      name: "github",
+      transport: {
+        type: "stdio",
+        command: "mcp-server-github"
+      }
+    }
+  ]
+end
+```
+
+### At Robot Level
+
+```ruby
+robot = RobotLab.build do
+  name "coder"
+
+  # Use network's MCP servers
+  mcp :inherit
+
+  # Or specific servers
+  mcp [
+    { name: "filesystem", transport: { type: "stdio", command: "mcp-fs" } }
+  ]
+
+  # Or disable MCP
+  mcp :none
+end
+```
+
+### Global Configuration
+
+```ruby
+RobotLab.configure do |config|
+  config.mcp = [
+    { name: "common_tools", transport: { type: "stdio", command: "common-mcp" } }
+  ]
+end
+```
+
+## Transport Types
+
+### Stdio Transport
+
+Communicate via stdin/stdout with a subprocess:
+
+```ruby
+{
+  name: "server_name",
+  transport: {
+    type: "stdio",
+    command: "mcp-server-command",
+    args: ["--option", "value"],
+    env: { "API_KEY" => ENV["API_KEY"] }
+  }
+}
+```
+
+### WebSocket Transport
+
+Connect via WebSocket:
+
+```ruby
+{
+  name: "remote_server",
+  transport: {
+    type: "websocket",
+    url: "ws://localhost:8080/mcp"
+  }
+}
+```
+
+!!! note "Dependency Required"
+    WebSocket transport requires the `async-websocket` gem.
+
+### SSE Transport
+
+Server-Sent Events transport:
+
+```ruby
+{
+  name: "sse_server",
+  transport: {
+    type: "sse",
+    url: "http://localhost:8080/sse"
+  }
+}
+```
+
+### HTTP Transport
+
+Streamable HTTP transport with session support:
+
+```ruby
+{
+  name: "http_server",
+  transport: {
+    type: "streamable_http",
+    url: "https://api.example.com/mcp",
+    session_id: "optional_session_id",
+    auth_provider: -> { "Bearer #{fetch_token}" }
+  }
+}
+```
+
+## Using MCP Tools
+
+Once configured, MCP tools are automatically available to robots:
+
+```ruby
+network = RobotLab.create_network do
+  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)
+```
+
+## Filtering MCP Tools
+
+Restrict which MCP tools are available:
+
+```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"
+  }
+)
+
+server.name           # => "my_server"
+server.transport_type # => "stdio"
+server.to_h           # Hash representation
+```
+
+### Client Object
+
+```ruby
+client = RobotLab::MCP::Client.new(server: server)
+client.connect
+
+client.connected?     # => true
+client.to_h           # Client info
+```
+
+## Common MCP Servers
+
+### Filesystem
+
+```ruby
+{
+  name: "filesystem",
+  transport: {
+    type: "stdio",
+    command: "mcp-server-filesystem",
+    args: ["--root", "/path/to/files"]
+  }
+}
+```
+
+Tools: `read_file`, `write_file`, `list_directory`, `search_files`
+
+### GitHub
+
+```ruby
+{
+  name: "github",
+  transport: {
+    type: "stdio",
+    command: "mcp-server-github",
+    env: { "GITHUB_TOKEN" => ENV["GITHUB_TOKEN"] }
+  }
+}
+```
+
+Tools: `search_repositories`, `create_issue`, `get_file_contents`, etc.
+
+### Database
+
+```ruby
+{
+  name: "postgres",
+  transport: {
+    type: "stdio",
+    command: "mcp-server-postgres",
+    env: { "DATABASE_URL" => ENV["DATABASE_URL"] }
+  }
+}
+```
+
+Tools: `query`, `list_tables`, `describe_table`
+
+## Error Handling
+
+### Connection Errors
+
+```ruby
+begin
+  network.run(state: state)
+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
+```
+
+## Disconnecting
+
+Robots automatically disconnect from MCP servers when done:
+
+```ruby
+robot.disconnect  # Manually disconnect
+```
+
+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
+end
+```
+
+### Dynamic Server Selection
+
+```ruby
+def mcp_servers_for_user(user)
+  servers = []
+  servers << github_server if user.github_connected?
+  servers << slack_server if user.slack_connected?
+  servers
+end
+
+network = RobotLab.create_network do
+  mcp mcp_servers_for_user(current_user)
+end
+```
+
+## Best Practices
+
+### 1. Use Environment Variables for Credentials
+
+```ruby
+{
+  name: "github",
+  transport: {
+    type: "stdio",
+    command: "mcp-server-github",
+    env: {
+      "GITHUB_TOKEN" => ENV["GITHUB_TOKEN"],
+      "GITHUB_ORG" => ENV["GITHUB_ORG"]
+    }
+  }
+}
+```
+
+### 2. Limit Tool Access
+
+```ruby
+# Don't expose all tools
+robot = RobotLab.build do
+  mcp :inherit
+  tools %w[read_file search_files]  # No write access
+end
+```
+
+### 3. Handle Disconnections
+
+```ruby
+begin
+  result = network.run(state: state)
+rescue RobotLab::MCPError
+  # Retry without MCP
+  result = network.run(state: state, mcp: :none)
+end
+```
+
+## Next Steps
+
+- [Using Tools](using-tools.md) - Local tool patterns
+- [Creating Networks](creating-networks.md) - Network configuration
+- [API Reference: MCP](../api/mcp/index.md) - Complete MCP API

data/docs/guides/memory.md

@@ -0,0 +1,309 @@
+# Memory System
+
+The memory system allows robots to share data within a network run.
+
+## Overview
+
+Memory provides:
+
+- Key-value storage accessible by all robots
+- Namespaced scopes for organization
+- Persistence within a single network run
+
+## Basic Usage
+
+### Store Values
+
+```ruby
+state.memory.remember("user_name", "Alice")
+state.memory.remember("preferences", { theme: "dark", language: "en" })
+```
+
+### Retrieve Values
+
+```ruby
+name = state.memory.recall("user_name")  # => "Alice"
+prefs = state.memory.recall("preferences")  # => { theme: "dark", ... }
+
+# Returns nil if not found
+missing = state.memory.recall("unknown")  # => nil
+```
+
+### Check Existence
+
+```ruby
+state.memory.exists?("user_name")  # => true
+state.memory.exists?("unknown")    # => false
+```
+
+### Remove Values
+
+```ruby
+state.memory.forget("user_name")
+```
+
+## Scoped Memory
+
+Organize data with namespaces:
+
+```ruby
+# Create a scoped view
+user_memory = state.memory.scoped("user:123")
+
+# Operations are scoped
+user_memory.remember("name", "Alice")
+user_memory.remember("email", "alice@example.com")
+
+# Keys are prefixed
+state.memory.recall("user:123:name")  # => "Alice"
+
+# Scoped recall
+user_memory.recall("name")  # => "Alice"
+```
+
+### Nested Scopes
+
+```ruby
+session = state.memory.scoped("session:abc")
+prefs = session.scoped("preferences")
+
+prefs.remember("theme", "dark")
+# Full key: "session:abc:preferences:theme"
+```
+
+## Memory Operations
+
+### List All Keys
+
+```ruby
+state.memory.all
+# => {
+#   "user_name" => "Alice",
+#   "user:123:email" => "alice@example.com",
+#   ...
+# }
+```
+
+### List Namespaces
+
+```ruby
+state.memory.namespaces
+# => ["user:123", "session:abc", ...]
+```
+
+### Search by Pattern
+
+```ruby
+# Find keys matching pattern
+matches = state.memory.search("user:*")
+# => { "user:123:name" => "Alice", "user:123:email" => "..." }
+```
+
+### Statistics
+
+```ruby
+state.memory.stats
+# => { total_keys: 15, namespaces: ["user:123", "session"] }
+```
+
+### Clear Memory
+
+```ruby
+# Clear a namespace
+state.memory.scoped("temp").clear
+
+# Clear all memory
+state.memory.clear_all
+```
+
+## Shared Namespace
+
+The `SHARED` namespace is a convention for cross-robot data:
+
+```ruby
+# In first robot
+state.memory.remember("SHARED:context", important_data)
+
+# In later robot
+context = state.memory.recall("SHARED:context")
+```
+
+### Using Shared Scope
+
+```ruby
+shared = state.memory.scoped(RobotLab::Memory::SHARED_NAMESPACE)
+shared.remember("workflow_status", "in_progress")
+```
+
+## In Tool Handlers
+
+Access memory from tools:
+
+```ruby
+tool :update_preference do
+  description "Update user preference"
+  parameter :key, type: :string, required: true
+  parameter :value, type: :string, required: true
+
+  handler do |key:, value:, state:, **_|
+    prefs = state.memory.scoped("preferences")
+    prefs.remember(key, value)
+    { success: true, key: key, value: value }
+  end
+end
+```
+
+## In Routers
+
+Use memory for routing decisions:
+
+```ruby
+router = ->(args) {
+  case args.call_count
+  when 0
+    :classifier
+  when 1
+    # Read classification from memory
+    intent = args.network.state.memory.recall("SHARED:intent")
+    case intent
+    when "billing" then :billing_agent
+    when "technical" then :tech_agent
+    else :general_agent
+    end
+  else
+    nil
+  end
+}
+```
+
+## Patterns
+
+### Accumulating Data
+
+```ruby
+# In each robot
+def add_finding(state, finding)
+  findings = state.memory.recall("findings") || []
+  findings << finding
+  state.memory.remember("findings", findings)
+end
+
+# In final robot
+all_findings = state.memory.recall("findings")
+```
+
+### Tracking Progress
+
+```ruby
+# Track workflow stages
+state.memory.remember("stage", "intake")
+# ... processing ...
+state.memory.remember("stage", "analysis")
+# ... processing ...
+state.memory.remember("stage", "response")
+```
+
+### Caching Expensive Operations
+
+```ruby
+tool :fetch_user do
+  handler do |user_id:, state:, **_|
+    cache_key = "cache:user:#{user_id}"
+
+    # Check cache
+    cached = state.memory.recall(cache_key)
+    return cached if cached
+
+    # Fetch and cache
+    user = User.find(user_id).to_h
+    state.memory.remember(cache_key, user)
+    user
+  end
+end
+```
+
+### User Session Data
+
+```ruby
+# Store session data
+session = state.memory.scoped("session:#{session_id}")
+session.remember("started_at", Time.now.iso8601)
+session.remember("page_views", 0)
+
+# Update during conversation
+views = session.recall("page_views") || 0
+session.remember("page_views", views + 1)
+```
+
+## Memory vs State.data
+
+| Feature | Memory | State.data |
+|---------|--------|------------|
+| Purpose | Robot-to-robot sharing | Input/output data |
+| Scope | Namespaced | Flat hash |
+| Typical Use | Intermediate results | User input, workflow config |
+| Persistence | Within run | Can be serialized |
+
+```ruby
+# Use state.data for input configuration
+state = RobotLab.create_state(
+  message: "Process order",
+  data: { order_id: "123", priority: "high" }
+)
+
+# Use memory for intermediate findings
+state.memory.remember("validation_result", { valid: true })
+state.memory.remember("processing_steps", ["validated", "charged"])
+```
+
+## Best Practices
+
+### 1. Use Descriptive Keys
+
+```ruby
+# Good
+state.memory.remember("classification:intent", "billing")
+state.memory.remember("user:123:last_order_id", "ord_456")
+
+# Bad
+state.memory.remember("x", "billing")
+state.memory.remember("temp1", "ord_456")
+```
+
+### 2. Scope Related Data
+
+```ruby
+# Good
+user = state.memory.scoped("user:#{user_id}")
+user.remember("name", name)
+user.remember("email", email)
+user.remember("plan", plan)
+
+# Less organized
+state.memory.remember("user_name", name)
+state.memory.remember("user_email", email)
+state.memory.remember("user_plan", plan)
+```
+
+### 3. Clean Up Temporary Data
+
+```ruby
+# At end of processing
+state.memory.scoped("temp").clear
+```
+
+### 4. Document Memory Keys
+
+```ruby
+# In your robot definitions, document expected keys
+# Memory keys used:
+# - SHARED:intent - Classification result
+# - SHARED:entities - Extracted entities
+# - user:{id}:* - User-specific data
+```
+
+## Next Steps
+
+- [State Management](../architecture/state-management.md) - Full state details
+- [Building Robots](building-robots.md) - Using memory in robots
+- [API Reference: Memory](../api/core/memory.md) - Complete API