RAAF Core Guide

agent = RAAF::Agent.new(
  name: "DataAnalyst",
  instructions: "You are a data analyst...",
  model: "gpt-4o"
)

name: "CustomerService"  # Used for handoffs and tracing
  instructions: "...",
  model: "gpt-4o"
)

# Before: Vague and ineffective
agent = RAAF::Agent.new(
  instructions: "Be a helpful customer service agent"
)

# After: Specific and effective
agent = RAAF::Agent.new(
  name: "CustomerServicePro",
  instructions: <<~INSTRUCTIONS
    You are a senior customer service representative for TechCorp.

    Your personality:

    - Professional but warm (like a helpful colleague, not a robot)
    - Patient with frustrated customers
    - Solution-oriented rather than problem-focused

    Your approach:

    1. Acknowledge the customer's concern first
    2. Ask clarifying questions if needed
    3. Provide specific solutions, not generic advice
    4. Always offer a next step

    Example good response:
    "I understand how frustrating that must be. Let me help you resolve this. 
    Can you tell me which version of the software you're using?"

    Example bad response:
    "Have you tried turning it off and on again?"

    Never:

    - Blame the customer
    - Say "that's not possible" (say "let me find a solution" instead)
    - End without offering next steps
  INSTRUCTIONS,
  model: "gpt-4o"
)

# OpenAI models
agent = RAAF::Agent.new(model: "gpt-4o")        # Premium: high quality, higher cost
agent = RAAF::Agent.new(model: "gpt-4o-mini")   # Balanced: good quality, lower cost

# Anthropic models
agent = RAAF::Agent.new(model: "claude-3-5-sonnet-20241022")  # Excellent reasoning

# Groq models
agent = RAAF::Agent.new(model: "mixtral-8x7b-32768")  # Fast inference, good for simple tasks

# LiteLLM universal access
agent = RAAF::Agent.new(model: "bedrock/claude-3")  # Access to AWS Bedrock models

agent = RAAF::Agent.new(
  name: "Assistant",
  instructions: "You are helpful",
  model: "gpt-4o",
  temperature: 0.7,        # Control randomness
  max_tokens: 1000,        # Limit response length
  top_p: 0.9              # Nucleus sampling
)

agent = RAAF::Agent.new(
  name: "Assistant",
  instructions: "You are helpful",
  model: "gpt-4o"
)

runner = RAAF::Runner.new(agent: agent)
result = runner.run("Hello!")

puts result.messages.last[:content]

runner = RAAF::Runner.new(
  agent: agent,
  max_turns: 10,           # Limit conversation turns
  stream: false,           # Enable/disable streaming
  parallel: true           # Enable parallel tool execution
)

result = runner.run("Hello!")

# Access messages
result.messages.each do |message|
  puts "#{message[:role]}: #{message[:content]}"
end

# Check completion status
puts "Success: #{result.success?}"
puts "Agent: #{result.agent.name}"

# Usage statistics
puts "Tokens used: #{result.usage}"

runner = RAAF::Runner.new(agent: agent)

# Turn 1
result1 = runner.run("My name is Alice")
puts result1.messages.last[:content]

# Turn 2 - agent remembers Alice's name
result2 = runner.run("What's my name?")
puts result2.messages.last[:content]

def get_weather(location)
  # Simulate weather API call
  "Weather in #{location}: 72°F, sunny"
end

agent = RAAF::Agent.new(
  name: "WeatherBot",
  instructions: "Help users get weather information",
  model: "gpt-4o"
)

agent.add_tool(method(:get_weather))

def send_email(to:, subject:, body:, priority: 'normal')
  # Send email logic
  {
    status: 'sent',
    message_id: 'msg_123',
    timestamp: Time.now
  }
end

agent.add_tool(method(:send_email))

# Agent can now call:
# send_email(to: "[email protected]", subject: "Hello", body: "Hi there!")

class DatabaseTool
  def initialize(connection)
    @db = connection
  end

  def call(query:, limit: 100)
    results = @db.execute(query).limit(limit)
    {
      rows: results.to_a,
      count: results.count,
      execution_time: @db.last_execution_time
    }
  end
end

db_tool = DatabaseTool.new(database_connection)
agent.add_tool(db_tool.method(:call))

get_time = ->(timezone: 'UTC') do
  Time.now.in_time_zone(timezone).strftime("%I:%M %p %Z")
end

agent.add_tool(get_time)

def book_flight(
  origin:,           # Required parameter
  destination:,      # Required parameter  
  departure_date:,   # Required parameter
  passengers: 1,     # Optional with default
  class_type: 'economy'  # Optional with default
)
  # Implementation
end

# Books a flight for the specified passengers
# @param origin [String] Departure airport code (e.g., 'LAX')
# @param destination [String] Arrival airport code (e.g., 'JFK')
# @param departure_date [String] Departure date in YYYY-MM-DD format
# @param passengers [Integer] Number of passengers (default: 1)
# @param class_type [String] Seat class: 'economy', 'business', or 'first'
# @return [Hash] Flight booking confirmation details
def book_flight(origin:, destination:, departure_date:, passengers: 1, class_type: 'economy')
  # Implementation
end

def get_stock_price(symbol:)
  begin
    api = StockAPI.new
    price_data = api.get_current_price(symbol.upcase)

    {
      symbol: symbol.upcase,
      price: price_data[:current_price],
      currency: price_data[:currency],
      last_updated: price_data[:timestamp]
    }
  rescue StockAPI::InvalidSymbolError
    { error: "Invalid stock symbol: #{symbol}" }
  rescue StockAPI::APIError => e
    { error: "Unable to fetch stock data: #{e.message}" }
  rescue => e
    { error: "Unexpected error: #{e.message}" }
  end
end

agent.add_tool(method(:get_stock_price))

def analyze_large_dataset(dataset_url:)
  # Start background job
  job_id = DataAnalysisJob.perform_async(dataset_url)

  {
    job_id: job_id,
    status: 'started',
    estimated_completion: 5.minutes.from_now,
    status_url: "/api/jobs/#{job_id}/status"
  }
end

def check_job_status(job_id:)
  job = DataAnalysisJob.find(job_id)

  {
    job_id: job_id,
    status: job.status,
    progress: job.progress_percentage,
    result: job.completed? ? job.result : nil,
    error: job.failed? ? job.error_message : nil
  }
end

agent.add_tool(method(:analyze_large_dataset))
agent.add_tool(method(:check_job_status))

require 'raaf'

