robot_lab 0.1.0 → 0.2.1

data/examples/33_stock_predictor.rb

@@ -0,0 +1,306 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example 33: XYZZY Stock Price Predictor
+#
+# Consumes fake streaming prices for ticker XYZZY from a Redis channel,
+# predicts the high and low over the next price window using an SMA + EMA
+# ensemble, and uses a RobotLab learning robot to tune predictor parameters
+# after each window closes.
+#
+# Run alongside:
+#   ruby examples/33_stock_generator.rb   (in a separate terminal)
+#
+# Prerequisites:
+#   gem install redis
+#   Redis server running on localhost:6379
+#
+# Usage:
+#   ruby examples/33_stock_predictor.rb
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "robot_lab"
+require "robot_lab/durable"
+require "redis"
+require "json"
+
+CHANNEL     = "stock:xyzzy"
+WINDOW_SIZE = 12  # ticks per prediction window
+
+# ── Mutable predictor parameters ──────────────────────────────────────────────
+
+module PredictorConfig
+  @sma_window         = 10
+  @sma_std_multiplier = 1.5
+  @ema_alpha          = 0.2
+  @ema_vol_multiplier = 2.0
+  @sma_weight         = 0.5
+
+  class << self
+    attr_accessor :sma_window, :sma_std_multiplier, :ema_alpha,
+                  :ema_vol_multiplier, :sma_weight
+
+    def summary
+      format(
+        "sma_window=%d  sma_std=%.2f  ema_alpha=%.2f  ema_vol=%.2f  sma_weight=%.2f",
+        sma_window, sma_std_multiplier, ema_alpha, ema_vol_multiplier, sma_weight
+      )
+    end
+  end
+end
+
+# ── SMA predictor ──────────────────────────────────────────────────────────────
+
+module SMAPredictor
+  def self.predict(prices)
+    window = prices.last(PredictorConfig.sma_window)
+    mean   = window.sum / window.size.to_f
+    var    = window.sum { |p| (p - mean)**2 } / window.size.to_f
+    std    = Math.sqrt(var)
+    mult   = PredictorConfig.sma_std_multiplier
+
+    {
+      high: (mean + mult * std).round(2),
+      low:  [mean - mult * std, 1.0].max.round(2)
+    }
+  end
+end
+
+# ── EMA predictor (stateful — updated every tick) ──────────────────────────────
+
+module EMAPredictor
+  @ema     = nil
+  @var_ema = nil
+
+  class << self
+    def update(price)
+      alpha = PredictorConfig.ema_alpha
+      if @ema.nil?
+        @ema     = price
+        @var_ema = 0.0
+      else
+        delta    = price - @ema
+        @ema     = alpha * price + (1 - alpha) * @ema
+        @var_ema = alpha * delta**2 + (1 - alpha) * @var_ema
+      end
+    end
+
+    def predict
+      return nil if @ema.nil?
+
+      vol = Math.sqrt(@var_ema) * PredictorConfig.ema_vol_multiplier
+      {
+        high: (@ema + vol).round(2),
+        low:  [@ema - vol, 1.0].max.round(2)
+      }
+    end
+  end
+end
+
+# ── Ensemble predictor ─────────────────────────────────────────────────────────
+
+module EnsemblePredictor
+  def self.predict(prices)
+    sma = SMAPredictor.predict(prices)
+    ema = EMAPredictor.predict
+    return sma unless ema
+
+    w = PredictorConfig.sma_weight
+    {
+      high: (w * sma[:high] + (1 - w) * ema[:high]).round(2),
+      low:  (w * sma[:low]  + (1 - w) * ema[:low]).round(2)
+    }
+  end
+end
+
+# ── AdjustParameters tool ──────────────────────────────────────────────────────
+
+class AdjustParameters < RobotLab::Tool
+  description "Adjust one predictor parameter to improve future prediction accuracy. " \
+              "Make at most one or two targeted changes per window."
+
+  param :parameter, type: "string",
+    desc: "Parameter to adjust: sma_window, sma_std_multiplier, ema_alpha, ema_vol_multiplier, sma_weight"
+  param :value, type: "number",
+    desc: "New value (sma_window: 3-30 int; std/vol multipliers: 0.5-4.0; ema_alpha: 0.05-0.5; sma_weight: 0.0-1.0)"
+  param :reasoning, type: "string",
+    desc: "Why this change should reduce prediction error"
+
+  LIMITS = {
+    "sma_window"         => { min: 3,    max: 30,  integer: true  },
+    "sma_std_multiplier" => { min: 0.5,  max: 4.0, integer: false },
+    "ema_alpha"          => { min: 0.05, max: 0.5, integer: false },
+    "ema_vol_multiplier" => { min: 0.5,  max: 4.0, integer: false },
+    "sma_weight"         => { min: 0.0,  max: 1.0, integer: false }
+  }.freeze
+
+  def execute(parameter:, value:, reasoning:)
+    spec = LIMITS[parameter]
+    return "Unknown parameter '#{parameter}'. Valid: #{LIMITS.keys.join(", ")}" unless spec
+
+    clamped = value.to_f.clamp(spec[:min], spec[:max])
+    clamped = clamped.round if spec[:integer]
+
+    PredictorConfig.send(:"#{parameter}=", clamped)
+
+    "Set #{parameter} = #{clamped}. #{reasoning}"
+  end
+end
+
+# ── Error metrics ──────────────────────────────────────────────────────────────
+
+WindowResult = Data.define(
+  :window_num,
+  :predicted_high, :predicted_low,
+  :actual_high,    :actual_low,
+  :high_err,       :low_err,       :mean_err
+)
+
+def evaluate_window(window_num, predicted, actuals)
+  actual_high = actuals.max.round(2)
+  actual_low  = actuals.min.round(2)
+  high_err    = (predicted[:high] - actual_high).abs.round(2)
+  low_err     = (predicted[:low]  - actual_low).abs.round(2)
+  mean_err    = ((high_err + low_err) / 2.0).round(2)
+
+  WindowResult.new(
+    window_num:,
+    predicted_high: predicted[:high], predicted_low: predicted[:low],
+    actual_high:,   actual_low:,
+    high_err:,      low_err:,         mean_err:
+  )
+end
+
+def tuner_prompt(result)
+  <<~PROMPT
+    Window #{result.window_num} just closed.
+
+    Prediction vs Actual:
+      Predicted: high=$#{result.predicted_high}  low=$#{result.predicted_low}
+      Actual:    high=$#{result.actual_high}      low=$#{result.actual_low}
+      Error:     high_err=$#{result.high_err}  low_err=$#{result.low_err}  mean_err=$#{result.mean_err}
+
+    Current parameters:
+      #{PredictorConfig.summary}
+
+    Window size: #{WINDOW_SIZE} ticks.
+
+    First call RecallKnowledge to check what has worked before.
+    Then decide whether to adjust a parameter via AdjustParameters.
+    If the error is acceptable or you are uncertain, do nothing.
+    If you notice a clear pattern worth preserving, call RecordKnowledge.
+  PROMPT
+end
+
+# ── Main ──────────────────────────────────────────────────────────────────────
+
+puts "=" * 60
+puts "XYZZY Stock Predictor"
+puts "=" * 60
+puts "Channel    : #{CHANNEL}"
+puts "Window     : #{WINDOW_SIZE} ticks"
+puts "Model      : SMA + EMA Ensemble with Durable Learning"
+puts "Warmup     : #{PredictorConfig.sma_window} ticks"
+puts "Press Ctrl-C to stop."
+puts "-" * 60
+
+redis      = Redis.new
+prices     = []
+robot      = RobotLab.build(
+  model: "gpt-5.4",
+               name:          "predictor_tuner",
+               system_prompt: <<~PROMPT,
+                 You are a quantitative analyst tuning an ensemble stock price range
+                 predictor for ticker XYZZY. Each prediction covers the high and low
+                 price over the next #{WINDOW_SIZE} ticks.
+
+                 The ensemble combines a Simple Moving Average (SMA) band and an
+                 Exponential Moving Average (EMA) band. Adjustable parameters:
+
+                   sma_window (3-30 int)         — lookback period for SMA
+                   sma_std_multiplier (0.5-4.0)  — band width relative to SMA stddev
+                   ema_alpha (0.05-0.5)           — EMA smoothing (higher = more reactive)
+                   ema_vol_multiplier (0.5-4.0)   — band width relative to EMA volatility
+                   sma_weight (0.0-1.0)           — SMA share in ensemble (EMA = 1 - weight)
+
+                 Workflow per window:
+                   1. Call RecallKnowledge to check past findings before acting.
+                   2. If the error is clearly too high/low in one direction, adjust the
+                      relevant band multiplier via AdjustParameters.
+                   3. Make at most two adjustments per window to isolate cause and effect.
+                   4. If you observe a reliable pattern, call RecordKnowledge to preserve it.
+                   5. When uncertain, do nothing rather than guess.
+               PROMPT
+               local_tools:   [AdjustParameters],
+               learn:         true,
+               learn_domain:  "xyzzy stock prediction"
+             )
+
+warmed_up    = false
+pending_pred = nil  # { prediction: {high:, low:}, window_prices: [] }
+window_num   = 0
+
+trap("INT") { puts "\nPredictor stopped."; exit }
+
+puts "Connecting to Redis and subscribing to #{CHANNEL}..."
+
+redis.subscribe(CHANNEL) do |on|
+  on.message do |_channel, payload|
+    data  = JSON.parse(payload, symbolize_names: true)
+    tick  = data[:tick]
+    price = data[:price].to_f
+
+    EMAPredictor.update(price)
+    prices << price
+
+    # ── Warmup phase ──────────────────────────────────────────────
+    unless warmed_up
+      if prices.size < PredictorConfig.sma_window
+        puts "Tick %5d  $%8.2f  [warming up %d/%d]" % [tick, price, prices.size, PredictorConfig.sma_window]
+        next
+      end
+
+      warmed_up    = true
+      pred         = EnsemblePredictor.predict(prices)
+      pending_pred = { prediction: pred, window_prices: [] }
+
+      puts "Tick %5d  $%8.2f  [warmup done]" % [tick, price]
+      puts "  First prediction → high=$#{pred[:high]}  low=$#{pred[:low]}"
+      next
+    end
+
+    # ── Accumulate current window ──────────────────────────────────
+    pending_pred[:window_prices] << price
+    progress = pending_pred[:window_prices].size
+    pred     = pending_pred[:prediction]
+
+    puts "Tick %5d  $%8.2f  [%2d/#{WINDOW_SIZE}]  (pred high=$#{pred[:high]} low=$#{pred[:low]})" %
+         [tick, price, progress]
+
+    next unless progress >= WINDOW_SIZE
+
+    # ── Window closed — evaluate ───────────────────────────────────
+    window_num += 1
+    result = evaluate_window(window_num, pred, pending_pred[:window_prices])
+
+    puts "\n#{"─" * 60}"
+    puts "  Window #{result.window_num} result:"
+    puts "    Predicted  high=$%-8.2f  low=$%-.2f" % [result.predicted_high, result.predicted_low]
+    puts "    Actual     high=$%-8.2f  low=$%-.2f" % [result.actual_high, result.actual_low]
+    puts "    Error      high=%-8.2f  low=%-8.2f  mean=%.2f" % [result.high_err, result.low_err, result.mean_err]
+    puts "#{"─" * 60}"
+
+    print "  [tuner] analyzing window #{window_num}..."
+    tuner_response = robot.run(tuner_prompt(result))
+    tuner_line     = tuner_response.reply.lines.first&.chomp || "(no response)"
+    puts "\r  [tuner] #{tuner_line}#{" " * 20}"
+    puts "  Params: #{PredictorConfig.summary}"
+    puts
+
+    # ── Start next window ──────────────────────────────────────────
+    new_pred     = EnsemblePredictor.predict(prices)
+    pending_pred = { prediction: new_pred, window_prices: [] }
+    puts "  Next prediction → high=$#{new_pred[:high]}  low=$#{new_pred[:low]}"
+    puts
+  end
+end

