robot_lab 0.0.1

data/docs/examples/tool-usage.md

@@ -0,0 +1,310 @@
+# Tool Usage
+
+Robots with external API integration.
+
+## Overview
+
+This example demonstrates how to give robots access to external systems through tools, including API calls, database queries, and calculations.
+
+## Complete Example
+
+```ruby
+#!/usr/bin/env ruby
+# examples/weather_assistant.rb
+
+require "bundler/setup"
+require "robot_lab"
+require "http"
+require "json"
+
+RobotLab.configure do |config|
+  config.default_model = "claude-sonnet-4"
+end
+
+# Weather assistant with API integration
+weather_bot = RobotLab.build do
+  name "weather_assistant"
+  description "Provides weather information"
+
+  template <<~PROMPT
+    You are a helpful weather assistant. You can look up current weather
+    conditions for any city. When users ask about weather, use the
+    get_weather tool to fetch real data.
+
+    Always provide temperatures in both Fahrenheit and Celsius.
+    Include relevant advice based on conditions (umbrella, sunscreen, etc).
+  PROMPT
+
+  tool :get_weather do
+    description "Get current weather for a city"
+
+    parameter :city, type: :string, required: true,
+              description: "City name (e.g., 'New York', 'London')"
+
+    handler do |city:, **_|
+      # Using wttr.in API (free, no key required)
+      response = HTTP.get("https://wttr.in/#{URI.encode_www_form_component(city)}?format=j1")
+
+      if response.status.success?
+        data = JSON.parse(response.body)
+        current = data["current_condition"].first
+
+        {
+          city: city,
+          temperature_f: current["temp_F"],
+          temperature_c: current["temp_C"],
+          condition: current["weatherDesc"].first["value"],
+          humidity: current["humidity"],
+          wind_mph: current["windspeedMiles"],
+          feels_like_f: current["FeelsLikeF"],
+          uv_index: current["uvIndex"]
+        }
+      else
+        { error: "Could not fetch weather for #{city}" }
+      end
+    rescue HTTP::Error => e
+      { error: "Network error: #{e.message}" }
+    end
+  end
+
+  tool :get_forecast do
+    description "Get weather forecast for upcoming days"
+
+    parameter :city, type: :string, required: true
+    parameter :days, type: :integer, default: 3
+
+    handler do |city:, days: 3, **_|
+      response = HTTP.get("https://wttr.in/#{URI.encode_www_form_component(city)}?format=j1")
+
+      if response.status.success?
+        data = JSON.parse(response.body)
+
+        data["weather"].take(days).map do |day|
+          {
+            date: day["date"],
+            high_f: day["maxtempF"],
+            low_f: day["mintempF"],
+            condition: day["hourly"].first["weatherDesc"].first["value"]
+          }
+        end
+      else
+        { error: "Could not fetch forecast" }
+      end
+    rescue HTTP::Error => e
+      { error: "Network error: #{e.message}" }
+    end
+  end
+end
+
+# Run interactive session
+puts "Weather 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?
+
+  state = RobotLab.create_state(message: input)
+
+  print "\nAssistant: "
+  weather_bot.run(state: state) do |event|
+    case event.type
+    when :text_delta
+      print event.text
+    when :tool_call
+      puts "\n[Checking weather for #{event.input[:city]}...]"
+    end
+  end
+  puts
+end
+
+puts "\nGoodbye!"
+```
+
+## Database Integration
+
+```ruby
+# examples/order_assistant.rb
+
+require "robot_lab"
+
+# Mock database
+ORDERS = {
+  "ORD001" => { id: "ORD001", status: "shipped", items: ["Widget"], total: 29.99 },
+  "ORD002" => { id: "ORD002", status: "processing", items: ["Gadget", "Gizmo"], total: 89.99 }
+}
+
+order_bot = RobotLab.build do
+  name "order_assistant"
+  template "You help customers check their orders."
+
+  tool :get_order do
+    description "Look up an order by ID"
+    parameter :order_id, type: :string, required: true
+
+    handler do |order_id:, state:, **_|
+      # Verify user owns this order
+      user_id = state.data[:user_id]
+      order = ORDERS[order_id.upcase]
+
+      if order
+        order
+      else
+        { error: "Order not found" }
+      end
+    end
+  end
+
+  tool :list_orders do
+    description "List user's recent orders"
+    parameter :limit, type: :integer, default: 5
+
+    handler do |limit:, state:, **_|
+      user_id = state.data[:user_id]
+      # Filter by user in real implementation
+      ORDERS.values.take(limit)
+    end
+  end
+
+  tool :cancel_order do
+    description "Cancel an order"
+    parameter :order_id, type: :string, required: true
+    parameter :reason, type: :string
+
+    handler do |order_id:, reason: nil, state:, **_|
+      order = ORDERS[order_id.upcase]
+
+      if order.nil?
+        { success: false, error: "Order not found" }
+      elsif order[:status] == "shipped"
+        { success: false, error: "Cannot cancel shipped orders" }
+      else
+        order[:status] = "cancelled"
+        order[:cancel_reason] = reason
+        { success: true, message: "Order #{order_id} cancelled" }
+      end
+    end
+  end
+end
+
+# Run with user context
+state = RobotLab.create_state(
+  message: "What's the status of order ORD001?",
+  data: { user_id: "user_123" }
+)
+
+result = order_bot.run(state: state)
+puts result.output.first.content
+```
+
+## Calculator Tool
+
+```ruby
+# examples/math_assistant.rb
+
+require "robot_lab"
+require "dentaku"
+
+calculator = Dentaku::Calculator.new
+
+math_bot = RobotLab.build do
+  name "math_assistant"
+  template "You help with mathematical calculations."
+
+  tool :calculate do
+    description "Evaluate a mathematical expression"
+    parameter :expression, type: :string, required: true,
+              description: "Math expression like '2 + 2' or 'sqrt(16)'"
+
+    handler do |expression:, **_|
+      result = calculator.evaluate(expression)
+      { expression: expression, result: result }
+    rescue => e
+      { error: "Invalid expression: #{e.message}" }
+    end
+  end
+
+  tool :solve_equation do
+    description "Solve for a variable"
+    parameter :equation, type: :string, required: true
+    parameter :variable, type: :string, required: true
+
+    handler do |equation:, variable:, **_|
+      result = calculator.solve(equation, variable.to_sym)
+      { equation: equation, variable: variable, solutions: result }
+    rescue => e
+      { error: "Could not solve: #{e.message}" }
+    end
+  end
+end
+```
+
+## Multi-Tool Example
+
+```ruby
+# examples/research_assistant.rb
+
+research_bot = RobotLab.build do
+  name "research_assistant"
+  template "You help with research tasks."
+
+  tool :web_search do
+    description "Search the web"
+    parameter :query, type: :string, required: true
+    handler { |query:, **_| SearchAPI.search(query) }
+  end
+
+  tool :read_url do
+    description "Read content from a URL"
+    parameter :url, type: :string, required: true
+    handler { |url:, **_| HTTP.get(url).body.to_s }
+  end
+
+  tool :summarize do
+    description "Summarize text"
+    parameter :text, type: :string, required: true
+    parameter :length, type: :string, enum: %w[short medium long], default: "medium"
+    handler { |text:, length:, **_| Summarizer.summarize(text, length) }
+  end
+
+  tool :save_note do
+    description "Save a research note"
+    parameter :title, type: :string, required: true
+    parameter :content, type: :string, required: true
+    handler do |title:, content:, state:, **_|
+      notes = state.memory.recall("notes") || []
+      notes << { title: title, content: content, created: Time.now }
+      state.memory.remember("notes", notes)
+      { saved: true, total_notes: notes.size }
+    end
+  end
+end
+```
+
+## Running
+
+```bash
+export ANTHROPIC_API_KEY="your-key"
+
+# Weather assistant
+ruby examples/weather_assistant.rb
+
+# Order lookup
+ruby examples/order_assistant.rb
+```
+
+## Key Concepts
+
+1. **Tool Definition**: Use the `tool` DSL with description and parameters
+2. **Handler**: Receives parameters plus state, robot, network context
+3. **Error Handling**: Return error hashes for graceful failures
+4. **State Access**: Tools can read/write state and memory
+
+## See Also
+
+- [Using Tools Guide](../guides/using-tools.md)
+- [Tool API](../api/core/tool.md)
+- [Memory Guide](../guides/memory.md)

