robot_lab 0.0.1

data/docs/examples/basic-chat.md

@@ -0,0 +1,193 @@
+# Basic Chat
+
+A simple conversational robot example.
+
+## Overview
+
+This example demonstrates the minimal setup for a conversational robot that can respond to user messages.
+
+## Complete Example
+
+```ruby
+#!/usr/bin/env ruby
+# examples/basic_chat.rb
+
+require "bundler/setup"
+require "robot_lab"
+
+# Configure RobotLab
+RobotLab.configure do |config|
+  config.default_model = "claude-sonnet-4"
+end
+
+# Build a simple assistant
+assistant = RobotLab.build do
+  name "assistant"
+  description "A helpful conversational assistant"
+
+  template <<~PROMPT
+    You are a helpful, friendly assistant. You provide clear,
+    concise answers to questions. Be conversational but informative.
+  PROMPT
+end
+
+# Simple REPL
+puts "Chat with the assistant (type 'quit' to exit)"
+puts "-" * 50
+
+loop do
+  print "\nYou: "
+  input = gets&.chomp
+
+  break if input.nil? || input.downcase == "quit"
+  next if input.empty?
+
+  # Create state and run
+  state = RobotLab.create_state(message: input)
+  result = assistant.run(state: state)
+
+  # Display response
+  response = result.output.first&.content || "No response"
+  puts "\nAssistant: #{response}"
+end
+
+puts "\nGoodbye!"
+```
+
+## With Streaming
+
+```ruby
+#!/usr/bin/env ruby
+# examples/streaming_chat.rb
+
+require "bundler/setup"
+require "robot_lab"
+
+RobotLab.configure do |config|
+  config.default_model = "claude-sonnet-4"
+end
+
+assistant = RobotLab.build do
+  name "assistant"
+  template "You are a helpful assistant."
+end
+
+puts "Chat with streaming (type 'quit' to exit)"
+puts "-" * 50
+
+loop do
+  print "\nYou: "
+  input = gets&.chomp
+
+  break if input.nil? || input.downcase == "quit"
+  next if input.empty?
+
+  state = RobotLab.create_state(message: input)
+
+  print "\nAssistant: "
+  assistant.run(state: state) do |event|
+    print event.text if event.type == :text_delta
+  end
+  puts
+end
+
+puts "\nGoodbye!"
+```
+
+## With Conversation History
+
+```ruby
+#!/usr/bin/env ruby
+# examples/chat_with_memory.rb
+
+require "bundler/setup"
+require "robot_lab"
+
+RobotLab.configure do |config|
+  config.default_model = "claude-sonnet-4"
+end
+
+assistant = RobotLab.build do
+  name "assistant"
+  template "You are a helpful assistant with memory of our conversation."
+end
+
+# In-memory history store
+HISTORY = {}
+
+history_config = RobotLab::History::Config.new(
+  create_thread: ->(state:, **) {
+    id = SecureRandom.uuid
+    HISTORY[id] = []
+    { id: id }
+  },
+  get: ->(thread_id:, **) {
+    HISTORY[thread_id] || []
+  },
+  append_results: ->(thread_id:, new_results:, **) {
+    HISTORY[thread_id].concat(new_results.map(&:to_h))
+  }
+)
+
+network = RobotLab.create_network do
+  name "chat"
+  history history_config
+  add_robot assistant
+end
+
+puts "Chat with memory (type 'quit' to exit)"
+puts "-" * 50
+
+thread_id = nil
+
+loop do
+  print "\nYou: "
+  input = gets&.chomp
+
+  break if input.nil? || input.downcase == "quit"
+  next if input.empty?
+
+  message = thread_id ?
+    RobotLab::UserMessage.new(input, thread_id: thread_id) :
+    input
+
+  state = RobotLab.create_state(message: message)
+  result = network.run(state: state)
+
+  thread_id ||= result.state.thread_id
+
+  response = result.last_result&.output&.first&.content || "No response"
+  puts "\nAssistant: #{response}"
+end
+
+puts "\nGoodbye!"
+```
+
+## Running
+
+```bash
+# Set API key
+export ANTHROPIC_API_KEY="your-key"
+
+# Run basic chat
+ruby examples/basic_chat.rb
+
+# Run with streaming
+ruby examples/streaming_chat.rb
+
+# Run with memory
+ruby examples/chat_with_memory.rb
+```
+
+## Key Concepts
+
+1. **Robot Building**: Use `RobotLab.build` with a template
+2. **State Creation**: Use `RobotLab.create_state` with a message
+3. **Execution**: Call `robot.run(state: state)`
+4. **Response**: Access via `result.output.first.content`
+
+## See Also
+
+- [Building Robots Guide](../guides/building-robots.md)
+- [Streaming Guide](../guides/streaming.md)
+- [History Guide](../guides/history.md)