data/examples/34_agentskills.rb

@@ -0,0 +1,72 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example 34: AgentSkills.io Integration
+#
+# Demonstrates the unified skills: param detecting AgentSkills folder format.
+# Skills in ~/.prompts/skills/ are matched at runtime via embedding similarity
+# before each run() call — only relevant skills are injected.
+#
+# Usage:
+#   mkdir -p ~/.prompts/skills/code_reviewer
+#   # (create SKILL.md as shown in the example header)
+#   ANTHROPIC_API_KEY=your_key ruby examples/34_agentskills.rb
+
+require_relative "common"
+
+require "logger"
+log_file = File.join(__dir__, "34.log")
+RobotLab.config.logger = Logger.new(log_file)
+RubyLLM.configure { |c| c.logger = Logger.new(log_file) }
+
+banner "RobotLab — AgentSkills.io Integration Demo"
+
+# Check if the skill is installed
+skill_path = File.expand_path("~/.prompts/skills/code_reviewer/SKILL.md")
+unless File.exist?(skill_path)
+  puts "Demo skill not found at #{skill_path}"
+  puts "Create it with:"
+  puts "  mkdir -p ~/.prompts/skills/code_reviewer"
+  puts "  # Then add SKILL.md with name: code_reviewer"
+  exit 1
+end
+
+# Build a robot that lists code_reviewer as a candidate skill.
+# At runtime, if the user message is semantically similar to
+# "Review Ruby code for quality, style, and potential bugs",
+# the skill's instructions are injected into the system prompt.
+robot = RobotLab.build(
+  model: LLM[:default].model,
+  name: "assistant",
+  system_prompt: "You are a helpful Ruby programming assistant.",
+  skills: [:code_reviewer]
+)
+
+puts "Pending AgentSkills: #{robot.instance_variable_get(:@pending_agent_skills).map(&:name).inspect}"
+puts
+
+# Message semantically related to code review — skill should activate
+code_question = <<~MSG
+  Please review this Ruby method for quality issues:
+
+  def process(data)
+    begin
+      result = data.map { |item| transform(item) }
+      save(result)
+    rescue => e
+      puts e.message
+    end
+  end
+MSG
+
+puts "Query: code review (skill should activate)"
+result = robot.run(code_question)
+puts result.reply
+puts
+hr
+
+# Message unrelated to code review — skill should NOT activate
+puts "Query: general question (skill should NOT activate)"
+result = robot.run("What is the capital of France?")
+puts result.reply
+puts