# Fast but forgetful
memory_manager = RAAF::Memory::MemoryManager.new(
  store: RAAF::Memory::InMemoryStore.new(
    capacity: 10_000,  # Max conversations
    ttl: 3600          # Expire after 1 hour
  ),
  max_tokens: 4000
)

runner = RAAF::Runner.new(
  agent: agent,
  memory_manager: memory_manager
)

# The improved version we use in production
class ProductionFileStore < RAAF::Memory::FileStore
  def initialize(config)
    super(
      directory: config[:base_dir],
      # Organize by date for easier management
      path_pattern: '%{year}/%{month}/%{day}/%{session_id}.json',
      # Compress old conversations
      compression: :gzip,
      # Encrypt sensitive data
      encryption: {
        algorithm: 'AES-256-GCM',
        key: ENV['CONVERSATION_ENCRYPTION_KEY']
      }
    )
  end

  def store_message(session_id, message)
    # Add metadata for debugging
    message[:stored_at] = Time.now
    message[:server_version] = RAAF::VERSION

    super(session_id, message)

    # Async backup to S3
    BackupWorker.perform_async(session_id) if production?
  end
end

memory_manager = RAAF::Memory::MemoryManager.new(
  store: ProductionFileStore.new(
    base_dir: Rails.root.join('storage/conversations'),
    retention_days: 90  # GDPR compliance
  ),
  max_tokens: 4000
)

# This is where things get interesting
class IntelligentVectorStore < RAAF::Memory::VectorStore
  def initialize
    super(
      # Use OpenAI for embeddings
      embedding_model: 'text-embedding-3-small',

      # PostgreSQL with pgvector for production
      database: {
        adapter: 'postgresql',
        extension: 'vector',
        pool: 25
      },

      # Automatic clustering for similar conversations
      clustering: {
        enabled: true,
        algorithm: 'hnsw',
        min_cluster_size: 5
      }
    )
  end

  def find_similar_conversations(query, limit: 5)
    embedding = generate_embedding(query)

    # Find semantically similar past conversations
    results = database.execute(<<-SQL)
      SELECT session_id, message, 
             1 - (embedding <=> '#{embedding}') as similarity
      FROM conversation_messages
      WHERE embedding <=> '#{embedding}' < 0.3
      ORDER BY embedding <=> '#{embedding}'
      LIMIT #{limit}
    SQL

    # Use similar conversations as context
    results.map do |row|
      {
        session_id: row['session_id'],
        message: row['message'],
        similarity: row['similarity'],
        learned_context: extract_key_facts(row['message'])
      }
    end
  end
end

# Now your AI can say: "I see you had a similar issue last month..."
memory_manager = RAAF::Memory::MemoryManager.new(
  store: IntelligentVectorStore.new,
  max_tokens: 8000,

  # Hybrid approach: recent + relevant
  retrieval_strategy: :hybrid,
  recent_messages: 10,
  relevant_messages: 5
)

# Here's how we help clients choose
def recommend_memory_store(requirements)
  case
  when requirements[:conversations_per_day] < 100 && 
       requirements[:persistence_needed] == false
    :in_memory

  when requirements[:compliance_requirements].any? ||
       requirements[:audit_trail_needed]
    :file_store  # Easier to audit and backup

  when requirements[:conversations_per_day] > 10_000 ||
       requirements[:semantic_search_needed]
    :vector_store

  else
    :file_store  # Safe default
  end
end

# The naive approach we all start with
memory_manager = RAAF::Memory::MemoryManager.new(
  store: store,
  max_tokens: 4000,
  pruning_strategy: :sliding_window,

  # Keep at least this many recent messages
  min_messages_to_keep: 4,

  # Always preserve system message
  preserve_messages: [:system, :first_user]
)

# What actually happens in memory:
# [System] You are a helpful assistant...
# [User] Help me plan a wedding (removed)
# [AI] I'd be happy to help! (removed)
# [User] Budget is $50k (removed)
# [AI] Great! Let's start... (removed)
# [User] Actually make it $30k  <- Kept
# [AI] No problem, adjusting... <- Kept
# [User] What about flowers?     <- Kept
# [AI] For a $30k budget...      <- Kept

# The sophisticated approach that actually works
class ProductionSummarizer
  def initialize
    @memory_manager = RAAF::Memory::MemoryManager.new(
      store: store,
      max_tokens: 4000,
      pruning_strategy: :summarization,

      # Summarize when we hit 80% capacity
      summarization_threshold: 0.8,

      # Use fast, cheap model for summaries
      summary_model: 'gpt-4o-mini',

      # But use smart prompts
      summary_prompt: <<~PROMPT
        Summarize this conversation, preserving:

        1. Key decisions made
        2. Important numbers (budgets, dates, quantities)
        3. User preferences and constraints
        4. Current task status
        5. Unresolved questions

        Format: Brief bullet points
        Max length: 500 tokens
      PROMPT
    )
  end

  def smart_summarize(messages)
    # Group messages into logical chunks
    chunks = group_by_topic(messages)

    # Summarize each chunk separately
    summaries = chunks.map do |chunk|
      {
        topic: chunk[:topic],
        summary: summarize_chunk(chunk[:messages]),
        key_facts: extract_facts(chunk[:messages])
      }
    end

    # Combine into structured summary
    {
      conversation_summary: combine_summaries(summaries),
      key_facts: summaries.flat_map { |s| s[:key_facts] },
      open_topics: extract_open_questions(messages)
    }
  end
end

# The approach that feels like magic when it works
class SemanticMemoryManager
  def initialize
    @memory = RAAF::Memory::MemoryManager.new(
      store: RAAF::Memory::VectorStore.new,
      max_tokens: 4000,
      pruning_strategy: :semantic_similarity
    )

    # Track topic evolution
    @topic_embeddings = []
  end

  def select_relevant_context(current_query)
    # Get embedding for current query
    query_embedding = embed(current_query)

    # Find messages similar to current topic
    relevant_messages = @memory.search(
      embedding: query_embedding,
      threshold: 0.7,
      limit: 20
    )

    # But also keep temporal context
    recent_messages = @memory.recent(5)

    # And critical markers
    important_messages = @memory.tagged(:important)

    # Intelligently merge
    merge_contexts(
      relevant_messages,
      recent_messages,
      important_messages
    )
  end

  def tag_important_messages(message)
    # Auto-tag messages with key information
    tags = []
    tags << :budget if message =~ /\$\d+|budget|cost/i
    tags << :deadline if message =~ /by|before|deadline|due/i
    tags << :decision if message =~ /decided|agreed|confirmed/i
    tags << :problem if message =~ /issue|problem|broken|error/i

    @memory.tag_message(message, tags) if tags.any?
  end
