robot_lab 0.3.0 → 0.3.1

data/examples/04_mcp.rb

@@ -1,217 +0,0 @@
-#!/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:
-#      - GITHUB_PERSONAL_ACCESS_TOKEN: Your GitHub personal access token
-#
-# Usage:
-#   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 "common"
-
-# 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", "")
-    }
-  }
-}
-
-banner "MCP Integration Example: GitHub"
-
-puts "This example demonstrates using the GitHub MCP server to interact"
-puts "with GitHub repositories through the Model Context Protocol."
-puts
-
-# 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
-# ============================================================================
-
-section "Part 1: Direct MCP Client Usage"
-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:"
-  hr
-
-  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
-
-  hr
-  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
-  # ============================================================================
-
-
-  section "Part 2: Robot + MCP Integration"
-
-  puts "Creating Robot with MCP server integration..."
-  puts
-
-  # Create a Robot with MCP server - tools are automatically discovered.
-  # connect_mcp! forces eager connection; without it MCP clients initialize
-  # lazily on the first run() call, leaving mcp_clients empty until then.
-  robot = RobotLab.build(
-    **llm_opts,
-    name: "github_assistant",
-    template: :github_assistant,
-    mcp_servers: [github_server]
-  )
-  robot.connect_mcp!
-
-  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:"
-  hr
-  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?'"
-  hr
-
-  # mcp: :inherit is required — run() defaults it to :none, which resolves to
-  # "no MCP servers this turn" and the discovered tools would never reach the
-  # provider. tools: takes an allowlist of tool names; :inherit would send all
-  # ~90 GitHub tools, whose JSON schemas alone exceed 13k tokens and overflow
-  # a local model's context window (LM Studio's default is 8192) before the
-  # query even arrives. Send only the one tool this query needs.
-  result = robot.run(
-    "What are the top 3 most starred Ruby web frameworks on GitHub? Just list their names and star counts.",
-    mcp:   :inherit,
-    tools: %w[search_repositories]
-  )
-
-  puts
-  puts "Robot Response:"
-  hr
-  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:"
-    hr
-    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
-hr
-puts "Example complete!"

data/examples/05_streaming.rb

@@ -1,137 +0,0 @@
-#!/usr/bin/env ruby
-# frozen_string_literal: true
-
-# Example 5: Streaming Content
-#
-# Demonstrates real-time streaming of LLM responses using:
-#   1. Stored callback (on_content:) — wired at build time
-#   2. Per-call block — passed to run()
-#   3. Both together — stored fires first, then block
-#
-# Usage:
-#   ruby examples/05_streaming.rb
-
-require_relative "common"
-
-# Send logger output to a file instead of stdout
-require 'logger'
-log_file = File.join(__dir__, "05.log")
-RobotLab.config.logger = Logger.new(log_file)
-RubyLLM.configure { |c| c.logger = Logger.new(log_file) }
-
-banner "Streaming Content"
-
-# ── 1. Stored callback (on_content:) ─────────────────────────────
-#
-# Wire streaming at build time. The callback fires on every run() call.
-
-section "1. Stored Callback (on_content:)"
-
-chunks_received = 0
-robot = RobotLab.build(
-  **llm_opts,
-  name: "storyteller",
-  system_prompt: "You are a concise storyteller. Keep responses under 3 sentences.",
-  on_content: ->(chunk) {
-    print chunk.content
-    chunks_received += 1
-  }
-)
-
-result = robot.run("Tell me a one-sentence fact about Ruby programming.")
-
-puts ""
-puts "(#{chunks_received} chunks streamed)"
-puts ""
-
-# ── 2. Per-call block ────────────────────────────────────────────
-#
-# Pass a block to run() for one-off streaming.
-
-section "2. Per-call Block"
-
-block_chunks = 0
-bare_robot = RobotLab.build(
-  **llm_opts,
-  name: "factbot",
-  system_prompt: "You are concise. Answer in one sentence."
-)
-
-bare_robot.run("What year was Ruby created?") { |chunk|
-  print chunk.content
-  block_chunks += 1
-}
-
-puts ""
-puts "(#{block_chunks} chunks streamed)"
-puts ""
-
-# ── 3. Both together ────────────────────────────────────────────
-#
-# When both exist, both fire: stored callback first, then block.
-
-section "3. Both Together (stored fires first, then block)"
-
-stored_log = []
-block_log  = []
-
-combo_robot = RobotLab.build(
-  **llm_opts,
-  name: "combo",
-  system_prompt: "You are concise. Answer in one sentence.",
-  on_content: ->(chunk) { stored_log << chunk.content }
-)
-
-combo_robot.run("What is Matz's full name?") { |chunk|
-  block_log << chunk.content
-  print chunk.content
-}
-
-puts ""
-puts "(stored callback saw #{stored_log.length} chunks, block saw #{block_log.length} chunks)"
-puts "Callbacks fired in sync: #{stored_log == block_log}"
-puts ""
-
-# ── 4. Via RunConfig ─────────────────────────────────────────────
-#
-# on_content participates in the config cascade.
-
-section "4. Via RunConfig (config cascade)"
-
-config_chunks = 0
-# RunConfig accepts only the fields in RunConfig::FIELDS — `provider` is not
-# one of them, so it stays on the robot. on_content is a first-class config
-# field and cascades normally.
-config = RobotLab::RunConfig.new(
-  model: LLM[:default].model,
-  on_content: ->(chunk) {
-    print chunk.content
-    config_chunks += 1
-  }
-)
-
-config_robot = RobotLab.build(
-  **llm_opts,
-  name: "config_bot",
-  system_prompt: "You are concise. Answer in one sentence.",
-  config: config
-)
-
-config_robot.run("Who designed the Ruby programming language?")
-
-puts ""
-puts "(#{config_chunks} chunks streamed via RunConfig)"
-puts ""
-
-# ── Summary ──────────────────────────────────────────────────────
-
-section "Summary"
-puts <<~SUMMARY
-  on_content: callback  — wired at build time, fires every run()
-  run() { |chunk| ... } — per-call streaming block
-  Both together         — stored fires first, then block
-  RunConfig             — on_content participates in config cascade
-
-  For structured event streaming (lifecycle events, tool deltas,
-  sequencing), see RobotLab::Streaming::Context and Events.
-SUMMARY

