robot_lab 0.0.1 → 0.0.4

data/examples/08_llm_config.rb

@@ -0,0 +1,140 @@
+#!/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__ANTHROPIC_API_KEY=sk-ant-...
+#   ROBOT_LAB_RUBY_LLM__MODEL=gpt-4
+#   ROBOT_LAB_RUBY_LLM__REQUEST_TIMEOUT=180
+#
+# Usage:
+#   ANTHROPIC_API_KEY=your_key ruby examples/08_llm_config.rb
+#   ROBOT_LAB_ENV=test ANTHROPIC_API_KEY=your_key ruby examples/08_llm_config.rb
+#   ROBOT_LAB_ENV=production ANTHROPIC_API_KEY=your_key ruby examples/08_llm_config.rb
+
+# Configure template path before loading (MywayConfig reads env vars on init)
+ENV['ROBOT_LAB_TEMPLATE_PATH'] ||= File.join(__dir__, "prompts")
+
+require_relative "../lib/robot_lab"
+
+# =============================================================================
+# Demonstration
+# =============================================================================
+
+puts "=" * 70
+puts "Example 8: LLM Configuration via MywayConfig"
+puts "=" * 70
+puts
+
+# --- 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 API key status without revealing values
+api_key = config.ruby_llm.anthropic_api_key
+puts "  anthropic_api_key:  #{api_key ? '[SET via config]' : (ENV['ANTHROPIC_API_KEY'] ? '[SET via env]' : '(not set)')}"
+puts
+
+puts "-" * 70
+puts "Configuration hierarchy (highest priority first):"
+puts
+puts "  Per-Robot (override global settings for a specific robot):"
+puts "  9. Run-time context:      kwargs to robot.run re-render template"
+puts "  8. with_* methods:        robot.with_temperature(0.9).ask(...)"
+puts "  7. Constructor params:    Robot.new(model: ..., temperature: ...)"
+puts "  6. Template front matter: model, temperature, etc. in .md YAML header"
+puts
+puts "  Global (apply to all robots unless overridden):"
+puts "  5. Environment variables: ROBOT_LAB_RUBY_LLM__MODEL, etc."
+puts "  4. Project config:        ./config/robot_lab.yml"
+puts "  3. User config:           ~/.config/robot_lab/config.yml"
+puts "  2. Environment overrides: #{env} section in defaults.yml"
+puts "  1. Bundled defaults:      lib/robot_lab/config/defaults.yml"
+puts "-" * 70
+puts
+
+# Create a robot using the configuration
+robot = RobotLab.build(
+  name: "config_demo",
+  template: :llm_config_demo,
+  local_tools: [RobotLab::AskUser],
+  context: {
+    environment: env,
+    model: config.ruby_llm.model,
+    provider: config.ruby_llm.provider.to_s
+  }
+)
+
+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 two layers:
+    Global (MywayConfig): YAML defaults, env overrides, XDG, env vars
+    Per-Robot: template front matter, constructor params, with_* methods
+
+  Example environment variable overrides:
+    ROBOT_LAB_RUBY_LLM__MODEL=gpt-4
+    ROBOT_LAB_RUBY_LLM__REQUEST_TIMEOUT=180
+    ROBOT_LAB_RUBY_LLM__ANTHROPIC_API_KEY=sk-ant-...
+
+  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

data/examples/09_chaining.rb