data/docs/getting-started/configuration.md

@@ -0,0 +1,230 @@
+# Configuration
+
+RobotLab provides flexible configuration options at global, network, and robot levels.
+
+## Global Configuration
+
+Configure RobotLab globally using the `configure` block:
+
+```ruby
+RobotLab.configure do |config|
+  # LLM Provider API Keys
+  config.anthropic_api_key = ENV["ANTHROPIC_API_KEY"]
+  config.openai_api_key = ENV["OPENAI_API_KEY"]
+  config.gemini_api_key = ENV["GEMINI_API_KEY"]
+
+  # Default settings
+  config.default_provider = :anthropic
+  config.default_model = "claude-sonnet-4"
+
+  # Execution limits
+  config.max_iterations = 10        # Max robots per network run
+  config.max_tool_iterations = 10   # Max tool calls per robot run
+
+  # Streaming
+  config.streaming_enabled = true
+
+  # Logging
+  config.logger = Logger.new($stdout)
+
+  # Template path for prompt files
+  config.template_path = "prompts"
+end
+```
+
+## Configuration Options
+
+### API Keys
+
+| Option | Description |
+|--------|-------------|
+| `anthropic_api_key` | Anthropic Claude API key |
+| `openai_api_key` | OpenAI API key |
+| `gemini_api_key` | Google Gemini API key |
+| `bedrock_api_key` | AWS Bedrock API key |
+| `openrouter_api_key` | OpenRouter API key |
+
+### Defaults
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `default_provider` | `:anthropic` | Default LLM provider |
+| `default_model` | `"claude-sonnet-4"` | Default model |
+| `max_iterations` | `10` | Max robots per network run |
+| `max_tool_iterations` | `10` | Max tool calls per robot |
+| `streaming_enabled` | `true` | Enable streaming by default |
+
+### Templates
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `template_path` | `"prompts"` (or `"app/prompts"` in Rails) | Directory for prompt templates |
+
+### Global MCP & Tools
+
+```ruby
+RobotLab.configure do |config|
+  # Global MCP servers available to all networks
+  config.mcp = [
+    { name: "github", transport: { type: "stdio", command: "github-mcp" } }
+  ]
+
+  # Global tool whitelist
+  config.tools = %w[search_code create_issue]
+end
+```
+
+## Network-Level Configuration
+
+Override global settings at the network level:
+
+```ruby
+network = RobotLab.create_network do
+  name "my_network"
+
+  # Override default model for this network
+  default_model "claude-sonnet-4"
+
+  # Network-specific MCP servers
+  mcp [
+    { name: "filesystem", transport: { type: "stdio", command: "mcp-fs" } }
+  ]
+
+  # Network-specific tool whitelist
+  tools %w[read_file write_file]
+
+  # Or inherit from global
+  mcp :inherit
+  tools :inherit
+end
+```
+
+## Robot-Level Configuration
+
+Configure individual robots:
+
+```ruby
+robot = RobotLab.build do
+  name "specialist"
+
+  # Robot-specific model
+  model "claude-sonnet-4"
+
+  # Robot-specific MCP (overrides network)
+  mcp :inherit  # Use network's MCP servers
+  # or
+  mcp :none     # No MCP servers for this robot
+  # or
+  mcp [...]     # Specific servers
+
+  # Robot-specific tools
+  tools :inherit  # Use network's tools
+end
+```
+
+## Configuration Hierarchy
+
+Configuration cascades from global to network to robot:
+
+```
+Global (RobotLab.configure)
+  └── Network (create_network)
+        └── Robot (build)
+              └── Runtime (robot.run)
+```
+
+Each level can:
+
+- `:inherit` - Use parent level's configuration
+- `:none` or `nil` or `[]` - No items allowed
+- `[items]` - Specific items only
+
+## Rails Configuration
+
+In Rails, configure in an initializer:
+
+```ruby title="config/initializers/robot_lab.rb"
+RobotLab.configure do |config|
+  # Use Rails credentials
+  config.anthropic_api_key = Rails.application.credentials.anthropic_api_key
+
+  # Use Rails logger
+  config.logger = Rails.logger
+
+  # Template path is automatically set to app/prompts
+end
+```
+
+Or use `config/application.rb`:
+
+```ruby title="config/application.rb"
+module MyApp
+  class Application < Rails::Application
+    config.robot_lab.default_model = "claude-sonnet-4"
+    config.robot_lab.default_provider = :anthropic
+  end
+end
+```
+
+## Environment-Specific Configuration
+
+```ruby title="config/initializers/robot_lab.rb"
+RobotLab.configure do |config|
+  config.anthropic_api_key = ENV["ANTHROPIC_API_KEY"]
+
+  case Rails.env
+  when "development"
+    config.logger = Logger.new($stdout, level: :debug)
+    config.default_model = "claude-haiku-3"  # Faster/cheaper for dev
+  when "test"
+    config.streaming_enabled = false
+  when "production"
+    config.logger = Rails.logger
+    config.default_model = "claude-sonnet-4"
+  end
+end
+```
+
+## Using Environment Variables
+
+Recommended environment variables:
+
+```bash
+# Required - at least one provider
+ANTHROPIC_API_KEY=sk-ant-...
+OPENAI_API_KEY=sk-...
+GEMINI_API_KEY=...
+
+# Optional - override defaults
+ROBOT_LAB_DEFAULT_MODEL=claude-sonnet-4
+ROBOT_LAB_DEFAULT_PROVIDER=anthropic
+ROBOT_LAB_MAX_ITERATIONS=20
+```
+
+Load them in configuration:
+
+```ruby
+RobotLab.configure do |config|
+  config.anthropic_api_key = ENV["ANTHROPIC_API_KEY"]
+  config.default_model = ENV.fetch("ROBOT_LAB_DEFAULT_MODEL", "claude-sonnet-4")
+  config.max_iterations = ENV.fetch("ROBOT_LAB_MAX_ITERATIONS", 10).to_i
+end
+```
+
+## Accessing Configuration
+
+```ruby
+# Get current configuration
+config = RobotLab.configuration
+
+# Check settings
+config.default_model      # => "claude-sonnet-4"
+config.default_provider   # => :anthropic
+config.streaming_enabled  # => true
+```
+
+## Next Steps
+
+- [Building Robots](../guides/building-robots.md) - Create custom robots
+- [Creating Networks](../guides/creating-networks.md) - Network configuration
+- [MCP Integration](../guides/mcp-integration.md) - Configure MCP servers