data/examples/06_prompt_templates.rb

@@ -1,325 +0,0 @@
-#!/usr/bin/env ruby
-# frozen_string_literal: true
-
-# Example 6: Prompt Templates with prompt_manager
-#
-# Demonstrates using prompt_manager for organized, reusable prompts
-# within a RobotLab network. This example shows an e-commerce support
-# system with dynamic context injection using SimpleFlow's optional task routing.
-#
-# Usage:
-#   ruby examples/06_prompt_templates.rb
-#
-# Template Structure (prompt_manager .md files with YAML front matter):
-#   examples/prompts/
-#   ├── triage.md
-#   ├── order_support.md
-#   ├── product_support.md
-#   └── escalation.md
-
-require_relative "common"
-
-# =============================================================================
-# Sample Data
-# =============================================================================
-# Simulated customer and business data that would come from your database.
-# company_name is a template parameter (declared null in all four templates).
-# AskUser gathers it from the user before building robots.
-
-ask = RobotLab::AskUser.new
-COMPANY_NAME = ask.call(
-  "question" => "What is your company name?",
-  "default"  => "TechGear Pro"
-)
-
-SAMPLE_CUSTOMER = {
-  name: "Sarah Johnson",
-  email: "sarah.johnson@example.com",
-  account_type: "Premium",
-  member_since: "2022-03-15",
-  vip: true,
-  lifetime_value: 4_250.00,
-  recent_orders: [
-    { id: "ORD-2024-1847", date: "2024-01-10", status: "Delivered", total: 299.99 },
-    { id: "ORD-2024-1923", date: "2024-01-15", status: "Processing", total: 149.50 }
-  ],
-  open_tickets: [
-    { id: "TKT-5521", subject: "Delayed shipment inquiry", status: "Open" }
-  ],
-  purchase_history: [
-    { category: "Electronics" },
-    { category: "Accessories" },
-    { category: "Audio" }
-  ],
-  escalation_history: []
-}
-
-CATEGORIES = [
-  { name: "order", description: "Order status, shipping, returns, refunds" },
-  { name: "product", description: "Product questions, specifications, recommendations" },
-  { name: "escalation", description: "Complex issues, complaints, special requests" }
-]
-
-ORDERS = [
-  {
-    id: "ORD-2024-1847",
-    date: "2024-01-10",
-    status: "Delivered",
-    total: 299.99,
-    tracking: "1Z999AA10123456784",
-    items: [
-      { name: "Wireless Noise-Canceling Headphones", quantity: 1, price: 249.99 },
-      { name: "Premium Carrying Case", quantity: 1, price: 49.99 }
-    ]
-  },
-  {
-    id: "ORD-2024-1923",
-    date: "2024-01-15",
-    status: "Processing",
-    total: 149.50,
-    tracking: nil,
-    items: [
-      { name: "USB-C Hub Pro", quantity: 1, price: 89.50 },
-      { name: "Braided USB-C Cable 2m", quantity: 2, price: 30.00 }
-    ]
-  }
-]
-
-PRODUCTS = [
-  {
-    name: "Wireless Noise-Canceling Headphones XR500",
-    sku: "AUDIO-XR500",
-    price: 249.99,
-    category: "Audio",
-    in_stock: true,
-    quantity: 45,
-    features: ["40hr battery life", "Active noise cancellation", "Bluetooth 5.2", "Hi-Res Audio"],
-    compatible_with: ["All Bluetooth devices", "3.5mm audio jack"]
-  },
-  {
-    name: "USB-C Hub Pro 7-in-1",
-    sku: "ACC-HUB7",
-    price: 89.50,
-    category: "Accessories",
-    in_stock: true,
-    quantity: 120,
-    features: ["4K HDMI output", "100W Power Delivery", "SD/MicroSD slots", "USB 3.0 ports"],
-    compatible_with: ["MacBook Pro", "MacBook Air", "iPad Pro", "Windows laptops"]
-  }
-]
-
-PROMOTIONS = [
-  { name: "New Year Sale", description: "15% off all audio products", code: "AUDIO15" },
-  { name: "Free Shipping", description: "Free shipping on orders over $75", code: "FREESHIP" }
-]
-
-PRODUCT_CATEGORIES = [
-  { name: "Electronics", description: "Laptops, tablets, smartphones" },
-  { name: "Audio", description: "Headphones, speakers, microphones" },
-  { name: "Accessories", description: "Cables, hubs, cases, chargers" }
-]
-
-POLICIES = {
-  refund_window: 30,
-  free_shipping_threshold: 75,
-  express_fee: "$12.99"
-}
-
-ORDER_CAPABILITIES = [
-  "Check order status and tracking",
-  "Process returns and exchanges",
-  "Issue refunds (up to $500 without manager approval)",
-  "Modify pending orders",
-  "Apply shipping upgrades"
-]
-
-ESCALATION_AUTHORITIES = [
-  { name: "Courtesy Credit", description: "Account credit for inconvenience", limit: "$50" },
-  { name: "Expedited Shipping", description: "Free upgrade to express shipping", limit: "Unlimited" },
-  { name: "Extended Return Window", description: "Extend return period", limit: "60 days" },
-  { name: "Price Match", description: "Match competitor pricing", limit: "20% max discount" }
-]
-
-# =============================================================================
-# Triage Robot with Routing Logic
-# =============================================================================
-
-# Custom triage robot that classifies and activates appropriate specialist
-class TriageRobot < RobotLab::Robot
-  def call(result)
-    run_context = extract_run_context(result)
-    message = run_context.delete(:message)
-    robot_result = run(message, **run_context)
-
-    new_result = result
-      .with_context(@name.to_sym, robot_result)
-      .continue(robot_result)
-
-    # Examine LLM output and activate appropriate specialist
-    classification = robot_result.reply.to_s.strip.downcase
-
-    case classification
-    when /order/
-      new_result.activate(:order)
-    when /product/
-      new_result.activate(:product)
-    when /escalat/
-      new_result.activate(:escalation)
-    else
-      # Default to escalation for unclear cases
-      new_result.activate(:escalation)
-    end
-  end
-end
-
-# =============================================================================
-# Main Demo
-# =============================================================================
-
-banner "RobotLab + Prompt Templates Demo"
-puts "E-Commerce Support Network with Dynamic Context"
-puts
-
-# Template path is set via ROBOT_LAB_TEMPLATE_PATH env var (see top of file)
-
-# -----------------------------------------------------------------------------
-# Build Robots with Template-Based Prompts
-# -----------------------------------------------------------------------------
-
-# Triage Robot - Classifies incoming requests
-triage_robot = TriageRobot.new(
-  name: "triage",
-  description: "Classifies incoming requests to route to specialists",
-  template: :triage,
-  local_tools: [RobotLab::AskUser],
-  context: {
-    company_name: COMPANY_NAME,
-    categories: CATEGORIES
-  },
-  **llm_opts
-)
-
-# Order Support Robot
-order_robot = RobotLab.build(
-  **llm_opts,
-  name: "order",
-  description: "Handles order-related inquiries with full order history",
-  template: :order_support,
-  local_tools: [RobotLab::AskUser],
-  context: {
-    company_name: COMPANY_NAME,
-    policies: POLICIES,
-    capabilities: ORDER_CAPABILITIES
-  }
-)
-
-# Product Support Robot
-product_robot = RobotLab.build(
-  **llm_opts,
-  name: "product",
-  description: "Answers product questions with catalog knowledge",
-  template: :product_support,
-  local_tools: [RobotLab::AskUser],
-  context: {
-    company_name: COMPANY_NAME,
-    products: PRODUCTS,
-    promotions: PROMOTIONS,
-    product_categories: PRODUCT_CATEGORIES
-  }
-)
-
-# Escalation Robot
-escalation_robot = RobotLab.build(
-  **llm_opts,
-  name: "escalation",
-  description: "Handles complex cases requiring special authority",
-  template: :escalation,
-  local_tools: [RobotLab::AskUser],
-  context: {
-    company_name: COMPANY_NAME,
-    authorities: ESCALATION_AUTHORITIES
-  }
-)
-
-# -----------------------------------------------------------------------------
-# Create Network with Optional Task Routing
-# -----------------------------------------------------------------------------
-
-# tools: :inherit on each task. Task#to_run_params forwards it to robot.run,
-# which otherwise defaults to :none and would send the provider an empty tool
-# list — the AskUser tool would be attached to each robot but never offered
-# to the model.
-network = RobotLab.create_network(name: "ecommerce_support") do
-  task :triage, triage_robot, depends_on: :none, tools: :inherit
-  task :order, order_robot, depends_on: :optional, tools: :inherit
-  task :product, product_robot, depends_on: :optional, tools: :inherit
-  task :escalation, escalation_robot, depends_on: :optional, tools: :inherit
-end
-
-# -----------------------------------------------------------------------------
-# Run Demo Scenarios
-# -----------------------------------------------------------------------------
-
-demo_queries = [
-  {
-    label: "Order Inquiry",
-    message: "Where is my order ORD-2024-1923? It's been 5 days and still shows processing."
-  },
-  {
-    label: "Product Question",
-    message: "Are the XR500 headphones compatible with my iPhone? What's the battery life?"
-  },
-  {
-    label: "Escalation Case",
-    message: "This is ridiculous! I've been waiting 2 weeks for my order and nobody can help me. I want a refund AND compensation for this terrible experience!"
-  }
-]
-
-demo_queries.each_with_index do |query, index|
-  section "Scenario #{index + 1}: #{query[:label]}"
-  puts "Customer: #{query[:message]}"
-  puts
-
-  # Run the network with context
-  result = network.run(
-    message: query[:message],
-    customer: SAMPLE_CUSTOMER,
-    orders: ORDERS
-  )
-
-  # Display triage classification
-  if result.context[:triage]
-    triage_result = result.context[:triage]
-    puts "Classification: #{triage_result.reply}"
-    puts
-  end
-
-  # Display specialist response (the final value)
-  if result.value.is_a?(RobotLab::RobotResult)
-    puts "Routed to: #{result.value.robot_name.upcase}"
-    content = result.value.reply.to_s
-    # Truncate long responses for display
-    if content.length > 300
-      puts "Response: #{content[0..300]}..."
-    else
-      puts "Response: #{content}"
-    end
-  end
-
-  puts
-  hr
-end
-
-puts
-puts "Demo Complete!"
-puts
-puts <<~FOOTER
-  This example demonstrates:
-    - prompt_manager templates (.md with YAML front matter)
-    - Build-time context (robot identity/capabilities)
-    - Run-time context (customer data, order history)
-    - Multi-robot network with optional task routing
-    - SimpleFlow::Result for passing context between robots
-
-  Template files are located in: #{File.join(__dir__, 'prompts')}
-FOOTER