robot_lab 0.3.0 → 0.5.0

data/examples/07_network_memory.rb

@@ -1,313 +0,0 @@
-#!/usr/bin/env ruby
-# frozen_string_literal: true
-
-# Example 7: Network Memory with Concurrent Robots
-#
-# Demonstrates the reactive shared memory system where:
-# - Multiple robots run concurrently and write to shared memory
-# - Robots can wait for values written by other robots
-# - Subscriptions provide real-time notifications of memory changes
-# - Network broadcast sends messages to all robots
-#
-# Architecture:
-#   ┌─────────────────────────────────────────────────────────────┐
-#   │                    PARALLEL ANALYSIS                         │
-#   │                                                              │
-#   │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
-#   │  │  Sentiment  │  │  Entities   │  │  Keywords   │         │
-#   │  │  Analyzer   │  │  Extractor  │  │  Extractor  │         │
-#   │  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘         │
-#   │         │                │                │                 │
-#   │         ▼                ▼                ▼                 │
-#   │  memory.set(       memory.set(      memory.set(            │
-#   │   :sentiment)       :entities)       :keywords)            │
-#   │         │                │                │                 │
-#   │         └────────────────┼────────────────┘                 │
-#   │                          ▼                                  │
-#   │  ┌──────────────────────────────────────────────────────┐  │
-#   │  │                  SHARED MEMORY                        │  │
-#   │  │  { sentiment: {...}, entities: {...}, keywords: {...} │  │
-#   │  └──────────────────────────────────────────────────────┘  │
-#   │                          │                                  │
-#   │                          ▼                                  │
-#   │  ┌──────────────────────────────────────────────────────┐  │
-#   │  │                   Synthesizer                         │  │
-#   │  │    memory.get(:sentiment, :entities, :keywords,       │  │
-#   │  │               wait: true)                             │  │
-#   │  └──────────────────────────────────────────────────────┘  │
-#   │                                                              │
-#   └─────────────────────────────────────────────────────────────┘
-#
-# Usage:
-#   ruby examples/07_network_memory.rb
-
-require_relative "common"
-require "json"
-
-banner "Network Memory with Concurrent Robots"
-
-# -----------------------------------------------------------------------------
-# Custom Robot Classes that Write to Shared Memory
-# -----------------------------------------------------------------------------
-
-# Base class for analysis robots that write results to memory
-class AnalysisRobot < RobotLab::Robot
-  def initialize(memory_key:, **opts)
-    super(**opts)
-    @memory_key = memory_key
-  end
-
-  def call(result)
-    run_context = extract_run_context(result)
-    network_memory = run_context.delete(:network_memory)
-    message = run_context.delete(:message)
-
-    robot_result = run(message, network_memory: network_memory, **run_context)
-
-    # Parse the JSON response and write to shared memory
-    if network_memory
-      content = robot_result.reply.to_s
-
-      # Set writer before writing to memory
-      network_memory.current_writer = @name
-
-      begin
-        parsed = JSON.parse(content)
-        network_memory.set(@memory_key, parsed)
-        puts "  [#{@name}] Wrote JSON to memory[:#{@memory_key}]"
-      rescue JSON::ParserError
-        # If not valid JSON, store the raw text
-        network_memory.set(@memory_key, content)
-        puts "  [#{@name}] Wrote text to memory[:#{@memory_key}]"
-      end
-    end
-
-    result
-      .with_context(@name.to_sym, robot_result)
-      .continue(robot_result)
-  end
-end
-
-# Synthesizer robot that reads from shared memory and synthesizes results
-class SynthesizerRobot < RobotLab::Robot
-  def call(result)
-    run_context = extract_run_context(result)
-    network_memory = run_context.delete(:network_memory)
-    message = run_context.delete(:message)
-
-    puts "  [#{@name}] Reading analysis results from memory..."
-
-    if network_memory
-      # Read results from memory - they should already be there since
-      # SimpleFlow ensures our dependencies completed first
-      sentiment = network_memory.get(:sentiment)
-      entities = network_memory.get(:entities)
-      keywords = network_memory.get(:keywords)
-
-      puts "  [#{@name}] Got sentiment: #{sentiment.nil? ? 'nil' : 'present'}"
-      puts "  [#{@name}] Got entities: #{entities.nil? ? 'nil' : 'present'}"
-      puts "  [#{@name}] Got keywords: #{keywords.nil? ? 'nil' : 'present'}"
-
-      # Format for the template
-      run_context[:sentiment] = format_for_template(sentiment)
-      run_context[:entities] = format_for_template(entities)
-      run_context[:keywords] = format_for_template(keywords)
-    else
-      run_context[:sentiment] = "Not available"
-      run_context[:entities] = "Not available"
-      run_context[:keywords] = "Not available"
-    end
-
-    robot_result = run(message, network_memory: network_memory, **run_context)
-
-    result
-      .with_context(@name.to_sym, robot_result)
-      .continue(robot_result)
-  end
-
-  private
-
-  def format_for_template(value)
-    case value
-    when Hash, Array
-      JSON.pretty_generate(value)
-    when nil
-      "Not available"
-    else
-      value.to_s
-    end
-  end
-end
-
-# -----------------------------------------------------------------------------
-# Create the Robots
-# -----------------------------------------------------------------------------
-
-sentiment_robot = AnalysisRobot.new(
-  name: "sentiment_analyzer",
-  template: :sentiment_analyzer,
-  memory_key: :sentiment,
-  **llm_opts
-)
-
-entity_robot = AnalysisRobot.new(
-  name: "entity_extractor",
-  template: :entity_extractor,
-  memory_key: :entities,
-  **llm_opts
-)
-
-keyword_robot = AnalysisRobot.new(
-  name: "keyword_extractor",
-  template: :keyword_extractor,
-  memory_key: :keywords,
-  **llm_opts
-)
-
-synthesizer = SynthesizerRobot.new(
-  name: "synthesizer",
-  template: :synthesizer,
-  **llm_opts
-)
-
-# -----------------------------------------------------------------------------
-# Create the Network with Shared Memory
-# -----------------------------------------------------------------------------
-
-network = RobotLab.create_network(name: "parallel_analysis") do
-  # Three analysis robots run in parallel (all depend on nothing)
-  task :sentiment, sentiment_robot, depends_on: :none
-  task :entities, entity_robot, depends_on: :none
-  task :keywords, keyword_robot, depends_on: :none
-
-  # Synthesizer waits for all three to complete
-  task :synthesize, synthesizer, depends_on: [:sentiment, :entities, :keywords]
-end
-
-# -----------------------------------------------------------------------------
-# Set Up Memory Subscriptions (for monitoring)
-# -----------------------------------------------------------------------------
-
-puts "Setting up memory subscriptions for monitoring..."
-puts
-
-# Note: In concurrent execution, change.writer may be unreliable due to race
-# conditions. For production use, consider including writer info in the value.
-network.memory.subscribe(:sentiment, :entities, :keywords) do |change|
-  value_preview = case change.value
-                  when Hash then change.value.keys.join(", ")
-                  when String then change.value[0..50]
-                  else change.value.class.name
-                  end
-  puts "  [MONITOR] Memory[:#{change.key}] updated with keys: #{value_preview}"
-end
-
-# -----------------------------------------------------------------------------
-# Set Up Broadcast Handler
-# -----------------------------------------------------------------------------
-
-network.on_broadcast do |message|
-  puts "  [BROADCAST] #{message[:payload][:event]}: #{message[:payload][:details]}"
-end
-
-# -----------------------------------------------------------------------------
-# Run the Network
-# -----------------------------------------------------------------------------
-
-sample_text = <<~TEXT
-  Apple Inc. announced today that CEO Tim Cook will be presenting the new iPhone 15
-  at their headquarters in Cupertino, California on September 12th, 2024.
-  Industry analysts are extremely excited about the new features, though some
-  consumer advocates have expressed concerns about the expected price increase.
-  Samsung and Google are reportedly preparing competitive responses for later this year.
-TEXT
-
-puts "Network structure:"
-puts network.visualize
-puts
-hr
-puts "Input text:"
-puts sample_text.strip
-hr
-puts
-
-# Send a broadcast before starting
-network.broadcast(event: "analysis_started", details: "Beginning parallel analysis")
-
-puts "Running parallel analysis..."
-puts
-start_time = Time.now
-
-result = network.run(message: sample_text)
-
-elapsed = Time.now - start_time
-puts
-hr
-puts "Analysis complete in #{elapsed.round(2)} seconds"
-hr
-
-# Send completion broadcast
-network.broadcast(event: "analysis_complete", details: "All robots finished")
-
-# -----------------------------------------------------------------------------
-# Display Results
-# -----------------------------------------------------------------------------
-
-
-section "Final Synthesis"
-
-if result.value.is_a?(RobotLab::RobotResult)
-  puts result.value.reply
-end
-
-
-section "Memory State"
-
-# Show what's in shared memory
-memory = network.memory
-puts "Sentiment: #{memory.get(:sentiment)&.to_json}"
-puts
-puts "Entities: #{memory.get(:entities)&.to_json}"
-puts
-puts "Keywords: #{memory.get(:keywords)&.to_json}"
-
-# -----------------------------------------------------------------------------
-# Demonstrate Blocking Wait (without pipeline dependencies)
-# -----------------------------------------------------------------------------
-
-
-section "Demonstrating Blocking Wait"
-
-# Create a fresh memory for this demo
-demo_memory = RobotLab::Memory.new(network_name: "wait_demo")
-
-# Simulate a concurrent scenario where one thread waits for another
-puts "Starting writer thread (will write after 1 second)..."
-puts "Starting reader thread (will wait for value)..."
-
-reader_result = nil
-writer_done = false
-
-reader = Thread.new do
-  start = Time.now
-  puts "  [reader] Waiting for :delayed_result..."
-  value = demo_memory.get(:delayed_result, wait: 10)
-  elapsed = Time.now - start
-  reader_result = value
-  puts "  [reader] Got value after #{elapsed.round(2)}s: #{value}"
-end
-
-writer = Thread.new do
-  sleep 1
-  demo_memory.set(:delayed_result, { status: "complete", data: [1, 2, 3] })
-  writer_done = true
-  puts "  [writer] Wrote :delayed_result to memory"
-end
-
-# Wait for both threads
-writer.join
-reader.join
-
-puts
-puts "Blocking wait demonstration complete!"
-puts "Reader received: #{reader_result.inspect}"

