robot_lab 0.0.1

data/docs/index.md

@@ -0,0 +1,160 @@
+# RobotLab
+
+> [!CAUTION]
+> This gem is under active development. APIs and features may change without notice. See the [CHANGELOG](https://github.com/MadBomber/robot_lab/blob/main/CHANGELOG.md) for details.
+
+<table>
+<tr>
+<td width="50%" align="center" valign="top">
+<img src="assets/images/robot_lab.jpg" alt="RobotLab"><br>
+<em>"Build robots. Solve problems."</em>
+</td>
+<td width="50%" valign="top">
+RobotLab is a Ruby gem that enables you to build sophisticated AI applications using multiple specialized robots (LLM agents) that work together to accomplish complex tasks.<br><br>
+Each robot has its own system prompt, tools, and capabilities. Robots can be orchestrated through networks with customizable routing logic, share information through a hierarchical memory system, and connect to external tools via the Model Context Protocol (MCP).
+</td>
+</tr>
+</table>
+
+## Key Features
+
+<div class="grid cards" markdown>
+
+-   :material-robot:{ .lg .middle } **Multi-Robot Architecture**
+
+    ---
+
+    Build applications with multiple specialized AI agents, each with unique capabilities and personalities.
+
+    [:octicons-arrow-right-24: Learn more](architecture/core-concepts.md)
+
+-   :material-transit-connection-variant:{ .lg .middle } **Network Orchestration**
+
+    ---
+
+    Connect robots in networks with flexible routing to handle complex, multi-step workflows.
+
+    [:octicons-arrow-right-24: Creating Networks](guides/creating-networks.md)
+
+-   :material-tools:{ .lg .middle } **Extensible Tools**
+
+    ---
+
+    Give robots custom tools to interact with external systems, databases, and APIs.
+
+    [:octicons-arrow-right-24: Using Tools](guides/using-tools.md)
+
+-   :material-server-network:{ .lg .middle } **MCP Integration**
+
+    ---
+
+    Connect to Model Context Protocol servers to extend robot capabilities with external tools.
+
+    [:octicons-arrow-right-24: MCP Guide](guides/mcp-integration.md)
+
+-   :material-memory:{ .lg .middle } **Shared Memory**
+
+    ---
+
+    Robots can share information through a hierarchical memory system with namespaced scopes.
+
+    [:octicons-arrow-right-24: Memory System](guides/memory.md)
+
+-   :material-history:{ .lg .middle } **Conversation History**
+
+    ---
+
+    Persist and restore conversation threads for long-running interactions.
+
+    [:octicons-arrow-right-24: History Guide](guides/history.md)
+
+</div>
+
+## Quick Example
+
+```ruby
+require "robot_lab"
+
+# Configure RobotLab
+RobotLab.configure do |config|
+  config.anthropic_api_key = ENV["ANTHROPIC_API_KEY"]
+  config.default_model = "claude-sonnet-4"
+end
+
+# Create a simple robot
+robot = RobotLab.build do
+  name "assistant"
+  description "A helpful AI assistant"
+  template <<~PROMPT
+    You are a helpful assistant. Answer questions clearly and concisely.
+  PROMPT
+end
+
+# Create a network with the robot
+network = RobotLab.create_network do
+  name "simple_network"
+  add_robot robot
+end
+
+# Run the network
+state = RobotLab.create_state(message: "What is the capital of France?")
+result = network.run(state: state)
+
+puts result.last_result.output.first.content
+# => "The capital of France is Paris."
+```
+
+## Supported LLM Providers
+
+RobotLab supports multiple LLM providers through the [ruby_llm](https://github.com/crmne/ruby_llm) library:
+
+| Provider | Models |
+|----------|--------|
+| **Anthropic** | Claude 4, Claude Sonnet, Claude Haiku |
+| **OpenAI** | GPT-4o, GPT-4, GPT-3.5 Turbo |
+| **Google** | Gemini Pro, Gemini Ultra |
+| **Azure OpenAI** | All Azure-hosted OpenAI models |
+| **Bedrock** | Claude models via AWS Bedrock |
+| **Ollama** | Local models via Ollama |
+
+## Installation
+
+Add RobotLab to your Gemfile:
+
+```ruby
+gem "robot_lab"
+```
+
+Or install directly:
+
+```bash
+gem install robot_lab
+```
+
+[:octicons-arrow-right-24: Full Installation Guide](getting-started/installation.md)
+
+## Next Steps
+
+<div class="grid cards" markdown>
+
+-   [:octicons-rocket-24: **Quick Start**](getting-started/quick-start.md)
+
+    Get up and running in 5 minutes
+
+-   [:octicons-book-24: **Concepts**](concepts.md)
+
+    Understand the core concepts
+
+-   [:octicons-code-24: **Examples**](examples/index.md)
+
+    See RobotLab in action
+
+-   [:octicons-gear-24: **API Reference**](api/index.md)
+
+    Detailed API documentation
+
+</div>
+
+## License
+
+RobotLab is released under the [MIT License](https://opensource.org/licenses/MIT).

data/examples/01_simple_robot.rb

@@ -0,0 +1,38 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example 1: Simple Robot
+#
+# Demonstrates creating and running a basic robot with a template.
+#
+# Usage:
+#   ANTHROPIC_API_KEY=your_key ruby examples/01_simple_robot.rb
+
+require_relative "../lib/robot_lab"
+
+# Configure RobotLab
+RobotLab.configure do |config|
+  config.anthropic_api_key = ENV.fetch("ANTHROPIC_API_KEY", nil)
+  config.template_path = File.join(__dir__, "prompts")
+end
+
+# Create a simple robot using a template
+robot = RobotLab.build(
+  name: "helper",
+  template: :helper,
+  model: "claude-sonnet-4"
+)
+
+puts "Running simple robot..."
+puts "-" * 40
+
+# Run the robot with a simple query
+result = robot.run(message: "What is 2 + 2? Please explain your reasoning briefly.")
+
+# Display the result
+puts "Robot: #{robot.name}"
+puts "Output:"
+result.output.each do |message|
+  puts "  #{message.content}" if message.respond_to?(:content)
+end
+puts "-" * 40

data/examples/02_tools.rb

@@ -0,0 +1,106 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example 2: Robot with Tools
+#
+# Demonstrates creating a robot with custom tools using RubyLLM::Tool.
+#
+# Usage:
+#   ANTHROPIC_API_KEY=your_key ruby examples/02_tools.rb
+
+require_relative "../lib/robot_lab"
+
+# Configure RobotLab
+RobotLab.configure do |config|
+  config.anthropic_api_key = ENV.fetch("ANTHROPIC_API_KEY", nil)
+  config.template_path = File.join(__dir__, "prompts")
+end
+
+# Define tools using RubyLLM::Tool
+class Calculator < RubyLLM::Tool
+  description "Performs basic arithmetic operations"
+
+  param :operation,
+        type: "string",
+        desc: "The operation to perform (add, subtract, multiply, divide)"
+
+  param :a,
+        type: "number",
+        desc: "First operand"
+
+  param :b,
+        type: "number",
+        desc: "Second operand"
+
+  def execute(operation:, a:, b:)
+    case operation
+    when "add" then a + b
+    when "subtract" then a - b
+    when "multiply" then a * b
+    when "divide" then a.to_f / b
+    else "Unknown operation: #{operation}"
+    end
+  end
+end
+
+class FortuneCookie < RubyLLM::Tool
+  description "Get a fortune cookie message with wisdom and lucky numbers"
+
+  param :category,
+        type: "string",
+        desc: "The category of fortune (wisdom, love, career, adventure)"
+
+  FORTUNES = {
+    "wisdom" => [
+      "The obstacle in the path becomes the path.",
+      "A journey of a thousand miles begins with a single step.",
+      "The best time to plant a tree was 20 years ago. The second best time is now."
+    ],
+    "love" => [
+      "The heart that loves is always young.",
+      "To love and be loved is to feel the sun from both sides.",
+      "Love is not about finding the right person, but being the right person."
+    ],
+    "career" => [
+      "Opportunity dances with those already on the dance floor.",
+      "Your work is your signature. Sign it with excellence.",
+      "The expert in anything was once a beginner."
+    ],
+    "adventure" => [
+      "Life shrinks or expands in proportion to one's courage.",
+      "Not all who wander are lost.",
+      "The biggest adventure you can take is to live the life of your dreams."
+    ]
+  }.freeze
+
+  def execute(category:)
+    {
+      category: category,
+      fortune: FORTUNES.fetch(category, FORTUNES["wisdom"]).sample,
+      lucky_numbers: Array.new(6) { rand(1..49) }.sort
+    }
+  end
+end
+
+# Create robot with tools
+robot = RobotLab.build(
+  name: "assistant",
+  template: :assistant,
+  tools: [Calculator, FortuneCookie],
+  model: "claude-sonnet-4"
+)
+
+puts "Running robot with tools..."
+puts "-" * 40
+
+# Run the robot
+result = robot.run(message: "What is 15 multiplied by 7? Also, give me a fortune about my career.")
+
+# Display results
+puts "Robot: #{robot.name}"
+puts "\nOutput:"
+result.output.each do |message|
+  puts "  #{message.content}" if message.respond_to?(:content)
+end
+
+puts "-" * 40

data/examples/03_network.rb

@@ -0,0 +1,103 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example 3: Multi-Robot Network
+#
+# Demonstrates creating a network of robots with conditional routing
+# using SimpleFlow's optional step activation.
+#
+# Usage:
+#   ANTHROPIC_API_KEY=your_key ruby examples/03_network.rb
+
+require_relative "../lib/robot_lab"
+
+# Configure RobotLab
+RobotLab.configure do |config|
+  config.anthropic_api_key = ENV.fetch("ANTHROPIC_API_KEY", nil)
+  config.template_path = File.join(__dir__, "prompts")
+end
+
+# Classifier robot that activates the appropriate specialist
+class ClassifierRobot < RobotLab::Robot
+  def call(result)
+    robot_result = run(**extract_run_context(result))
+
+    new_result = result
+      .with_context(@name.to_sym, robot_result)
+      .continue(robot_result)
+
+    # Examine LLM output and activate appropriate specialist
+    category = robot_result.last_text_content.to_s.strip.downcase
+
+    case category
+    when /billing/
+      new_result.activate(:billing)
+    when /technical/
+      new_result.activate(:technical)
+    else
+      new_result.activate(:general)
+    end
+  end
+end
+
+# Create specialized robots
+classifier = ClassifierRobot.new(
+  name: "classifier",
+  template: :classifier,
+  model: "claude-sonnet-4"
+)
+
+billing_robot = RobotLab.build(
+  name: "billing",
+  template: :billing,
+  model: "claude-sonnet-4"
+)
+
+technical_robot = RobotLab.build(
+  name: "technical",
+  template: :technical,
+  model: "claude-sonnet-4"
+)
+
+general_robot = RobotLab.build(
+  name: "general",
+  template: :general,
+  model: "claude-sonnet-4"
+)
+
+# Create network with optional task routing
+network = RobotLab.create_network(name: "support_network") do
+  task :classifier, classifier, depends_on: :none
+  task :billing, billing_robot, depends_on: :optional
+  task :technical, technical_robot, depends_on: :optional
+  task :general, general_robot, depends_on: :optional
+end
+
+puts "Running multi-robot network..."
+puts "-" * 40
+puts "Network structure:"
+puts network.visualize
+puts "-" * 40
+
+# Run the network with a billing question
+result = network.run(message: "I was charged twice for my subscription last month. Can you help?")
+
+# Display results
+puts "Network: #{network.name}"
+puts "\nConversation flow:"
+
+# Show classifier result
+if result.context[:classifier]
+  classifier_result = result.context[:classifier]
+  puts "\n1. Robot: classifier"
+  puts "   Classification: #{classifier_result.last_text_content}"
+end
+
+# Show specialist result (the final value)
+if result.value.is_a?(RobotLab::RobotResult)
+  puts "\n2. Robot: #{result.value.robot_name}"
+  content = result.value.last_text_content
+  puts "   Response: #{content[0..200]}..." if content
+end
+
+puts "-" * 40

data/examples/04_mcp.rb

@@ -0,0 +1,219 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example 4: MCP (Model Context Protocol) Integration with GitHub
+#
+# Demonstrates connecting to the GitHub MCP server and using its tools
+# to interact with GitHub repositories.
+#
+# Prerequisites:
+#   1. Install the GitHub MCP server: brew install github-mcp-server
+#   2. Set environment variables:
+#      - ANTHROPIC_API_KEY: Your Anthropic API key
+#      - GITHUB_PERSONAL_ACCESS_TOKEN: Your GitHub personal access token
+#
+# Usage:
+#   ANTHROPIC_API_KEY=your_key GITHUB_PERSONAL_ACCESS_TOKEN=your_token ruby examples/04_mcp.rb
+#
+# The GitHub MCP server provides tools for:
+#   - Searching repositories, code, issues, and users
+#   - Creating and managing issues and pull requests
+#   - Reading file contents and repository information
+#   - Managing branches and commits
+
+require_relative "../lib/robot_lab"
+
+# Configure RobotLab
+RobotLab.configure do |config|
+  config.anthropic_api_key = ENV.fetch("ANTHROPIC_API_KEY", nil)
+  config.template_path = File.join(__dir__, "prompts")
+end
+
+# GitHub MCP server configuration using StdIO transport
+github_server = {
+  name: "github",
+  transport: {
+    type: "stdio",
+    command: "github-mcp-server",
+    args: ["stdio"],
+    env: {
+      "GITHUB_PERSONAL_ACCESS_TOKEN" => ENV.fetch("GITHUB_PERSONAL_ACCESS_TOKEN", "")
+    }
+  }
+}
+
+puts <<~HEADER
+  MCP Integration Example: GitHub
+  #{"=" * 40}
+
+  This example demonstrates using the GitHub MCP server to interact
+  with GitHub repositories through the Model Context Protocol.
+
+HEADER
+
+# Verify prerequisites
+unless ENV["GITHUB_PERSONAL_ACCESS_TOKEN"]
+  puts <<~ERROR
+    ERROR: GITHUB_PERSONAL_ACCESS_TOKEN environment variable not set.
+
+    To use this example:
+      1. Create a GitHub Personal Access Token at https://github.com/settings/tokens
+      2. Grant appropriate permissions (repo, read:user, etc.)
+      3. Run: GITHUB_PERSONAL_ACCESS_TOKEN=your_token ruby examples/04_mcp.rb
+  ERROR
+  exit 1
+end
+
+# ============================================================================
+# Part 1: Direct MCP Client Usage
+# ============================================================================
+
+puts "PART 1: Direct MCP Client Usage"
+puts "-" * 40
+puts
+puts "Connecting to GitHub MCP server..."
+
+begin
+  # Create MCP client and connect
+  client = RobotLab::MCP::Client.new(github_server)
+  client.connect
+
+  unless client.connected?
+    puts <<~ERROR
+
+      ERROR: Failed to connect to the GitHub MCP server.
+
+      Make sure you have installed it:
+        brew install github-mcp-server
+    ERROR
+    exit 1
+  end
+
+  puts "Connected successfully!"
+  puts
+
+  # List available tools
+  puts "Available GitHub Tools:"
+  puts "-" * 40
+
+  tools = client.list_tools
+  if tools.empty?
+    puts "  (No tools returned - check server connection)"
+  else
+    tools.each do |tool|
+      puts "  #{tool[:name]}"
+      puts "    #{tool[:description]}" if tool[:description]
+    end
+  end
+
+  puts "-" * 40
+  puts "Total: #{tools.size} tools available"
+  puts
+
+  # Demonstrate a simple tool call: search for repositories
+  puts "Demo: Searching for popular Ruby repositories..."
+  puts
+
+  result = client.call_tool("search_repositories", {
+    query: "language:ruby stars:>1000",
+    per_page: 5
+  })
+
+  # Extract and pretty print the JSON result
+  if result.is_a?(Array) && result.first.is_a?(Hash) && result.first[:text]
+    data = JSON.parse(result.first[:text])
+    puts JSON.pretty_generate(data)
+  else
+    puts JSON.pretty_generate(result)
+  end
+
+  puts
+
+  # Clean up direct client
+  client.disconnect
+  puts "Disconnected from direct MCP client."
+
+  # ============================================================================
+  # Part 2: Robot + MCP Integration
+  # ============================================================================
+
+  puts
+  puts "=" * 40
+  puts "PART 2: Robot + MCP Integration"
+  puts "-" * 40
+  puts
+
+  puts "Creating Robot with MCP server integration..."
+  puts
+
+  # Create a Robot with MCP server - tools are automatically discovered
+  robot = RobotLab.build(
+    name: "github_assistant",
+    template: :github_assistant,
+    mcp_servers: [github_server],
+    model: "claude-sonnet-4-20250514"
+  )
+
+  puts "Robot created: #{robot.name}"
+  puts "  Model: #{robot.model}"
+  puts "  MCP Servers: #{robot.mcp_clients.keys.join(", ")}"
+  puts "  MCP Tools discovered: #{robot.mcp_tools.size}"
+  puts
+
+  # Show discovered MCP tools
+  puts "Discovered MCP Tools:"
+  puts "-" * 40
+  robot.mcp_tools.first(10).each do |tool|
+    puts "  #{tool.name}"
+    puts "    #{tool.description&.slice(0, 60)}..." if tool.description
+  end
+  puts "  ... and #{robot.mcp_tools.size - 10} more" if robot.mcp_tools.size > 10
+  puts
+
+  # Run the robot with a query that will use MCP tools
+  puts "Running Robot with a GitHub query..."
+  puts "Query: 'What are the top 3 most starred Ruby web frameworks on GitHub?'"
+  puts "-" * 40
+
+  result = robot.run(message: "What are the top 3 most starred Ruby web frameworks on GitHub? Just list their names and star counts.")
+
+  puts
+  puts "Robot Response:"
+  puts "-" * 40
+  result.output.each do |msg|
+    puts msg.content if msg.respond_to?(:content)
+  end
+  puts
+
+  # Show tool calls if any were made
+  if result.tool_calls.any?
+    puts "Tool Calls Made:"
+    puts "-" * 40
+    result.tool_calls.each do |tc|
+      tool_info = tc.respond_to?(:tool) ? tc.tool : tc
+      puts "  #{tool_info[:name] || tool_info}"
+    end
+    puts
+  end
+
+  # Clean up robot's MCP connections
+  robot.disconnect
+  puts "Robot MCP connections disconnected."
+
+rescue RobotLab::MCPError => e
+  puts "MCP Error: #{e.message}"
+  exit 1
+rescue Errno::ENOENT
+  puts <<~ERROR
+
+    ERROR: Could not find the github-mcp-server command.
+
+    Install it with:
+      brew install github-mcp-server
+  ERROR
+  exit 1
+end
+
+puts
+puts "=" * 40
+puts "Example complete!"