end

# What we actually use in production
class HybridMemoryStrategy
  def initialize
    @strategies = {
      recent: SlidingWindow.new(last_n: 10),
      important: ImportanceScorer.new(threshold: 0.8),
      semantic: SemanticMatcher.new(top_k: 5),
      summary: ChunkSummarizer.new(chunk_size: 50)
    }
  end

  def build_context(current_input, conversation_history)
    context_budget = 4000  # tokens
    selected_messages = []

    # Layer 1: Always include system prompt (200 tokens)
    selected_messages << conversation_history[:system]
    context_budget -= 200

    # Layer 2: Recent messages (up to 1000 tokens)
    recent = @strategies[:recent].select(conversation_history)
    recent_tokens = count_tokens(recent)
    if recent_tokens <= 1000
      selected_messages.concat(recent)
      context_budget -= recent_tokens
    else
      # Summarize older recent messages
      summary = @strategies[:summary].summarize(recent[0...-5])
      selected_messages << summary
      selected_messages.concat(recent[-5..-1])
      context_budget -= count_tokens(summary) + count_tokens(recent[-5..-1])
    end

    # Layer 3: Semantically relevant (up to 1500 tokens)
    relevant = @strategies[:semantic].find_relevant(
      current_input, 
      conversation_history
    )
    relevant_tokens = count_tokens(relevant)
    if relevant_tokens <= context_budget - 500  # Leave room for response
      selected_messages.concat(relevant)
    else
      # Take most relevant that fit
      relevant.each do |msg|
        msg_tokens = count_tokens(msg)
        if context_budget - msg_tokens >= 500
          selected_messages << msg
          context_budget -= msg_tokens
        end
      end
    end

    # Layer 4: Fill remaining space with important messages
    important = @strategies[:important].rank(conversation_history)
    important.each do |msg|
      msg_tokens = count_tokens(msg)
      if context_budget - msg_tokens >= 500
        selected_messages << msg
        context_budget -= msg_tokens
      end
    end

    # Return organized context
    organize_chronologically(selected_messages)
  end
end

# Access conversation history
memory = runner.memory_manager.get_memory(session_id: 'user_123')
puts "Messages: #{memory.messages.count}"
puts "Total tokens: #{memory.token_count}"

# Clear memory
runner.memory_manager.clear_memory(session_id: 'user_123')

# Add custom memory
runner.memory_manager.add_memory(
  session_id: 'user_123',
  role: 'system',
  content: 'User prefers technical explanations'
)

User: "What's the weather?"
AI: "It's currently 72 degrees Fahrenheit in San Francisco with partly 
cloudy skies and a gentle breeze from the west at about 10 mph."
Our parsing code: *crashes trying to extract temperature*

require 'raaf'

# Define response schema
WeatherSchema = {
  type: 'object',
  properties: {
    location: { type: 'string' },
    temperature: { type: 'number' },
    conditions: { type: 'string' },
    humidity: { type: 'number' },
    wind_speed: { type: 'number' }
  },
  required: ['location', 'temperature', 'conditions']
}

agent = RAAF::Agent.new(
  name: "WeatherBot",
  instructions: "Provide weather information in the specified format",
  model: "gpt-4o",
  response_format: WeatherSchema
)

runner = RAAF::Runner.new(agent: agent)
result = runner.run("What's the weather in San Francisco?")

# Result will be structured JSON matching the schema
weather_data = JSON.parse(result.messages.last[:content])
puts "Temperature: #{weather_data['temperature']}°F"

PersonSchema = {
  type: 'object',
  properties: {
    name: { 
      type: 'string',
      minLength: 1,
      maxLength: 100
    },
    email: { 
      type: 'string',
      format: 'email'
    },
    phone: {
      type: 'string',
      pattern: '^\\+?[1-9]\\d{1,14}$'  # International phone format
    },
    role: {
      type: 'string',
      enum: ['admin', 'user', 'guest']
    }
  },
  required: ['name', 'email']
}

PricingSchema = {
  type: 'object',
  properties: {
    base_price: {
      type: 'number',
      minimum: 0,
      maximum: 1000000
    },
    discount_percent: {
      type: 'number',
      minimum: 0,
      maximum: 100
    },
    quantity: {
      type: 'integer',
      minimum: 1,
      maximum: 10000
    },
    is_taxable: {
      type: 'boolean'
    }
  },
  required: ['base_price', 'quantity']
}

ShoppingCartSchema = {
  type: 'object',
  properties: {
    items: {
      type: 'array',
      minItems: 1,
      maxItems: 50,
      items: {
        type: 'object',
        properties: {
          product_id: { type: 'string' },
          quantity: { type: 'integer', minimum: 1 }
        },
        required: ['product_id', 'quantity']
      }
    },
    total_items: {
      type: 'integer',
      minimum: 1
    }
  },
  required: ['items', 'total_items']
}

TransactionSchema = {
  type: 'object',
  properties: {
    transaction_id: { type: 'string' },
    amount: {
      type: 'number',
      minimum: 0.01,
      maximum: 1000000
    },
    currency: {
      type: 'string',
      enum: ['USD', 'EUR', 'GBP', 'JPY']
    },
    transaction_type: {
      type: 'string',
      enum: ['credit', 'debit', 'transfer']
    },
    merchant: {
      type: 'object',
      properties: {
        name: { type: 'string' },
        category: { type: 'string' },
        location: { type: 'string' }
      },
      required: ['name', 'category']
    },
    timestamp: {
      type: 'string',
      format: 'date-time'
    },
    status: {
      type: 'string',
      enum: ['pending', 'completed', 'failed', 'cancelled']
    }
  },
  required: ['transaction_id', 'amount', 'currency', 'transaction_type', 'timestamp', 'status']
}

# Usage
agent = RAAF::Agent.new(
  name: "TransactionProcessor",
  instructions: "Process financial transactions and extract structured data",
  model: "gpt-4o",
  response_format: TransactionSchema
)

result = runner.run("Process this transaction: $250.00 payment to Amazon on 2024-01-15")
transaction = JSON.parse(result.messages.last[:content])