data/examples/README.md

@@ -226,7 +226,7 @@ Demonstrates `robot.search_history(query, limit:)` — semantic search over accu
 
 Demonstrates `memory.store_document(key, text)` and `memory.search_documents(query, limit:)` — a lightweight RAG store using `fastembed` (BAAI/bge-small-en-v1.5). Documents are embedded once; queries are compared by cosine similarity at search time. Includes the `RobotLab::DocumentStore` standalone API and a RAG pattern sketch showing how to pass retrieved context to a robot.
 
-**Requires:** `fastembed` gem (already a core dependency); downloads the ~23 MB ONNX model on first run (cached in `~/.cache/fastembed/`)
+**Requires:** `robot_lab-document_store` gem (`gem "robot_lab-document_store"` in your Gemfile); downloads the ~23 MB ONNX model on first run (cached in `~/.cache/fastembed/`)
 
 ### 27 — Production Incident War Room
 

data/examples/common.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "logger"
+
+# Fallback for when direnv has not activated examples/.envrc
+ENV["ROBOT_LAB_TEMPLATE_PATH"] ||= File.join(__dir__, "prompts")
+
+require_relative "../lib/robot_lab"
+
+LlmConfig = Data.define(:provider, :model)
+
+LLM = {
+  default:   LlmConfig.new(provider: "openai",    model: "gpt-5.4"),
+  local:     LlmConfig.new(provider: "ollama",    model: "llama3.2"),
+  anthropic: LlmConfig.new(provider: "anthropic", model: "claude-opus-4-7")
+}.freeze
+
+RubyLLM.configure do |c|
+  c.logger        = Logger.new(File::NULL)
+  c.default_model = LLM[:default].model
+end
+
+RobotLab.configure do |c|
+  c.logger = Logger.new(File::NULL)
+end
+
+# ── Example Output Helpers ─────────────────────────────────────────────────────
+
+module ExOut
+  WIDTH = 68
+  RESET = "\e[0m"
+  BOLD  = "\e[1m"
+  DIM   = "\e[2m"
+  CYAN  = "\e[36m"
+end
+
+# Prints a bold top-level header. Extracts the example number from $0
+# automatically so callers only supply the title.
+def banner(title)
+  num   = File.basename($0, ".rb")[/^\d+/]&.to_i
+  label = num ? "Example #{num}: #{title}" : title
+  puts
+  puts "#{ExOut::BOLD}#{"=" * ExOut::WIDTH}#{ExOut::RESET}"
+  puts "#{ExOut::BOLD} #{label}#{ExOut::RESET}"
+  puts "#{ExOut::BOLD}#{"=" * ExOut::WIDTH}#{ExOut::RESET}"
+  puts
+end
+
+# Prints a named section divider with a cyan rule.
+def section(title)
+  puts
+  tail = "─" * [ExOut::WIDTH - title.length - 4, 2].max
+  puts "#{ExOut::BOLD}#{ExOut::CYAN}── #{title} #{tail}#{ExOut::RESET}"
+  puts
+end
+
+# Prints a plain dim horizontal rule.
+def hr
+  puts "#{ExOut::DIM}#{"─" * ExOut::WIDTH}#{ExOut::RESET}"
+end
+
+# Prints a Rouge-highlighted Ruby code block with a framed border.
+def show_code(ruby_string, label: "ruby")
+  require "rouge"
+  w      = ExOut::WIDTH - 2
+  border = "#{ExOut::DIM}  #{"─" * w}#{ExOut::RESET}"
+  output = Rouge::Formatters::Terminal256.new
+            .format(Rouge::Lexers::Ruby.new.lex(ruby_string))
+  output += "\n" unless output.end_with?("\n")
+  puts
+  puts "#{ExOut::DIM}  #{label}#{ExOut::RESET}"
+  puts border
+  output.each_line { |l| print "  #{l}" }
+  puts border
+  puts
+end