data/docs/examples/index.md

@@ -0,0 +1,129 @@
+# Examples
+
+Complete working examples demonstrating RobotLab features.
+
+## Overview
+
+These examples show how to use RobotLab for common scenarios, from simple chatbots to complex multi-robot systems.
+
+## Examples
+
+| Example | Description |
+|---------|-------------|
+| [Basic Chat](basic-chat.md) | Simple conversational robot |
+| [Multi-Robot Network](multi-robot-network.md) | Customer service with routing |
+| [Tool Usage](tool-usage.md) | External API integration |
+| [MCP Server](mcp-server.md) | Creating an MCP tool server |
+| [Rails Application](rails-application.md) | Full Rails integration |
+
+## Quick Links
+
+### Simple Examples
+
+- [Hello World Robot](#hello-world)
+- [Robot with Tools](#robot-with-tools)
+- [Network with Routing](#network-with-routing)
+
+### Advanced Examples
+
+- [Streaming Responses](basic-chat.md#with-streaming)
+- [Persistent Conversations](basic-chat.md#with-conversation-history)
+- [MCP Integration](mcp-server.md)
+
+## Hello World
+
+```ruby
+require "robot_lab"
+
+RobotLab.configure do |config|
+  config.default_model = "claude-sonnet-4"
+end
+
+robot = RobotLab.build do
+  name "greeter"
+  template "You are a friendly greeter. Say hello warmly."
+end
+
+state = RobotLab.create_state(message: "Hi there!")
+result = robot.run(state: state)
+
+puts result.output.first.content
+```
+
+## Robot with Tools
+
+```ruby
+robot = RobotLab.build do
+  name "calculator"
+  template "You help with calculations."
+
+  tool :calculate do
+    description "Perform a calculation"
+    parameter :expression, type: :string, required: true
+    handler { |expression:, **_| eval(expression).to_s }
+  end
+end
+
+state = RobotLab.create_state(message: "What's 25 * 4?")
+result = robot.run(state: state)
+```
+
+## Network with Routing
+
+```ruby
+classifier = RobotLab.build do
+  name "classifier"
+  template "Classify: BILLING, TECHNICAL, or GENERAL"
+end
+
+billing = RobotLab.build do
+  name "billing"
+  template "You handle billing questions."
+end
+
+tech = RobotLab.build do
+  name "tech"
+  template "You handle technical issues."
+end
+
+network = RobotLab.create_network do
+  name "support"
+  add_robot classifier
+  add_robot billing
+  add_robot tech
+
+  router ->(args) {
+    case args.call_count
+    when 0 then :classifier
+    when 1
+      category = args.last_result&.output&.first&.content&.strip
+      category == "BILLING" ? :billing : :tech
+    end
+  }
+end
+
+result = network.run(state: state)
+```
+
+## Running Examples
+
+1. Install dependencies:
+   ```bash
+   bundle install
+   ```
+
+2. Set API key:
+   ```bash
+   export ANTHROPIC_API_KEY="your-key"
+   ```
+
+3. Run example:
+   ```bash
+   ruby examples/basic_chat.rb
+   ```
+
+## See Also
+
+- [Getting Started](../getting-started/index.md)
+- [Guides](../guides/index.md)
+- [API Reference](../api/index.md)

data/docs/examples/mcp-server.md

@@ -0,0 +1,290 @@
+# MCP Server
+
+Creating and using Model Context Protocol servers.
+
+## Overview
+
+This example demonstrates how to create MCP servers to expose tools and how to connect robots to external MCP servers.
+
+## Creating an MCP Server
+
+```ruby
+#!/usr/bin/env ruby
+# examples/mcp_server.rb
+
+require "bundler/setup"
+require "robot_lab"
+require "json"
+
+# Create an MCP server with database tools
+server = RobotLab::MCP::Server.new(
+  name: "database_tools",
+  version: "1.0.0"
+)
+
+# Mock database
+USERS = {
+  "1" => { id: "1", name: "Alice", email: "alice@example.com", plan: "pro" },
+  "2" => { id: "2", name: "Bob", email: "bob@example.com", plan: "free" }
+}
+
+ORDERS = {
+  "ORD001" => { id: "ORD001", user_id: "1", total: 99.99, status: "shipped" },
+  "ORD002" => { id: "ORD002", user_id: "1", total: 49.99, status: "pending" },
+  "ORD003" => { id: "ORD003", user_id: "2", total: 29.99, status: "delivered" }
+}
+
+# Add tools to the server
+server.add_tool(
+  name: "get_user",
+  description: "Get user by ID",
+  parameters: {
+    user_id: { type: "string", required: true, description: "User ID" }
+  },
+  handler: ->(user_id:) {
+    user = USERS[user_id]
+    user || { error: "User not found" }
+  }
+)
+
+server.add_tool(
+  name: "list_users",
+  description: "List all users",
+  parameters: {
+    plan: { type: "string", enum: ["free", "pro"], description: "Filter by plan" }
+  },
+  handler: ->(plan: nil) {
+    users = USERS.values
+    users = users.select { |u| u[:plan] == plan } if plan
+    users
+  }
+)
+
+server.add_tool(
+  name: "get_orders",
+  description: "Get orders for a user",
+  parameters: {
+    user_id: { type: "string", required: true },
+    status: { type: "string", enum: ["pending", "shipped", "delivered"] }
+  },
+  handler: ->(user_id:, status: nil) {
+    orders = ORDERS.values.select { |o| o[:user_id] == user_id }
+    orders = orders.select { |o| o[:status] == status } if status
+    orders
+  }
+)
+
+server.add_tool(
+  name: "update_order_status",
+  description: "Update an order's status",
+  parameters: {
+    order_id: { type: "string", required: true },
+    status: { type: "string", required: true, enum: ["pending", "shipped", "delivered"] }
+  },
+  handler: ->(order_id:, status:) {
+    order = ORDERS[order_id]
+    return { error: "Order not found" } unless order
+    order[:status] = status
+    { success: true, order: order }
+  }
+)
+
+# Start the server (stdio for local use)
+puts "Starting MCP server..."
+server.start(transport: :stdio)
+```
+
+## Using MCP Server in Robot
+
+```ruby
+#!/usr/bin/env ruby
+# examples/mcp_client.rb
+
+require "bundler/setup"
+require "robot_lab"
+
+RobotLab.configure do |config|
+  config.default_model = "claude-sonnet-4"
+end
+
+# Robot that uses the MCP server
+admin_bot = RobotLab.build do
+  name "admin_assistant"
+  description "Helps with administrative tasks"
+
+  template <<~PROMPT
+    You are an administrative assistant with access to user and order data.
+    Help users look up information and manage orders.
+  PROMPT
+
+  mcp [
+    {
+      name: "database",
+      transport: {
+        type: "stdio",
+        command: "ruby",
+        args: ["examples/mcp_server.rb"]
+      }
+    }
+  ]
+end
+
+# Interactive session
+puts "Admin Assistant (uses MCP server)"
+puts "-" * 50
+
+state = RobotLab.create_state(message: "List all pro users and their orders")
+
+admin_bot.run(state: state) do |event|
+  case event.type
+  when :text_delta
+    print event.text
+  when :tool_call
+    puts "\n[MCP: #{event.name}]"
+  end
+end
+
+puts
+admin_bot.disconnect
+```
+
+## Network with MCP
+
+```ruby
+# examples/network_with_mcp.rb
+
+network = RobotLab.create_network do
+  name "support_with_mcp"
+
+  # MCP servers available to all robots
+  mcp [
+    {
+      name: "database",
+      transport: { type: "stdio", command: "ruby examples/mcp_server.rb" }
+    },
+    {
+      name: "filesystem",
+      transport: {
+        type: "stdio",
+        command: "npx",
+        args: ["@modelcontextprotocol/server-filesystem", "/data"]
+      }
+    }
+  ]
+
+  add_robot RobotLab.build {
+    name "data_analyst"
+    template "You analyze user data."
+    mcp :inherit  # Uses network's MCP servers
+  }
+
+  add_robot RobotLab.build {
+    name "file_manager"
+    template "You manage files."
+    mcp :inherit
+    tools %w[read_file list_directory]  # Only these MCP tools
+  }
+end
+```
+
+## HTTP MCP Server
+
+```ruby
+#!/usr/bin/env ruby
+# examples/http_mcp_server.rb
+
+require "robot_lab"
+require "sinatra"
+
+server = RobotLab::MCP::Server.new(name: "api_tools")
+
+server.add_tool(
+  name: "get_stats",
+  description: "Get system statistics",
+  parameters: {},
+  handler: -> {
+    {
+      uptime: `uptime`.strip,
+      memory: `free -m 2>/dev/null || vm_stat`.strip,
+      time: Time.now.iso8601
+    }
+  }
+)
+
+# Sinatra endpoint for MCP
+post "/mcp" do
+  content_type :json
+  request_body = JSON.parse(request.body.read)
+  response = server.handle_request(request_body)
+  response.to_json
+end
+
+# Run: ruby examples/http_mcp_server.rb
+# Connect with HTTP transport
+```
+
+## Connecting to HTTP Server
+
+```ruby
+robot = RobotLab.build do
+  name "remote_assistant"
+  template "You have access to remote tools."
+
+  mcp [
+    {
+      name: "remote",
+      transport: {
+        type: "http",
+        url: "https://mcp.example.com/mcp",
+        headers: { "Authorization" => "Bearer #{ENV['MCP_TOKEN']}" }
+      }
+    }
+  ]
+end
+```
+
+## WebSocket Server
+
+```ruby
+#!/usr/bin/env ruby
+# examples/websocket_mcp_server.rb
+
+require "robot_lab"
+
+server = RobotLab::MCP::Server.new(name: "realtime_tools")
+
+server.add_tool(
+  name: "subscribe_events",
+  description: "Subscribe to real-time events",
+  parameters: { channel: { type: "string", required: true } },
+  handler: ->(channel:) { { subscribed: channel } }
+)
+
+# Start WebSocket server
+server.start(transport: :websocket, port: 8765)
+```
+
+## Running
+
+```bash
+# Start MCP server in one terminal
+ruby examples/mcp_server.rb
+
+# Run client in another terminal
+export ANTHROPIC_API_KEY="your-key"
+ruby examples/mcp_client.rb
+```
+
+## Key Concepts
+
+1. **Server Creation**: Use `RobotLab::MCP::Server.new`
+2. **Tool Registration**: Add tools with `server.add_tool`
+3. **Transport**: Choose stdio, http, websocket, or sse
+4. **Client Connection**: Configure in robot's `mcp` block
+5. **Tool Filtering**: Use `tools` whitelist for security
+
+## See Also
+
+- [MCP Integration Guide](../guides/mcp-integration.md)
+- [MCP API Reference](../api/mcp/index.md)
+- [Transports](../api/mcp/transports.md)