@@ -0,0 +1,223 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example 9: Robot Chaining & Reconfiguration
+#
+# Demonstrates the Robot API surface for runtime configuration without
+# making any LLM calls. Covers:
+#   - with_* method chaining
+#   - update() for reconfiguration
+#   - to_h introspection (via amazing_print)
+#   - Config diffs between steps (via hashdiff)
+#   - Template front matter config keys
+#   - Constructor params overriding front matter
+#   - Config hierarchy in action
+#   - AskUser tool for gathering template parameters interactively
+#
+# Usage:
+#   bundle exec ruby examples/09_chaining.rb
+
+# Configure template path before loading
+ENV['ROBOT_LAB_TEMPLATE_PATH'] ||= File.join(__dir__, "prompts")
+
+require_relative "../lib/robot_lab"
+require "amazing_print"
+require "hashdiff"
+require "stringio"
+
+# Show a config snapshot and the diff from the previous snapshot.
+# Returns the current hash for use as the next "previous" snapshot.
+def show_config(robot, previous_config = nil)
+  current = robot.to_h
+  ap current
+
+  if previous_config
+    diff = Hashdiff.diff(previous_config, current)
+    if diff.empty?
+      puts "  (no changes to to_h)"
+    else
+      puts
+      puts "  Diff from previous:"
+      diff.each do |change|
+        op, path, *values = change
+        case op
+        when "+"
+          puts "    + #{path}: #{values.first.inspect}"
+        when "-"
+          puts "    - #{path}: #{values.first.inspect}"
+        when "~"
+          puts "    ~ #{path}: #{values.first.inspect} -> #{values.last.inspect}"
+        end
+      end
+    end
+  end
+
+  current
+end
+
+puts "=" * 70
+puts "Example 9: Robot Chaining & Reconfiguration"
+puts "=" * 70
+puts
+
+# =============================================================================
+# Section 1: Template front matter config
+# =============================================================================
+
+puts "--- Section 1: Template Front Matter Config ---"
+puts
+
+# The 'configurable' template sets temperature: 0.3 and max_tokens: 200
+# via YAML front matter. These are applied automatically.
+robot = RobotLab.build(
+  name: "chameleon",
+  template: :configurable,
+  context: { task_type: "analysis" }
+)
+
+puts "Robot created with :configurable template"
+prev = show_config(robot)
+puts
+
+# =============================================================================
+# Section 2: with_* method chaining
+# =============================================================================
+
+puts "--- Section 2: with_* Method Chaining ---"
+puts
+
+# with_* methods return self, enabling fluent chaining.
+# These override whatever the template set.
+robot.with_temperature(0.9)
+
+puts "After chaining with_temperature(0.9):"
+prev = show_config(robot, prev)
+puts
+
+# =============================================================================
+# Section 3: update() for reconfiguration
+# =============================================================================
+
+puts "--- Section 3: update() for Reconfiguration ---"
+puts
+
+# update() can swap the template, model, temperature, and other settings.
+robot.update(template: :assistant, temperature: 0.5)
+
+puts "After update(template: :assistant, temperature: 0.5):"
+prev = show_config(robot, prev)
+puts
+
+# Swap back with context
+robot.update(template: :configurable, context: { task_type: "creative" })
+
+puts "After update(template: :configurable, context: { task_type: 'creative' }):"
+prev = show_config(robot, prev)
+puts
+
+# =============================================================================
+# Section 4: Constructor params override front matter
+# =============================================================================
+
+puts "--- Section 4: Constructor Params Override Front Matter ---"
+puts
+
+# The configurable template sets temperature: 0.3 in front matter.
+# Passing temperature: 0.9 to the constructor overrides it.
+robot2 = RobotLab.build(
+  name: "override_demo",
+  template: :configurable,
+  context: { task_type: "creative" },
+  temperature: 0.9
+)
+
+puts "Template sets temperature: 0.3, constructor passes temperature: 0.9"
+prev2 = show_config(robot2)
+puts
+
+# =============================================================================
+# Section 5: Bare robot with chaining
+# =============================================================================
+
+puts "--- Section 5: Bare Robot with Chaining ---"
+puts
+
+# A bare robot has no template. Configure entirely via chaining.
+bare = RobotLab.build(name: "bare")
+
+puts "Bare robot before chaining:"
+prev_bare = show_config(bare)
+puts
+
+bare
+  .with_instructions("You are a helpful assistant.")
+  .with_temperature(0.5)
+
+puts "After with_instructions(...).with_temperature(0.5):"
+prev_bare = show_config(bare, prev_bare)
+puts
+
+# =============================================================================
+# Section 6: with_template() on an existing robot
+# =============================================================================
+
+puts "--- Section 6: with_template() on Existing Robot ---"
+puts
+
+# You can apply a template to a robot after creation.
+bare.with_template(:helper)
+
+puts "After bare.with_template(:helper):"
+show_config(bare, prev_bare)
+puts
+
+# =============================================================================
+# Section 7: AskUser tool for gathering template parameters
+# =============================================================================
+
+puts "--- Section 7: AskUser for Template Parameters ---"
+puts
+puts "The :configurable template declares `task_type: general` in its front"
+puts "matter. That default is offered to the user — they can accept it by"
+puts "pressing Enter or type something else. Parameters with null values"
+puts "have no default and require user input."
+puts
+
+# Build a robot with AskUser — the template's task_type default ("general")
+# is offered to the user, who can accept or override it.
+interactive = RobotLab.build(
+  name: "interactive_demo",
+  template: :configurable,
+  local_tools: [RobotLab::AskUser]
+)
+
+puts "Robot 'interactive_demo' has AskUser in its tools."
+puts "The template renders with the default: task_type = \"general\""
+puts "When run, the robot can call ask_user to let the user confirm"
+puts "or change the value."
+puts
+
+# Simulate what the user would see (no LLM call needed)
+output = StringIO.new
+demo_tool = RobotLab::AskUser.new(robot: interactive)
+interactive.output = output
+interactive.input  = StringIO.new("2\n")
+
+result = demo_tool.call(
+  "question" => "What type of task should I optimize for?",
+  "choices"  => %w[general analysis creative coding research],
+  "default"  => "general"
+)
+
+puts output.string
+puts "User selected: #{result}"
+puts
+puts "The robot would re-render the template with task_type: \"#{result}\""
+puts "producing: \"You are a precise assistant optimized for #{result} tasks.\""
+puts
+puts "If the user had pressed Enter, the default \"general\" would be kept."
+puts
+
+puts "=" * 70
+puts "All sections completed without any LLM calls."
+puts "=" * 70

