robot_lab 0.0.1 → 0.0.6

data/examples/08_llm_config.rb

@@ -0,0 +1,169 @@
+#!/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 "  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"
+puts "-" * 70
+puts
+
+# --- RunConfig demonstration ---
+puts "-" * 70
+puts "RunConfig: Shared Operational Defaults"
+puts "-" * 70
+puts
+
+shared = RobotLab::RunConfig.new(model: "claude-sonnet-4", temperature: 0.5)
+puts "  shared = RunConfig.new(model: \"claude-sonnet-4\", temperature: 0.5)"
+puts "  shared.to_h => #{shared.to_h.inspect}"
+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(
+  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 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: "claude-sonnet-4", 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=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,262 @@
+#!/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: RunConfig as alternative to individual kwargs
+# =============================================================================
+
+puts "--- Section 5: RunConfig as Alternative to Individual kwargs ---"
+puts
+
+# Instead of passing model:, temperature:, etc. individually,
+# use a RunConfig to express shared defaults.
+shared = RobotLab::RunConfig.new(model: "claude-sonnet-4", temperature: 0.5)
+
+puts "RunConfig: #{shared.to_h.inspect}"
+puts
+
+# Robot inherits from RunConfig; constructor kwargs still override
+robot3 = RobotLab.build(
+  name: "runconfig_demo",
+  template: :configurable,
+  context: { task_type: "analysis" },
+  config: shared,
+  temperature: 0.8  # overrides RunConfig's 0.5
+)
+
+puts "Robot with config: shared, temperature: 0.8"
+puts "(RunConfig sets 0.5, constructor overrides to 0.8)"
+prev3 = show_config(robot3)
+puts
+
+# RunConfig merge semantics
+creative = RobotLab::RunConfig.new(temperature: 0.9, max_tokens: 2000)
+merged = shared.merge(creative)
+
+puts "Merge: shared.merge(creative)"
+puts "  shared:   #{shared.to_h.inspect}"
+puts "  creative: #{creative.to_h.inspect}"
+puts "  merged:   #{merged.to_h.inspect}"
+puts "  (model inherited, temperature overridden, max_tokens added)"
+puts
+
+# =============================================================================
+# Section 6: Bare robot with chaining
+# =============================================================================
+
+puts "--- Section 6: 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 7: with_template() on an existing robot
+# =============================================================================
+
+puts "--- Section 7: 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 8: AskUser tool for gathering template parameters
+# =============================================================================
+
+puts "--- Section 8: 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