data/examples/08_llm_config.rb

@@ -1,162 +0,0 @@
-#!/usr/bin/env ruby
-# frozen_string_literal: true
-
-# Example 8: LLM Configuration via MywayConfig
-#
-# Demonstrates how RobotLab uses MywayConfig for environment-specific
-# configuration (similar to Rails database.yml).
-#
-# Configuration is loaded from multiple sources in priority order:
-#   1. Bundled defaults (lib/robot_lab/config/defaults.yml)
-#   2. Environment-specific overrides (development, test, production)
-#   3. XDG user config (~/.config/robot_lab/config.yml)
-#   4. Project config (./config/robot_lab.yml)
-#   5. Environment variables (ROBOT_LAB_*)
-#   6. Template front matter (model, temperature, etc. in .md YAML header)
-#   7. Constructor parameters (model:, temperature:, etc. passed to Robot.new)
-#   8. with_* methods (runtime chaining, e.g. robot.with_temperature(0.9))
-#   9. Run-time context (kwargs passed to robot.run that re-render the template)
-#
-# Environment is determined by ROBOT_LAB_ENV, RAILS_ENV, or RACK_ENV.
-#
-# Environment variable examples:
-#   ROBOT_LAB_RUBY_LLM__MODEL=qwen/qwen3.8-27b
-#   ROBOT_LAB_RUBY_LLM__REQUEST_TIMEOUT=180
-#   LMS_API_BASE=http://localhost:1234/v1
-#
-# Usage:
-#   ruby examples/08_llm_config.rb
-#   ROBOT_LAB_ENV=test ruby examples/08_llm_config.rb
-#   ROBOT_LAB_ENV=production ruby examples/08_llm_config.rb
-
-require_relative "common"
-
-# =============================================================================
-# Demonstration
-# =============================================================================
-
-banner "LLM Configuration via MywayConfig"
-
-# --- Gather environment from the user via AskUser ---
-ask = RobotLab::AskUser.new
-env = ask.call(
-  "question" => "Which environment should the demo run in?",
-  "choices"  => %w[development test production],
-  "default"  => ENV['ROBOT_LAB_ENV'] || ENV['RAILS_ENV'] || ENV['RACK_ENV'] || "development"
-)
-puts
-
-# Display configuration values (hiding sensitive keys)
-config = RobotLab.config
-
-puts "Core Settings:"
-puts "  max_iterations:     #{config.max_iterations}"
-puts "  streaming_enabled:  #{config.streaming_enabled}"
-puts "  template_path:      #{config.template_path || '(default)'}"
-puts
-
-puts "RubyLLM Settings:"
-puts "  model:              #{config.ruby_llm.model}"
-puts "  provider:           #{config.ruby_llm.provider}"
-puts "  request_timeout:    #{config.ruby_llm.request_timeout}s"
-puts "  max_retries:        #{config.ruby_llm.max_retries}"
-puts "  log_level:          #{config.ruby_llm.log_level}"
-
-# Show where the LLM traffic actually goes
-puts "  lms_api_base:       #{LMS_API_BASE}"
-puts "  (local inference — no API key in play)"
-puts
-
-section "Configuration Hierarchy (highest priority first)"
-puts
-puts "  Per-Robot (override global settings for a specific robot):"
-puts "  11. Run-time context:      kwargs to robot.run re-render template"
-puts "  10. with_* methods:        robot.with_temperature(0.9).ask(...)"
-puts "   9. Constructor params:    Robot.new(model: ..., temperature: ...)"
-puts "   8. Template front matter: model, temperature, etc. in .md YAML header"
-puts "   7. Robot RunConfig:       config: passed to Robot constructor"
-puts
-puts "  Network/Task (shared defaults for a group of robots):"
-puts "   6. Task RunConfig:        config: passed to task() in network"
-puts "   5. Network RunConfig:     config: passed to create_network()"
-puts
-puts "  Global (apply to all robots unless overridden):"
-puts "   4. Environment variables: ROBOT_LAB_RUBY_LLM__MODEL, etc."
-puts "   3. Project config:        ./config/robot_lab.yml"
-puts "   2. User config:           ~/.config/robot_lab/config.yml"
-puts "   1. Bundled defaults:      lib/robot_lab/config/defaults.yml + env overrides"
-
-section "RunConfig: Shared Operational Defaults"
-
-shared = RobotLab::RunConfig.new(model: LLM[:default].model, temperature: 0.5)
-puts "  shared = RunConfig.new(model: #{LLM[:default].model.inspect}, temperature: 0.5)"
-puts "  shared.to_h => #{shared.to_h.inspect}"
-puts
-puts "  Note: RunConfig carries no `provider` field, so an LM Studio model still"
-puts "  needs provider: passed to each robot alongside the shared config."
-puts
-
-creative = RobotLab::RunConfig.new(temperature: 0.9)
-merged = shared.merge(creative)
-puts "  creative = RunConfig.new(temperature: 0.9)"
-puts "  merged = shared.merge(creative)"
-puts "  merged.to_h => #{merged.to_h.inspect}"
-puts "  (model inherited from shared, temperature overridden by creative)"
-puts
-
-# Create a robot using the configuration
-robot = RobotLab.build(
-  **llm_opts,
-  name: "config_demo",
-  template: :llm_config_demo,
-  local_tools: [RobotLab::AskUser],
-  # These are TEMPLATE parameters, not robot kwargs — the template renders
-  # them into its prompt text.
-  context: {
-    environment: env,
-    model:       LLM[:default].model,
-    provider:    LLM[:default].provider
-  }
-)
-
-puts "Running robot with #{env} configuration..."
-puts "Model: #{robot.model}"
-puts
-
-# Run the robot
-result = robot.run(
-  "Briefly explain how environment-specific LLM configuration works " \
-  "and why it's useful."
-)
-
-# Display the result
-puts "Response:"
-result.output.each do |message|
-  puts message.content if message.respond_to?(:content)
-end
-
-puts <<~FOOTER
-
-  #{"=" * 70}
-  Configuration demonstrated successfully!
-
-  Configuration flows through three layers:
-    Global (MywayConfig): YAML defaults, env overrides, XDG, env vars
-    Network/Task (RunConfig): shared defaults for groups of robots
-    Per-Robot: RunConfig, template front matter, constructor params, with_*
-
-  RunConfig lets you express shared defaults that flow through the hierarchy:
-    shared = RobotLab::RunConfig.new(model: #{LLM[:default].model.inspect}, temperature: 0.5)
-    network = RobotLab.create_network(name: "team", config: shared) { ... }
-    robot = RobotLab.build(name: "bot", config: shared, temperature: 0.9)
-
-  Example environment variable overrides:
-    ROBOT_LAB_RUBY_LLM__MODEL=#{LLM[:default].model}
-    ROBOT_LAB_RUBY_LLM__REQUEST_TIMEOUT=180
-    LMS_API_BASE=http://localhost:1234/v1
-
-  Try running with different environments:
-    ROBOT_LAB_ENV=test ruby examples/08_llm_config.rb
-    ROBOT_LAB_ENV=production ruby examples/08_llm_config.rb
-  #{"=" * 70}
-FOOTER