SupportTicketSchema = {
  type: 'object',
  properties: {
    ticket_id: { type: 'string' },
    customer_info: {
      type: 'object',
      properties: {
        name: { type: 'string' },
        email: { type: 'string', format: 'email' },
        tier: { type: 'string', enum: ['free', 'premium', 'enterprise'] }
      },
      required: ['name', 'email', 'tier']
    },
    issue: {
      type: 'object',
      properties: {
        category: {
          type: 'string',
          enum: ['billing', 'technical', 'account', 'feature_request']
        },
        priority: {
          type: 'string',
          enum: ['low', 'medium', 'high', 'critical']
        },
        description: { type: 'string' },
        affected_features: {
          type: 'array',
          items: { type: 'string' }
        }
      },
      required: ['category', 'priority', 'description']
    },
    resolution: {
      type: 'object',
      properties: {
        status: {
          type: 'string',
          enum: ['open', 'in_progress', 'resolved', 'closed']
        },
        estimated_resolution_time: { type: 'string' },
        assigned_agent: { type: 'string' }
      },
      required: ['status']
    }
  },
  required: ['ticket_id', 'customer_info', 'issue', 'resolution']
}

# Usage for ticket classification
agent = RAAF::Agent.new(
  name: "TicketClassifier",
  instructions: "Classify and structure customer support tickets",
  model: "gpt-4o",
  response_format: SupportTicketSchema
)

result = runner.run("Customer [email protected] (premium) says: 'My dashboard won't load and I can't see my analytics. This is urgent for tomorrow's board meeting.'")
ticket = JSON.parse(result.messages.last[:content])

class StructuredOutputHandler
  def self.safe_parse(agent_response, schema)
    begin
      # Parse the JSON response
      parsed_data = JSON.parse(agent_response)

      # Validate against schema
      validation_errors = validate_schema(parsed_data, schema)

      if validation_errors.any?
        {
          success: false,
          errors: validation_errors,
          raw_response: agent_response
        }
      else
        {
          success: true,
          data: parsed_data
        }
      end

    rescue JSON::ParserError => e
      {
        success: false,
        errors: ["Invalid JSON format: #{e.message}"],
        raw_response: agent_response
      }
    end
  end

  private

  def self.validate_schema(data, schema)
    errors = []

    # Check required fields
    schema[:required]&.each do |field|
      unless data.key?(field.to_s)
        errors << "Missing required field: #{field}"
      end
    end

    # Check data types
    schema[:properties]&.each do |field, constraints|
      next unless data.key?(field.to_s)

      value = data[field.to_s]
      expected_type = constraints[:type]

      unless validate_type(value, expected_type)
        errors << "Field '#{field}' should be #{expected_type}, got #{value.class}"
      end
    end

    errors
  end

  def self.validate_type(value, expected_type)
    case expected_type
    when 'string'
      value.is_a?(String)
    when 'number'
      value.is_a?(Numeric)
    when 'integer'
      value.is_a?(Integer)
    when 'boolean'
      value.is_a?(TrueClass) || value.is_a?(FalseClass)
    when 'array'
      value.is_a?(Array)
    when 'object'
      value.is_a?(Hash)
    else
      false
    end
  end
end

# Usage
result = runner.run("Extract customer data from this text...")
response = result.messages.last[:content]

parsed_result = StructuredOutputHandler.safe_parse(response, CustomerSchema)

if parsed_result[:success]
  customer_data = parsed_result[:data]
  puts "Customer: #{customer_data['name']}"
else
  puts "Parsing failed: #{parsed_result[:errors].join(', ')}"
  # Handle fallback or retry logic
end

# Tip 1: Use concise schemas for faster generation
CompactSchema = {
  type: 'object',
  properties: {
    status: { type: 'string' },
    result: { type: 'string' }
  },
  required: ['status']
}

# Tip 2: Cache schema validation
class SchemaCache
  @cache = {}

  def self.validate(data, schema)
    schema_key = schema.hash
    validator = @cache[schema_key] ||= build_validator(schema)
    validator.validate(data)
  end
end

# Tip 3: Use progressive schema complexity
BasicContactSchema = {
  type: 'object',
  properties: {
    name: { type: 'string' },
    email: { type: 'string' }
  },
  required: ['name', 'email']
}

# Extend only when needed
DetailedContactSchema = BasicContactSchema.merge({
  properties: BasicContactSchema[:properties].merge({
    phone: { type: 'string' },
    address: { type: 'object' },
    preferences: { type: 'array' }
  })
})

# Start with the core entities
BasicOrderSchema = {
  type: 'object',
  properties: {
    order_id: { type: 'string' },
    customer: { type: 'object' },
    items: { type: 'array' },
    total: { type: 'number' }
  },
  required: ['order_id', 'customer', 'items', 'total']
}

# Define customer object structure
CustomerObject = {
  type: 'object',
  properties: {
    customer_id: { type: 'string' },
    name: { type: 'string' },
    email: { type: 'string', format: 'email' },
    phone: { type: 'string' },
    address: {
      type: 'object',
      properties: {
        street: { type: 'string' },
        city: { type: 'string' },
        state: { type: 'string' },
        postal_code: { type: 'string' },
        country: { type: 'string', enum: ['US', 'CA', 'GB', 'AU'] }
      },
      required: ['street', 'city', 'state', 'postal_code', 'country']
    },
    billing_address: {
      type: 'object',
      properties: {
        same_as_shipping: { type: 'boolean' },
        street: { type: 'string' },
        city: { type: 'string' },
        state: { type: 'string' },
        postal_code: { type: 'string' },
        country: { type: 'string', enum: ['US', 'CA', 'GB', 'AU'] }
      },
      required: ['same_as_shipping']
    }
  },
  required: ['customer_id', 'name', 'email', 'address']
}

# Define item structure with variants and metadata
ItemObject = {
  type: 'object',
  properties: {
    product_id: { type: 'string' },
    name: { type: 'string' },
    category: { type: 'string' },
    quantity: { type: 'integer', minimum: 1, maximum: 100 },
    unit_price: { type: 'number', minimum: 0 },
    discount: {
      type: 'object',
      properties: {
        type: { type: 'string', enum: ['percentage', 'fixed'] },
        value: { type: 'number', minimum: 0 },
        reason: { type: 'string' }
      }
    },
    variants: {
      type: 'array',
      items: {
        type: 'object',
        properties: {
          name: { type: 'string' },
          value: { type: 'string' }
        },
        required: ['name', 'value']
      }
    },
    metadata: {
      type: 'object',
      properties: {
        weight: { type: 'number' },
        dimensions: {
          type: 'object',
          properties: {
            length: { type: 'number' },
            width: { type: 'number' },
            height: { type: 'number' }
          }
        },
        sku: { type: 'string' },
        barcode: { type: 'string' }
      }
    }
  },
  required: ['product_id', 'name', 'quantity', 'unit_price']
}