data/docs/getting-started/index.md

@@ -0,0 +1,56 @@
+# Getting Started
+
+Welcome to RobotLab! This section will help you get up and running quickly.
+
+## What You'll Learn
+
+In this section, you'll learn how to:
+
+1. **Install RobotLab** - Add the gem to your project
+2. **Configure Your Environment** - Set up API keys and defaults
+3. **Create Your First Robot** - Build a simple AI assistant
+4. **Run a Network** - Execute a multi-robot workflow
+
+## Prerequisites
+
+Before you begin, make sure you have:
+
+- **Ruby 3.1+** installed
+- An **API key** from at least one LLM provider:
+    - [Anthropic](https://console.anthropic.com/) (recommended)
+    - [OpenAI](https://platform.openai.com/)
+    - [Google AI](https://ai.google.dev/)
+
+## Quick Links
+
+<div class="grid cards" markdown>
+
+-   [:octicons-download-24: **Installation**](installation.md)
+
+    Install RobotLab and dependencies
+
+-   [:octicons-rocket-24: **Quick Start**](quick-start.md)
+
+    Build your first robot in 5 minutes
+
+-   [:octicons-gear-24: **Configuration**](configuration.md)
+
+    Configure API keys and defaults
+
+</div>
+
+## Estimated Time
+
+| Guide | Time |
+|-------|------|
+| Installation | 2 minutes |
+| Quick Start | 5 minutes |
+| Configuration | 5 minutes |
+
+## Need Help?
+
+If you run into issues:
+
+- Check the [API Reference](../api/index.md) for detailed documentation
+- Browse [Examples](../examples/index.md) for working code
+- Open an issue on [GitHub](https://github.com/madbomber/robot_lab/issues)