robot_lab 0.0.1

data/docs/examples/multi-robot-network.md

@@ -0,0 +1,312 @@
+# Multi-Robot Network
+
+Customer service system with intelligent routing using SimpleFlow pipelines.
+
+## Overview
+
+This example demonstrates a multi-robot network where a classifier routes customer inquiries to specialized support robots using optional task activation.
+
+## Complete Example
+
+```ruby
+#!/usr/bin/env ruby
+# examples/customer_service.rb
+
+require "bundler/setup"
+require "robot_lab"
+
+RobotLab.configure do |config|
+  config.default_model = "claude-sonnet-4"
+end
+
+# Custom classifier that routes to specialists
+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)
+
+    # Route based on classification
+    category = robot_result.last_text_content.to_s.strip.downcase
+
+    case category
+    when /billing/ then new_result.activate(:billing_agent)
+    when /technical/ then new_result.activate(:tech_agent)
+    when /account/ then new_result.activate(:account_agent)
+    else new_result.activate(:general_agent)
+    end
+  end
+end
+
+# Classifier robot
+classifier = ClassifierRobot.new(
+  name: "classifier",
+  description: "Classifies customer inquiries",
+  system_prompt: <<~PROMPT
+    You are a customer inquiry classifier. Analyze the customer's message
+    and respond with exactly ONE of these categories:
+
+    - BILLING (payment issues, invoices, refunds, subscriptions)
+    - TECHNICAL (bugs, errors, how-to questions, feature requests)
+    - ACCOUNT (login issues, profile changes, security concerns)
+    - GENERAL (everything else)
+
+    Respond with ONLY the category name, nothing else.
+  PROMPT
+)
+
+# Billing specialist
+billing_agent = RobotLab.build(
+  name: "billing_agent",
+  description: "Handles billing inquiries",
+  system_prompt: <<~PROMPT
+    You are a billing support specialist. You help customers with:
+    - Payment issues and refunds
+    - Invoice questions
+    - Subscription management
+    - Pricing inquiries
+
+    Be helpful, empathetic, and provide clear next steps.
+  PROMPT
+)
+
+# Technical support
+tech_agent = RobotLab.build(
+  name: "tech_agent",
+  description: "Handles technical issues",
+  system_prompt: <<~PROMPT
+    You are a technical support specialist. You help customers with:
+    - Bug reports and troubleshooting
+    - Feature explanations
+    - Integration questions
+    - Best practices
+
+    Ask clarifying questions when needed. Provide step-by-step solutions.
+  PROMPT
+)
+
+# Account specialist
+account_agent = RobotLab.build(
+  name: "account_agent",
+  description: "Handles account issues",
+  system_prompt: <<~PROMPT
+    You are an account support specialist. You help customers with:
+    - Login and authentication issues
+    - Profile and settings changes
+    - Security concerns
+    - Account recovery
+
+    Prioritize security while being helpful.
+  PROMPT
+)
+
+# General support
+general_agent = RobotLab.build(
+  name: "general_agent",
+  description: "Handles general inquiries",
+  system_prompt: <<~PROMPT
+    You are a general support agent. You help customers with:
+    - Product information
+    - General questions
+    - Feedback collection
+    - Routing to appropriate departments
+
+    Be friendly and informative.
+  PROMPT
+)
+
+# Create the network with optional task routing
+network = RobotLab.create_network(name: "customer_service") do
+  task :classifier, classifier, depends_on: :none
+  task :billing_agent, billing_agent, depends_on: :optional
+  task :tech_agent, tech_agent, depends_on: :optional
+  task :account_agent, account_agent, depends_on: :optional
+  task :general_agent, general_agent, depends_on: :optional
+end
+
+# Run the support system
+puts "Customer Service System"
+puts "=" * 50
+puts
+
+test_inquiries = [
+  "I was charged twice for my subscription last month",
+  "How do I reset my password?",
+  "The app crashes when I try to upload photos",
+  "What features are included in the pro plan?"
+]
+
+test_inquiries.each do |inquiry|
+  puts "Customer: #{inquiry}"
+  puts "-" * 50
+
+  result = network.run(message: inquiry)
+
+  # Show classification
+  if result.context[:classifier]
+    puts "Classification: #{result.context[:classifier].last_text_content}"
+  end
+
+  # Show specialist response
+  if result.value.is_a?(RobotLab::RobotResult)
+    puts "Handled by: #{result.value.robot_name}"
+    puts "Response: #{result.value.last_text_content[0..200]}..."
+  end
+
+  puts
+  puts "=" * 50
+  puts
+end
+```
+
+## With Context Passing
+
+```ruby
+# Enhanced version with additional context
+
+class ContextAwareClassifier < RobotLab::Robot
+  def call(result)
+    robot_result = run(**extract_run_context(result))
+
+    # Store classification in context for specialist
+    new_result = result
+      .with_context(@name.to_sym, robot_result)
+      .with_context(:classification, robot_result.last_text_content.strip)
+      .with_context(:original_message, result.context[:run_params][:message])
+      .continue(robot_result)
+
+    category = robot_result.last_text_content.to_s.downcase
+    case category
+    when /billing/ then new_result.activate(:billing_agent)
+    when /technical/ then new_result.activate(:tech_agent)
+    else new_result.activate(:general_agent)
+    end
+  end
+end
+
+# Specialist can access shared context
+class BillingAgent < RobotLab::Robot
+  def call(result)
+    # Access context from classifier
+    classification = result.context[:classification]
+    original_message = result.context[:original_message]
+
+    robot_result = run(
+      **extract_run_context(result),
+      classification: classification,
+      customer_message: original_message
+    )
+
+    result.with_context(@name.to_sym, robot_result).continue(robot_result)
+  end
+end
+```
+
+## Per-Task Configuration
+
+```ruby
+# Tasks with individual context and tools
+network = RobotLab.create_network(name: "support") do
+  task :classifier, classifier, depends_on: :none
+  task :billing_agent, billing_agent,
+       context: { department: "billing", escalation_level: 2 },
+       tools: [RefundTool, InvoiceTool],
+       depends_on: :optional
+  task :tech_agent, tech_agent,
+       context: { department: "technical" },
+       mcp: [FilesystemServer],
+       depends_on: :optional
+end
+```
+
+## Pipeline Pattern
+
+```ruby
+# Sequential processing pipeline
+network = RobotLab.create_network(name: "document_processor") do
+  task :extract, extractor, depends_on: :none
+  task :analyze, analyzer, depends_on: [:extract]
+  task :format, formatter, depends_on: [:analyze]
+end
+
+result = network.run(message: "Process this document")
+puts result.value.last_text_content
+```
+
+## Parallel Analysis Pattern
+
+```ruby
+# Fan-out / fan-in pattern
+network = RobotLab.create_network(name: "multi_analysis", concurrency: :threads) do
+  task :prepare, preparer, depends_on: :none
+
+  # These run in parallel
+  task :sentiment, sentiment_analyzer, depends_on: [:prepare]
+  task :entities, entity_extractor, depends_on: [:prepare]
+  task :keywords, keyword_extractor, depends_on: [:prepare]
+
+  # Waits for all three
+  task :summarize, summarizer, depends_on: [:sentiment, :entities, :keywords]
+end
+
+result = network.run(message: "Analyze this text")
+
+# Access parallel results
+puts "Sentiment: #{result.context[:sentiment].last_text_content}"
+puts "Entities: #{result.context[:entities].last_text_content}"
+puts "Keywords: #{result.context[:keywords].last_text_content}"
+puts "Summary: #{result.value.last_text_content}"
+```
+
+## Conditional Halting
+
+```ruby
+class ValidatorRobot < RobotLab::Robot
+  def call(result)
+    robot_result = run(**extract_run_context(result))
+
+    if robot_result.last_text_content.include?("INVALID")
+      # Halt the pipeline early
+      result.halt(robot_result)
+    else
+      result.with_context(@name.to_sym, robot_result).continue(robot_result)
+    end
+  end
+end
+
+network = RobotLab.create_network(name: "validated_pipeline") do
+  task :validate, validator, depends_on: :none
+  task :process, processor, depends_on: [:validate]  # Only runs if not halted
+end
+
+result = network.run(message: "Process this")
+if result.halted?
+  puts "Validation failed: #{result.value.last_text_content}"
+else
+  puts "Processing complete: #{result.value.last_text_content}"
+end
+```
+
+## Running
+
+```bash
+export ANTHROPIC_API_KEY="your-key"
+ruby examples/customer_service.rb
+```
+
+## Key Concepts
+
+1. **SimpleFlow Pipeline**: DAG-based execution with dependency management
+2. **Optional Tasks**: Activated dynamically based on classification
+3. **Robot#call**: Custom routing logic in classifier robots
+4. **Context Flow**: Data passed through `result.context`
+5. **Parallel Execution**: Tasks with same dependencies run concurrently
+6. **Per-Task Configuration**: Each task can have its own context, tools, and MCP servers
+
+## See Also
+
+- [Creating Networks Guide](../guides/creating-networks.md)
+- [Network Orchestration](../architecture/network-orchestration.md)
+- [API Reference: Network](../api/core/network.md)