# The full enterprise-grade order schema
CompleteOrderSchema = {
  type: 'object',
  properties: {
    order_id: { type: 'string' },
    order_number: { type: 'string' },
    customer: CustomerObject,
    items: {
      type: 'array',
      minItems: 1,
      maxItems: 50,
      items: ItemObject
    },
    pricing: {
      type: 'object',
      properties: {
        subtotal: { type: 'number', minimum: 0 },
        tax: { type: 'number', minimum: 0 },
        shipping: { type: 'number', minimum: 0 },
        discount: { type: 'number', minimum: 0 },
        total: { type: 'number', minimum: 0 }
      },
      required: ['subtotal', 'tax', 'shipping', 'total']
    },
    payment: {
      type: 'object',
      properties: {
        method: { type: 'string', enum: ['credit_card', 'debit_card', 'paypal', 'bank_transfer'] },
        status: { type: 'string', enum: ['pending', 'authorized', 'captured', 'failed'] },
        transaction_id: { type: 'string' },
        amount: { type: 'number', minimum: 0 }
      },
      required: ['method', 'status', 'amount']
    },
    fulfillment: {
      type: 'object',
      properties: {
        method: { type: 'string', enum: ['standard', 'express', 'overnight', 'pickup'] },
        carrier: { type: 'string' },
        tracking_number: { type: 'string' },
        estimated_delivery: { type: 'string', format: 'date' },
        status: { type: 'string', enum: ['pending', 'processing', 'shipped', 'delivered', 'cancelled'] }
      },
      required: ['method', 'status']
    },
    timestamps: {
      type: 'object',
      properties: {
        created_at: { type: 'string', format: 'date-time' },
        updated_at: { type: 'string', format: 'date-time' },
        confirmed_at: { type: 'string', format: 'date-time' }
      },
      required: ['created_at', 'updated_at']
    },
    metadata: {
      type: 'object',
      properties: {
        source: { type: 'string', enum: ['web', 'mobile', 'api', 'phone'] },
        referrer: { type: 'string' },
        session_id: { type: 'string' },
        user_agent: { type: 'string' },
        ip_address: { type: 'string' },
        notes: { type: 'string' }
      }
    }
  },
  required: ['order_id', 'customer', 'items', 'pricing', 'payment', 'fulfillment', 'timestamps']
}

# Usage
agent = RAAF::Agent.new(
  name: "OrderProcessor",
  instructions: "Process complex orders with full details for enterprise integration",
  model: "gpt-4o",
  response_format: CompleteOrderSchema
)

result = runner.run("Process this order: Customer John Smith wants 2 iPhone 15 Pro cases and 1 screen protector, shipping to 123 Main St, Boston, MA 02101")
order = JSON.parse(result.messages.last[:content])

# Schema that changes based on other properties
ConditionalSchema = {
  type: 'object',
  properties: {
    notification_type: { type: 'string', enum: ['email', 'sms', 'push'] },
    recipient: { type: 'string' },
    content: { type: 'string' }
  },
  required: ['notification_type', 'recipient', 'content'],

  # Conditional validation
  if: { properties: { notification_type: { const: 'email' } } },
  then: {
    properties: {
      recipient: { type: 'string', format: 'email' },
      subject: { type: 'string' },
      html_content: { type: 'string' }
    },
    required: ['subject']
  },

  else: {
    if: { properties: { notification_type: { const: 'sms' } } },
    then: {
      properties: {
        recipient: { type: 'string', pattern: '^\\+?[1-9]\\d{1,14}$' },
        message: { type: 'string', maxLength: 160 }
      },
      required: ['message']
    }
  }
}

# Schema that handles different object types
PolymorphicSchema = {
  type: 'object',
  properties: {
    events: {
      type: 'array',
      items: {
        type: 'object',
        properties: {
          event_type: { type: 'string', enum: ['user_action', 'system_event', 'error'] },
          timestamp: { type: 'string', format: 'date-time' },
          data: { type: 'object' }
        },
        required: ['event_type', 'timestamp', 'data'],

        # Different data structure based on event_type
        if: { properties: { event_type: { const: 'user_action' } } },
        then: {
          properties: {
            data: {
              type: 'object',
              properties: {
                user_id: { type: 'string' },
                action: { type: 'string' },
                page: { type: 'string' },
                session_id: { type: 'string' }
              },
              required: ['user_id', 'action']
            }
          }
        },

        else: {
          if: { properties: { event_type: { const: 'system_event' } } },
          then: {
            properties: {
              data: {
                type: 'object',
                properties: {
                  service: { type: 'string' },
                  operation: { type: 'string' },
                  status: { type: 'string' },
                  duration_ms: { type: 'number' }
                },
                required: ['service', 'operation', 'status']
              }
            }
          }
        }
      }
    }
  },
  required: ['events']
}

# Schema that references itself (like file system trees)
RecursiveSchema = {
  type: 'object',
  properties: {
    name: { type: 'string' },
    type: { type: 'string', enum: ['file', 'directory'] },
    size: { type: 'number' },
    children: {
      type: 'array',
      items: { '$ref': '#' }  # References the root schema
    }
  },
  required: ['name', 'type'],

  # Conditional requirements
  if: { properties: { type: { const: 'file' } } },
  then: { required: ['size'] },
  else: { required: ['children'] }
}

class SchemaBuilder
  def self.build_progressive(base_schema, extensions = {})
    result = base_schema.deep_dup

    extensions.each do |key, extension|
      case key
      when :add_properties
        result[:properties].merge!(extension)
      when :add_required
        result[:required] ||= []
        result[:required].concat(extension)
      when :add_constraints
        extension.each do |prop, constraints|
          result[:properties][prop]&.merge!(constraints)
        end
      end
    end

    result
  end
end

# Usage
base_schema = {
  type: 'object',
  properties: {
    name: { type: 'string' },
    email: { type: 'string' }
  },
  required: ['name']
}

# Add complexity progressively
enhanced_schema = SchemaBuilder.build_progressive(base_schema, {
  add_properties: {
    phone: { type: 'string' },
    address: { type: 'object' }
  },
  add_required: ['email'],
  add_constraints: {
    email: { format: 'email' },
    name: { minLength: 2, maxLength: 50 }
  }
})

# Reusable schema components
AddressSchema = {
  type: 'object',
  properties: {
    street: { type: 'string' },
    city: { type: 'string' },
    state: { type: 'string' },
    postal_code: { type: 'string' },
    country: { type: 'string' }
  },
  required: ['street', 'city', 'state', 'postal_code', 'country']
}

PersonSchema = {
  type: 'object',
  properties: {
    name: { type: 'string' },
    email: { type: 'string', format: 'email' },
    address: AddressSchema
  },
  required: ['name', 'email', 'address']
}