data/examples/10_memory.rb

@@ -0,0 +1,331 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example 10: Advanced Memory Operations
+#
+# Demonstrates the Memory API without making any LLM calls. Covers:
+#   - StateProxy for method-style data access
+#   - Key subscriptions with MemoryChange objects
+#   - Pattern subscriptions
+#   - Unsubscribe
+#   - Key enumeration (keys, all_keys, key?)
+#   - Serialization (to_h, from_hash, to_json) with amazing_print
+#   - Serialization round-trip verification with hashdiff
+#   - Clone for isolated copies
+#   - Delete with reserved key protection
+#   - Clear vs reset
+#
+# Usage:
+#   bundle exec ruby examples/10_memory.rb
+
+# Configure template path before loading
+ENV['ROBOT_LAB_TEMPLATE_PATH'] ||= File.join(__dir__, "prompts")
+
+require_relative "../lib/robot_lab"
+require "json"
+require "amazing_print"
+require "hashdiff"
+
+puts "=" * 70
+puts "Example 10: Advanced Memory Operations"
+puts "=" * 70
+puts
+
+# =============================================================================
+# Section 1: StateProxy for method-style access
+# =============================================================================
+
+puts "--- Section 1: StateProxy for Method-Style Access ---"
+puts
+
+memory = RobotLab.create_memory(
+  data: { category: nil, priority: "low" },
+  enable_cache: false
+)
+
+puts "Initial data:"
+ap memory.data.to_h
+puts
+
+# StateProxy allows method-style access to the :data hash
+memory.data.category = "billing"
+
+puts "After memory.data.category = 'billing':"
+ap memory.data.to_h
+puts
+
+# Bracket-style also works
+memory.data[:priority] = "high"
+puts "After memory.data[:priority] = 'high':"
+ap memory.data.to_h
+puts
+
+# =============================================================================
+# Section 2: Subscriptions and MemoryChange
+# =============================================================================
+
+puts "--- Section 2: Subscriptions and MemoryChange ---"
+puts
+
+changes = []
+
+sub_id = memory.subscribe(:status) do |change|
+  changes << change
+end
+
+puts "Subscribed to :status (sub_id: #{sub_id[0..7]}...)"
+
+# Set current_writer so the MemoryChange knows who wrote
+memory.current_writer = "classifier"
+memory.set(:status, "processing")
+
+# Give the async callback time to fire
+sleep 0.1
+
+if changes.any?
+  change = changes.first
+  puts "Change received:"
+  ap change.to_h
+  puts "  created?: #{change.created?}"
+  puts "  updated?: #{change.updated?}"
+end
+
+# Update the same key to see an 'updated' change
+memory.set(:status, "complete")
+sleep 0.1
+
+if changes.size > 1
+  puts
+  puts "Second change (update):"
+  ap changes.last.to_h
+  puts "  created?: #{changes.last.created?}"
+  puts "  updated?: #{changes.last.updated?}"
+end
+puts
+
+# =============================================================================
+# Section 3: Pattern subscriptions
+# =============================================================================
+
+puts "--- Section 3: Pattern Subscriptions ---"
+puts
+
+pattern_changes = []
+
+pattern_sub_id = memory.subscribe_pattern("analysis:*") do |change|
+  pattern_changes << change
+end
+
+puts "Subscribed to pattern 'analysis:*'"
+
+memory.current_writer = "analyst"
+memory.set(:"analysis:sentiment", { score: 0.8 })
+memory.set(:"analysis:entities", ["Ruby", "LLM"])
+memory.set(:unrelated_key, "ignored")
+
+sleep 0.1
+
+puts "Pattern matched #{pattern_changes.size} changes (expected 2):"
+pattern_changes.each do |change|
+  ap({ change.key => change.value })
+end
+puts
+
+# =============================================================================
+# Section 4: Unsubscribe
+# =============================================================================
+
+puts "--- Section 4: Unsubscribe ---"
+puts
+
+count_before = changes.size
+memory.unsubscribe(sub_id)
+puts "Unsubscribed from :status"
+
+memory.set(:status, "archived")
+sleep 0.1
+
+puts "Changes after unsubscribe: #{changes.size} (was #{count_before}, should be same)"
+puts
+
+# =============================================================================
+# Section 5: Key management
+# =============================================================================
+
+puts "--- Section 5: Key Management ---"
+puts
+
+puts "memory.keys (non-reserved):"
+ap memory.keys
+puts
+
+puts "memory.all_keys (includes reserved: data, results, messages, session_id, cache):"
+ap memory.all_keys
+puts
+
+puts "memory.key?(:status) = #{memory.key?(:status)}"
+puts "memory.key?(:nope)   = #{memory.key?(:nope)}"
+puts
+
+# =============================================================================
+# Section 6: Serialization round-trip
+# =============================================================================
+
+puts "--- Section 6: Serialization Round-Trip ---"
+puts
+
+hash = memory.to_h
+puts "memory.to_h:"
+ap hash
+puts
+
+json_str = memory.to_json
+puts "memory.to_json length: #{json_str.length} chars"
+puts
+
+# Round-trip via from_hash
+restored = RobotLab::Memory.from_hash(hash)
+
+puts "Restored memory from hash:"
+ap restored.to_h
+puts
+
+# Use hashdiff to verify the round-trip preserved everything
+diff = Hashdiff.diff(hash, restored.to_h)
+if diff.empty?
+  puts "Round-trip verification: PERFECT (no differences)"
+else
+  puts "Round-trip differences:"
+  diff.each do |change|
+    op, path, *values = change
+    case op
+    when "+"
+      puts "  + #{path}: #{values.first.inspect}"
+    when "-"
+      puts "  - #{path}: #{values.first.inspect}"
+    when "~"
+      puts "  ~ #{path}: #{values.first.inspect} -> #{values.last.inspect}"
+    end
+  end
+end
+puts
+
+# =============================================================================
+# Section 7: Clone for isolation
+# =============================================================================
+
+puts "--- Section 7: Clone for Isolation ---"
+puts
+
+cloned = memory.clone
+cloned.set(:isolated_key, "only in clone")
+
+puts "cloned.key?(:isolated_key)  = #{cloned.key?(:isolated_key)}"
+puts "memory.key?(:isolated_key)  = #{memory.key?(:isolated_key)}  (isolated!)"
+puts
+
+# Show exactly what differs between clone and original
+diff = Hashdiff.diff(memory.to_h, cloned.to_h)
+puts "Diff (original vs clone):"
+diff.each do |change|
+  op, path, *values = change
+  case op
+  when "+"
+    puts "  + #{path}: #{values.first.inspect}"
+  when "-"
+    puts "  - #{path}: #{values.first.inspect}"
+  when "~"
+    puts "  ~ #{path}: #{values.first.inspect} -> #{values.last.inspect}"
+  end
+end
+puts
+
+# =============================================================================
+# Section 8: Delete and reserved key protection
+# =============================================================================
+
+puts "--- Section 8: Delete and Reserved Key Protection ---"
+puts
+
+before_delete = memory.to_h
+memory.delete(:status)
+
+puts "After memory.delete(:status):"
+diff = Hashdiff.diff(before_delete, memory.to_h)
+diff.each do |change|
+  op, path, *values = change
+  case op
+  when "-"
+    puts "  - #{path}: #{values.first.inspect}"
+  end
+end
+puts
+
+begin
+  memory.delete(:data)
+rescue ArgumentError => e
+  puts "memory.delete(:data) raises: #{e.message}"
+end
+puts
+
+# =============================================================================
+# Section 9: Clear vs Reset
+# =============================================================================
+
+puts "--- Section 9: Clear vs Reset ---"
+puts
+
+memory.set(:temp1, "value1")
+memory.set(:temp2, "value2")
+
+puts "Before clear:"
+before_clear = memory.to_h
+ap before_clear
+puts
+
+memory.clear
+
+puts "After clear (non-reserved keys removed):"
+after_clear = memory.to_h
+ap after_clear
+puts
+
+puts "Diff (before clear vs after clear):"
+Hashdiff.diff(before_clear, after_clear).each do |change|
+  op, path, *values = change
+  case op
+  when "+"
+    puts "  + #{path}: #{values.first.inspect}"
+  when "-"
+    puts "  - #{path}: #{values.first.inspect}"
+  when "~"
+    puts "  ~ #{path}: #{values.first.inspect} -> #{values.last.inspect}"
+  end
+end
+puts
+
+before_reset = memory.to_h
+memory.reset
+
+puts "After reset (full reset to initial state):"
+after_reset = memory.to_h
+ap after_reset
+puts
+
+puts "Diff (before reset vs after reset):"
+Hashdiff.diff(before_reset, after_reset).each do |change|
+  op, path, *values = change
+  case op
+  when "+"
+    puts "  + #{path}: #{values.first.inspect}"
+  when "-"
+    puts "  - #{path}: #{values.first.inspect}"
+  when "~"
+    puts "  ~ #{path}: #{values.first.inspect} -> #{values.last.inspect}"
+  end
+end
+puts
+
+puts "=" * 70
+puts "All sections completed without any LLM calls."
+puts "=" * 70