data/docs/examples/rails-application.md

@@ -0,0 +1,420 @@
+# Rails Application
+
+Full Rails integration with Action Cable and background jobs.
+
+## Overview
+
+This example demonstrates integrating RobotLab into a Rails application with real-time streaming via Action Cable, background job processing, and persistent conversation history.
+
+## Setup
+
+### 1. Add to Gemfile
+
+```ruby
+# Gemfile
+gem "robot_lab"
+```
+
+### 2. Run Generator
+
+```bash
+rails generate robot_lab:install
+```
+
+This creates:
+
+- `config/initializers/robot_lab.rb`
+- `app/robots/` directory
+- Database migrations for history
+
+### 3. Run Migrations
+
+```bash
+rails db:migrate
+```
+
+## Configuration
+
+```ruby
+# config/initializers/robot_lab.rb
+
+RobotLab.configure do |config|
+  config.default_model = ENV.fetch("LLM_MODEL", "claude-sonnet-4")
+
+  # Enable logging in development
+  config.logger = Rails.logger if Rails.env.development?
+end
+```
+
+## Models
+
+```ruby
+# app/models/conversation_thread.rb
+class ConversationThread < ApplicationRecord
+  belongs_to :user
+  has_many :messages, class_name: "ConversationMessage", dependent: :destroy
+
+  validates :external_id, presence: true, uniqueness: true
+
+  def self.find_or_create_for(user:, external_id: nil)
+    external_id ||= SecureRandom.uuid
+    find_or_create_by!(user: user, external_id: external_id)
+  end
+end
+
+# app/models/conversation_message.rb
+class ConversationMessage < ApplicationRecord
+  belongs_to :thread, class_name: "ConversationThread"
+
+  validates :role, presence: true
+  validates :content, presence: true
+
+  scope :ordered, -> { order(:position) }
+
+  def to_robot_result
+    RobotLab::RobotResult.from_hash(
+      robot_name: robot_name,
+      input: input,
+      output: output
+    )
+  end
+end
+```
+
+## Robot Definitions
+
+```ruby
+# app/robots/support_robot.rb
+class SupportRobot
+  def self.build
+    RobotLab.build do
+      name "support"
+      description "Customer support assistant"
+
+      template <<~PROMPT
+        You are a helpful customer support assistant for our company.
+        Be friendly, professional, and thorough in your responses.
+        If you need to look up information, use the available tools.
+      PROMPT
+
+      tool :get_user_info do
+        description "Get information about the current user"
+
+        handler do |state:, **_|
+          user_id = state.data[:user_id]
+          user = User.find(user_id)
+
+          {
+            name: user.name,
+            email: user.email,
+            plan: user.subscription&.plan || "free",
+            member_since: user.created_at.to_date.to_s
+          }
+        rescue ActiveRecord::RecordNotFound
+          { error: "User not found" }
+        end
+      end
+
+      tool :get_orders do
+        description "Get user's recent orders"
+        parameter :limit, type: :integer, default: 5
+
+        handler do |limit:, state:, **_|
+          user_id = state.data[:user_id]
+          orders = Order.where(user_id: user_id)
+                       .order(created_at: :desc)
+                       .limit(limit)
+
+          orders.map do |order|
+            {
+              id: order.external_id,
+              status: order.status,
+              total: order.total.to_f,
+              created_at: order.created_at.iso8601
+            }
+          end
+        end
+      end
+
+      tool :create_ticket do
+        description "Create a support ticket"
+        parameter :subject, type: :string, required: true
+        parameter :description, type: :string, required: true
+        parameter :priority, type: :string, enum: %w[low medium high], default: "medium"
+
+        handler do |subject:, description:, priority:, state:, **_|
+          ticket = SupportTicket.create!(
+            user_id: state.data[:user_id],
+            subject: subject,
+            description: description,
+            priority: priority
+          )
+
+          {
+            success: true,
+            ticket_id: ticket.external_id,
+            message: "Ticket created successfully"
+          }
+        rescue => e
+          { success: false, error: e.message }
+        end
+      end
+    end
+  end
+end
+```
+
+## Network Configuration
+
+```ruby
+# app/robots/support_network.rb
+class SupportNetwork
+  def self.build
+    RobotLab.create_network do
+      name "support_network"
+      default_model "claude-sonnet-4"
+
+      history RobotLab::History::ActiveRecordAdapter.new(
+        thread_model: ConversationThread,
+        result_model: ConversationMessage
+      ).to_config
+
+      add_robot SupportRobot.build
+    end
+  end
+end
+```
+
+## Service Object
+
+```ruby
+# app/services/chat_service.rb
+class ChatService
+  def initialize(user:, thread_id: nil)
+    @user = user
+    @thread_id = thread_id
+    @network = SupportNetwork.build
+  end
+
+  def call(message:, &streaming_callback)
+    user_message = build_message(message)
+    state = build_state(user_message)
+
+    result = @network.run(state: state, user_id: @user.id) do |event|
+      streaming_callback&.call(event)
+    end
+
+    {
+      thread_id: result.state.thread_id,
+      response: extract_response(result),
+      messages: result.new_results
+    }
+  end
+
+  private
+
+  def build_message(content)
+    if @thread_id
+      RobotLab::UserMessage.new(content, thread_id: @thread_id)
+    else
+      content
+    end
+  end
+
+  def build_state(message)
+    RobotLab.create_state(
+      message: message,
+      data: { user_id: @user.id }
+    )
+  end
+
+  def extract_response(result)
+    result.last_result&.output&.find { |m| m.is_a?(RobotLab::TextMessage) }&.content
+  end
+end
+```
+
+## Controller
+
+```ruby
+# app/controllers/api/chats_controller.rb
+module Api
+  class ChatsController < ApplicationController
+    before_action :authenticate_user!
+
+    def create
+      service = ChatService.new(
+        user: current_user,
+        thread_id: params[:thread_id]
+      )
+
+      result = service.call(message: params[:message])
+
+      render json: {
+        thread_id: result[:thread_id],
+        response: result[:response]
+      }
+    end
+  end
+end
+```
+
+## Action Cable Integration
+
+```ruby
+# app/channels/chat_channel.rb
+class ChatChannel < ApplicationCable::Channel
+  def subscribed
+    stream_for current_user
+  end
+
+  def receive(data)
+    ChatJob.perform_later(
+      user_id: current_user.id,
+      thread_id: data["thread_id"],
+      message: data["message"]
+    )
+  end
+end
+
+# app/jobs/chat_job.rb
+class ChatJob < ApplicationJob
+  queue_as :default
+
+  def perform(user_id:, thread_id:, message:)
+    user = User.find(user_id)
+
+    service = ChatService.new(user: user, thread_id: thread_id)
+
+    service.call(message: message) do |event|
+      case event.type
+      when :text_delta
+        broadcast_to_user(user, type: "text", content: event.text)
+      when :tool_call
+        broadcast_to_user(user, type: "tool", name: event.name)
+      when :complete
+        broadcast_to_user(user, type: "complete")
+      end
+    end
+  end
+
+  private
+
+  def broadcast_to_user(user, data)
+    ChatChannel.broadcast_to(user, data)
+  end
+end
+```
+
+## Frontend (Stimulus)
+
+```javascript
+// app/javascript/controllers/chat_controller.js
+import { Controller } from "@hotwired/stimulus"
+import { createConsumer } from "@rails/actioncable"
+
+export default class extends Controller {
+  static targets = ["messages", "input", "response"]
+
+  connect() {
+    this.consumer = createConsumer()
+    this.channel = this.consumer.subscriptions.create("ChatChannel", {
+      received: (data) => this.handleMessage(data)
+    })
+  }
+
+  disconnect() {
+    this.channel?.unsubscribe()
+  }
+
+  send() {
+    const message = this.inputTarget.value.trim()
+    if (!message) return
+
+    this.appendMessage("user", message)
+    this.inputTarget.value = ""
+
+    // Create response container
+    this.currentResponse = document.createElement("div")
+    this.currentResponse.className = "message assistant"
+    this.messagesTarget.appendChild(this.currentResponse)
+
+    this.channel.send({
+      message: message,
+      thread_id: this.threadId
+    })
+  }
+
+  handleMessage(data) {
+    switch (data.type) {
+      case "text":
+        this.currentResponse.textContent += data.content
+        break
+      case "tool":
+        // Show tool indicator
+        break
+      case "complete":
+        this.threadId = data.thread_id
+        break
+    }
+  }
+
+  appendMessage(role, content) {
+    const div = document.createElement("div")
+    div.className = `message ${role}`
+    div.textContent = content
+    this.messagesTarget.appendChild(div)
+  }
+}
+```
+
+## View
+
+```erb
+<!-- app/views/chats/show.html.erb -->
+<div data-controller="chat">
+  <div class="messages" data-chat-target="messages">
+    <!-- Messages appear here -->
+  </div>
+
+  <form data-action="submit->chat#send">
+    <input type="text"
+           data-chat-target="input"
+           placeholder="Type a message..."
+           autocomplete="off">
+    <button type="submit">Send</button>
+  </form>
+</div>
+```
+
+## Running
+
+```bash
+# Install dependencies
+bundle install
+yarn install
+
+# Setup database
+rails db:migrate
+
+# Set API key
+export ANTHROPIC_API_KEY="your-key"
+
+# Start server
+bin/dev
+```
+
+## Key Concepts
+
+1. **Robot Classes**: Encapsulate robot definitions
+2. **Network Classes**: Configure multi-robot networks
+3. **Service Objects**: Handle business logic
+4. **Action Cable**: Real-time streaming to browser
+5. **Background Jobs**: Non-blocking processing
+6. **History Persistence**: ActiveRecord integration
+
+## See Also
+
+- [Rails Integration Guide](../guides/rails-integration.md)
+- [Streaming Guide](../guides/streaming.md)
+- [History Guide](../guides/history.md)