# Compose into larger schemas
CompanySchema = {
  type: 'object',
  properties: {
    name: { type: 'string' },
    employees: {
      type: 'array',
      items: PersonSchema
    },
    headquarters: AddressSchema
  },
  required: ['name', 'employees', 'headquarters']
}

# Bad: Scattered related fields
BadSchema = {
  properties: {
    first_name: { type: 'string' },
    last_name: { type: 'string' },
    email: { type: 'string' },
    phone: { type: 'string' },
    street: { type: 'string' },
    city: { type: 'string' }
  }
}

# Good: Grouped related fields
GoodSchema = {
  properties: {
    personal_info: {
      type: 'object',
      properties: {
        first_name: { type: 'string' },
        last_name: { type: 'string' }
      }
    },
    contact_info: {
      type: 'object',
      properties: {
        email: { type: 'string' },
        phone: { type: 'string' }
      }
    },
    address: {
      type: 'object',
      properties: {
        street: { type: 'string' },
        city: { type: 'string' }
      }
    }
  }
}

# Clear, consistent naming
NamingSchema = {
  properties: {
    user_id: { type: 'string' },          # Not: id, userId, user_identifier
    created_at: { type: 'string' },       # Not: created, createdAt, creation_time
    is_active: { type: 'boolean' },       # Not: active, status, enabled
    email_address: { type: 'string' },    # Not: email, mail, e_mail
    phone_number: { type: 'string' },     # Not: phone, tel, telephone
    order_items: { type: 'array' },       # Not: items, products, line_items
    total_amount: { type: 'number' },     # Not: total, amount, price
    payment_method: { type: 'string' },   # Not: payment, method, pay_method
    shipping_address: { type: 'object' }, # Not: address, ship_to, destination
    billing_address: { type: 'object' }   # Not: bill_to, payment_address
  }
}

# Most providers now support native structured outputs
agent = RAAF::Agent.new(
  name: "DataExtractor",
  instructions: "Extract structured data",
  model: "gpt-4o",
  response_format: schema,
  strict: true  # Enable strict schema validation
)

runner = RAAF::Runner.new(agent: agent)

begin
  result = runner.run("Extract customer data from this text...")
  data = JSON.parse(result.messages.last[:content])

  # Data is guaranteed to match schema
  process_customer_data(data)

rescue RAAF::StructuredOutput::ValidationError => e
  puts "Schema validation failed: #{e.message}"
  puts "Validation errors: #{e.errors}"
end

class SchemaValidator
  def self.validate(data, schema)
    errors = []

    # Check required fields
    missing_fields = check_required_fields(data, schema)
    errors.concat(missing_fields) if missing_fields.any?

    # Check data types
    type_errors = check_data_types(data, schema)
    errors.concat(type_errors) if type_errors.any?

    # Check constraints
    constraint_errors = check_constraints(data, schema)
    errors.concat(constraint_errors) if constraint_errors.any?

    # Check business rules
    business_errors = check_business_rules(data, schema)
    errors.concat(business_errors) if business_errors.any?

    {
      valid: errors.empty?,
      errors: errors,
      data: data
    }
  end

  private

  def self.check_required_fields(data, schema)
    errors = []
    required_fields = schema.dig(:required) || []

    required_fields.each do |field|
      unless data.key?(field.to_s) || data.key?(field.to_sym)
        errors << "Missing required field: #{field}"
      end
    end

    errors
  end

  def self.check_data_types(data, schema)
    errors = []
    properties = schema.dig(:properties) || {}

    properties.each do |field, constraints|
      next unless data.key?(field.to_s) || data.key?(field.to_sym)

      value = data[field.to_s] || data[field.to_sym]
      expected_type = constraints[:type]

      unless valid_type?(value, expected_type)
        errors << "Field '#{field}' should be #{expected_type}, got #{value.class}"
      end
    end

    errors
  end

  def self.check_constraints(data, schema)
    errors = []
    properties = schema.dig(:properties) || {}

    properties.each do |field, constraints|
      next unless data.key?(field.to_s) || data.key?(field.to_sym)

      value = data[field.to_s] || data[field.to_sym]

      # Check string constraints
      if constraints[:type] == 'string'
        errors.concat(validate_string_constraints(field, value, constraints))
      end

      # Check numeric constraints
      if constraints[:type] == 'number' || constraints[:type] == 'integer'
        errors.concat(validate_numeric_constraints(field, value, constraints))
      end

      # Check array constraints
      if constraints[:type] == 'array'
        errors.concat(validate_array_constraints(field, value, constraints))
      end

      # Check enum constraints
      if constraints[:enum]
        unless constraints[:enum].include?(value)
          errors << "Field '#{field}' must be one of #{constraints[:enum].join(', ')}, got '#{value}'"
        end
      end
    end

    errors
  end

  def self.validate_string_constraints(field, value, constraints)
    errors = []

    if constraints[:minLength] && value.length < constraints[:minLength]
      errors << "Field '#{field}' must be at least #{constraints[:minLength]} characters"
    end

    if constraints[:maxLength] && value.length > constraints[:maxLength]
      errors << "Field '#{field}' must be at most #{constraints[:maxLength]} characters"
    end

    if constraints[:pattern] && !value.match(Regexp.new(constraints[:pattern]))
      errors << "Field '#{field}' must match pattern #{constraints[:pattern]}"
    end

    if constraints[:format] == 'email' && !value.match(/\A[^@]+@[^@]+\.[^@]+\z/)
      errors << "Field '#{field}' must be a valid email address"
    end

    errors
  end

  def self.validate_numeric_constraints(field, value, constraints)
    errors = []

    if constraints[:minimum] && value < constraints[:minimum]
      errors << "Field '#{field}' must be at least #{constraints[:minimum]}"
    end

    if constraints[:maximum] && value > constraints[:maximum]
      errors << "Field '#{field}' must be at most #{constraints[:maximum]}"
    end

    if constraints[:type] == 'integer' && !value.is_a?(Integer)
      errors << "Field '#{field}' must be an integer"
    end

    errors
  end

  def self.validate_array_constraints(field, value, constraints)
    errors = []

    if constraints[:minItems] && value.length < constraints[:minItems]
      errors << "Field '#{field}' must have at least #{constraints[:minItems]} items"
    end

    if constraints[:maxItems] && value.length > constraints[:maxItems]
      errors << "Field '#{field}' must have at most #{constraints[:maxItems]} items"
    end

    # Validate array items
    if constraints[:items]
      value.each_with_index do |item, index|
        item_errors = validate(item, constraints[:items])
        if item_errors[:errors].any?
          errors << "Item #{index} in field '#{field}': #{item_errors[:errors].join(', ')}"
        end
      end
    end

    errors
  end

  def self.check_business_rules(data, schema)
    errors = []

    # Custom business rule validation
    if schema[:business_rules]
      schema[:business_rules].each do |rule|
        unless rule[:validator].call(data)
          errors << rule[:message]
        end
      end
    end

    errors
  end

  def self.valid_type?(value, expected_type)
    case expected_type
    when 'string'
      value.is_a?(String)
    when 'number'
      value.is_a?(Numeric)
    when 'integer'
      value.is_a?(Integer)
    when 'boolean'
      value.is_a?(TrueClass) || value.is_a?(FalseClass)
    when 'array'
      value.is_a?(Array)
    when 'object'
      value.is_a?(Hash)
    when 'null'
      value.nil?
    else
      false
    end
  end
