robot_lab 0.3.0 → 0.3.1

data/examples/09_chaining.rb

@@ -1,251 +0,0 @@
-#!/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
-
-require_relative "common"
-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
-
-banner "Robot Chaining & Reconfiguration"
-
-# =============================================================================
-# Section 1: Template front matter config
-# =============================================================================
-
-section "Section 1: Template Front Matter Config"
-
-# The 'configurable' template sets temperature: 0.3 and max_tokens: 200
-# via YAML front matter. These are applied automatically.
-robot = RobotLab.build(
-  **llm_opts,
-  name: "chameleon",
-  template: :configurable,
-  context: { task_type: "analysis" }
-)
-
-puts "Robot created with :configurable template"
-prev = show_config(robot)
-puts
-
-# =============================================================================
-# Section 2: with_* method chaining
-# =============================================================================
-
-section "Section 2: with_* Method Chaining"
-
-# 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
-# =============================================================================
-
-section "Section 3: update() for Reconfiguration"
-
-# 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
-# =============================================================================
-
-section "Section 4: Constructor Params Override Front Matter"
-
-# The configurable template sets temperature: 0.3 in front matter.
-# Passing temperature: 0.9 to the constructor overrides it.
-robot2 = RobotLab.build(
-  **llm_opts,
-  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
-# =============================================================================
-
-section "Section 5: RunConfig as Alternative to Individual kwargs"
-
-# Instead of passing model:, temperature:, etc. individually,
-# use a RunConfig to express shared defaults.
-shared = RobotLab::RunConfig.new(model: LLM[:default].model, temperature: 0.5)
-
-puts "RunConfig: #{shared.to_h.inspect}"
-puts
-
-# Robot inherits from RunConfig; constructor kwargs still override
-robot3 = RobotLab.build(
-  **llm_opts,
-  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
-# =============================================================================
-
-section "Section 6: Bare Robot with Chaining"
-
-# 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
-# =============================================================================
-
-section "Section 7: with_template() on Existing Robot"
-
-# 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
-# =============================================================================
-
-section "Section 8: AskUser for Template Parameters"
-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(
-  **llm_opts,
-  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
-
-hr
-puts "All sections completed without any LLM calls."

data/examples/10_memory.rb

@@ -1,315 +0,0 @@
-#!/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
-
-require_relative "common"
-require "json"
-require "amazing_print"
-require "hashdiff"
-
-banner "Advanced Memory Operations"
-
-# =============================================================================
-# Section 1: StateProxy for method-style access
-# =============================================================================
-
-section "Section 1: StateProxy for Method-Style Access"
-
-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
-# =============================================================================
-
-section "Section 2: Subscriptions and MemoryChange"
-
-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
-# =============================================================================
-
-section "Section 3: Pattern Subscriptions"
-
-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
-# =============================================================================
-
-section "Section 4: Unsubscribe"
-
-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
-# =============================================================================
-
-section "Section 5: Key Management"
-
-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
-# =============================================================================
-
-section "Section 6: Serialization Round-Trip"
-
-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
-# =============================================================================
-
-section "Section 7: Clone for Isolation"
-
-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
-# =============================================================================
-
-section "Section 8: Delete and Reserved Key Protection"
-
-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
-# =============================================================================
-
-section "Section 9: Clear vs Reset"
-
-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
-
-hr
-puts "All sections completed without any LLM calls."