end

# Schema with business rules
OrderSchema = {
  type: 'object',
  properties: {
    customer_id: { type: 'string' },
    items: {
      type: 'array',
      items: {
        type: 'object',
        properties: {
          product_id: { type: 'string' },
          quantity: { type: 'integer', minimum: 1 },
          price: { type: 'number', minimum: 0 }
        }
      }
    },
    total: { type: 'number', minimum: 0 }
  },
  required: ['customer_id', 'items', 'total'],

  # Custom business rules
  business_rules: [
    {
      validator: ->(data) {
        # Total must equal sum of item prices
        calculated_total = data['items'].sum { |item| item['price'] * item['quantity'] }
        (data['total'] - calculated_total).abs < 0.01
      },
      message: "Total must equal sum of item prices"
    },
    {
      validator: ->(data) {
        # Maximum 20 items per order
        data['items'].length <= 20
      },
      message: "Orders cannot exceed 20 items"
    },
    {
      validator: ->(data) {
        # No duplicate products
        product_ids = data['items'].map { |item| item['product_id'] }
        product_ids.uniq.length == product_ids.length
      },
      message: "Order cannot contain duplicate products"
    }
  ]
}

# Usage
result = runner.run("Process this order...")
response = result.messages.last[:content]
data = JSON.parse(response)

validation_result = SchemaValidator.validate(data, OrderSchema)

if validation_result[:valid]
  process_order(data)
else
  puts "Validation failed:"
  validation_result[:errors].each { |error| puts "  - #{error}" }
end

class StreamingValidator
  def initialize(schema)
    @schema = schema
    @partial_data = {}
    @errors = []
  end

  def validate_chunk(chunk)
    @partial_data.merge!(chunk)

    # Validate what we have so far
    current_errors = validate_partial(@partial_data, @schema)

    {
      valid_so_far: current_errors.empty?,
      errors: current_errors,
      can_continue: can_continue_parsing?(current_errors)
    }
  end

  def finalize
    # Final validation of complete data
    SchemaValidator.validate(@partial_data, @schema)
  end

  private

  def validate_partial(data, schema)
    # Only validate fields that are present
    # Don't fail on missing required fields yet
    errors = []

    schema[:properties]&.each do |field, constraints|
      next unless data.key?(field.to_s)

      value = data[field.to_s]

      # Validate type
      unless SchemaValidator.valid_type?(value, constraints[:type])
        errors << "Field '#{field}' has invalid type"
      end

      # Validate constraints
      if constraints[:type] == 'string'
        errors.concat(SchemaValidator.validate_string_constraints(field, value, constraints))
      end
    end

    errors
  end

  def can_continue_parsing?(errors)
    # Don't continue if we have fundamental type errors
    !errors.any? { |error| error.include?('invalid type') }
  end
end

class ConditionalValidator
  def self.validate(data, schema)
    errors = []

    # Base validation
    base_errors = SchemaValidator.validate(data, schema)
    errors.concat(base_errors[:errors])

    # Conditional validation
    if schema[:conditional_rules]
      schema[:conditional_rules].each do |rule|
        if rule[:condition].call(data)
          conditional_errors = validate_conditional_schema(data, rule[:then_schema])
          errors.concat(conditional_errors)
        elsif rule[:else_schema]
          conditional_errors = validate_conditional_schema(data, rule[:else_schema])
          errors.concat(conditional_errors)
        end
      end
    end

    {
      valid: errors.empty?,
      errors: errors,
      data: data
    }
  end

  private

  def self.validate_conditional_schema(data, schema)
    result = SchemaValidator.validate(data, schema)
    result[:errors]
  end
end

# Usage
PaymentSchema = {
  type: 'object',
  properties: {
    payment_method: { type: 'string', enum: ['credit_card', 'paypal', 'bank_transfer'] },
    amount: { type: 'number', minimum: 0 }
  },
  required: ['payment_method', 'amount'],

  conditional_rules: [
    {
      condition: ->(data) { data['payment_method'] == 'credit_card' },
      then_schema: {
        type: 'object',
        properties: {
          card_number: { type: 'string', pattern: '^[0-9]{16}$' },
          expiry: { type: 'string', pattern: '^[0-9]{2}/[0-9]{2}$' },
          cvv: { type: 'string', pattern: '^[0-9]{3,4}$' }
        },
        required: ['card_number', 'expiry', 'cvv']
      }
    },
    {
      condition: ->(data) { data['payment_method'] == 'paypal' },
      then_schema: {
        type: 'object',
        properties: {
          paypal_email: { type: 'string', format: 'email' }
        },
        required: ['paypal_email']
      }
    }
  ]
}

class CachedValidator
  def initialize
    @validation_cache = {}
    @schema_cache = {}
  end

  def validate(data, schema)
    # Cache compiled schemas
    schema_key = schema.hash
    compiled_schema = @schema_cache[schema_key] ||= compile_schema(schema)

    # Cache validation results for identical data
    data_key = data.hash
    cache_key = "#{schema_key}_#{data_key}"

    @validation_cache[cache_key] ||= perform_validation(data, compiled_schema)
  end

  private

  def compile_schema(schema)
    # Pre-compile regex patterns, enum sets, etc.
    compiled = schema.deep_dup

    compiled[:properties]&.each do |field, constraints|
      if constraints[:pattern]
        constraints[:compiled_pattern] = Regexp.new(constraints[:pattern])
      end

      if constraints[:enum]
        constraints[:enum_set] = Set.new(constraints[:enum])
      end
    end

    compiled
  end

  def perform_validation(data, compiled_schema)
    # Use compiled patterns for faster validation
    errors = []

    compiled_schema[:properties]&.each do |field, constraints|
      next unless data.key?(field.to_s)

      value = data[field.to_s]

      # Use compiled regex
      if constraints[:compiled_pattern] && !value.match(constraints[:compiled_pattern])
        errors << "Field '#{field}' must match pattern"
      end

      # Use compiled enum set
      if constraints[:enum_set] && !constraints[:enum_set].include?(value)
        errors << "Field '#{field}' must be one of allowed values"
      end
    end

    {
      valid: errors.empty?,
      errors: errors,
      data: data
    }
  end
end

class ValidationErrorRecovery
  def self.attempt_recovery(data, schema, errors)
    recovery_attempts = []

    errors.each do |error|
      case error
      when /Missing required field: (.+)/
        field = $1
        recovery_attempts << attempt_infer_missing_field(data, field, schema)

      when /Field '(.+)' should be (.+), got (.+)/
        field, expected_type, actual_type = $1, $2, $3
        recovery_attempts << attempt_type_conversion(data, field, expected_type)

      when /Field '(.+)' must be at least (\d+) characters/
        field, min_length = $1, $2.to_i
        recovery_attempts << attempt_pad_string(data, field, min_length)

      when /Field '(.+)' must be one of (.+), got '(.+)'/
        field, allowed_values, actual_value = $1, $2, $3
        recovery_attempts << attempt_enum_correction(data, field, allowed_values, actual_value)
      end
    end

    # Apply successful recovery attempts
    recovered_data = data.dup
    recovery_attempts.compact.each do |recovery|
      recovered_data[recovery[:field]] = recovery[:value]
    end

    {
      recovered_data: recovered_data,
      recovery_applied: recovery_attempts.any?(&:present?)
    }
  end

  private

  def self.attempt_infer_missing_field(data, field, schema)
    # Try to infer missing field from context
    case field
    when 'created_at'
      { field: field, value: Time.now.iso8601 }
    when 'status'
      { field: field, value: 'pending' }
    when 'id'
      { field: field, value: SecureRandom.uuid }
    else
      nil
    end
  end

  def self.attempt_type_conversion(data, field, expected_type)
    current_value = data[field]

    case expected_type
    when 'string'
      { field: field, value: current_value.to_s }
    when 'number'
      { field: field, value: current_value.to_f }
    when 'integer'
      { field: field, value: current_value.to_i }
    when 'boolean'
      { field: field, value: !!current_value }
    else
      nil
    end
  end

  def self.attempt_pad_string(data, field, min_length)
    current_value = data[field]
    if current_value.length < min_length
      { field: field, value: current_value.ljust(min_length, '0') }
    else
      nil
    end
  end

  def self.attempt_enum_correction(data, field, allowed_values, actual_value)
    allowed_array = allowed_values.split(', ')

    # Try fuzzy matching
    best_match = allowed_array.min_by do |allowed|
      levenshtein_distance(actual_value.downcase, allowed.downcase)
    end

    if levenshtein_distance(actual_value.downcase, best_match.downcase) <= 2
      { field: field, value: best_match }
    else
      nil
    end
  end

  def self.levenshtein_distance(s1, s2)
    # Simple Levenshtein distance implementation
    return s2.length if s1.empty?
    return s1.length if s2.empty?

    costs = Array.new(s2.length + 1) { |i| i }

    (1..s1.length).each do |i|
      costs[0] = i
      nw = i - 1

      (1..s2.length).each do |j|
        costs[j], nw = [
          costs[j] + 1,
          costs[j - 1] + 1,
          nw + (s1[i - 1] == s2[j - 1] ? 0 : 1)
        ].min, costs[j]
      end
    end

    costs[s2.length]
  end
end

# Same schema works with different providers
schema = { type: 'object', properties: { name: { type: 'string' } } }

# OpenAI - uses native structured outputs
openai_agent = RAAF::Agent.new(
  model: "gpt-4o",
  response_format: schema
)

# Anthropic - uses guided generation
claude_agent = RAAF::Agent.new(
  model: "claude-3-5-sonnet-20241022", 
  response_format: schema
)

# Groq - uses constrained generation
groq_agent = RAAF::Agent.new(
  model: "mixtral-8x7b-32768",
  response_format: schema
)

# Without context - Every interaction starts fresh
user: "I need help with my order"
agent: "Sure! Can you provide your order number?"
user: "It's ORD-12345"
agent: "Thank you. What's your issue?"
user: "I need to change the shipping address"
agent: "What's your new address?"
user: "123 Main St, New York"
agent: "Done! Is there anything else?"
user: "Actually, can you check if there are any other orders?"
agent: "I'd be happy to help! Can you provide your order number?"

# With context - Information persists and accumulates
user: "I need help with my order"
agent: "I'd be happy to help! Can you provide your order number?"
user: "It's ORD-12345"
agent: "Thank you. I can see this is for John Smith, shipping to 456 Oak Ave. What's your issue?"
user: "I need to change the shipping address"
agent: "What's your new address?"
user: "123 Main St, New York"
agent: "I've updated order ORD-12345 to ship to 123 Main St, New York. Is there anything else?"
user: "Actually, can you check if there are any other orders?"
agent: "Looking at your account, I see you have two other orders: ORD-12340 (delivered) and ORD-12342 (processing). Would you like details on either of these?"

# Comprehensive context setup
runner = RAAF::Runner.new(
  agent: agent,
  context_variables: {
    # User identity and preferences
    user_id: 'user_123',
    user_name: 'John Smith',
    user_role: 'premium_customer',
    language: 'en',
    timezone: 'America/New_York',

    # Session information
    session_type: 'support',
    session_id: 'sess_abc123',
    channel: 'web_chat',

    # Business context
    company_id: 'comp_456',
    account_tier: 'enterprise',
    region: 'north_america',

    # Workflow state
    current_step: 'initial_contact',
    escalation_level: 0,
    previous_interactions: 3
  }
)

# Context variables are automatically injected into tools
def get_user_preferences(user_id: nil)
  # user_id is automatically provided from context
  preferences = UserPreferences.find_by(user_id: user_id)

  {
    theme: preferences.theme,
    notification_preferences: preferences.notifications,
    communication_style: preferences.style,
    preferred_channel: preferences.channel
  }
end

def personalize_response(content:, user_id: nil, language: nil, timezone: nil)
  # Multiple context variables injected automatically
  localized_content = I18n.with_locale(language) do
    content.gsub('{timezone}', timezone)
  end

  {
    content: localized_content,
    personalization_applied: true,
    user_id: user_id
  }
end

agent.add_tool(method(:get_user_preferences))
agent.add_tool(method(:personalize_response))