robot_lab-durable 0.1.0

data/docs/superpowers/specs/2026-05-06-durable-learning-design.md

@@ -0,0 +1,182 @@
+# Durable Learning for RobotLab
+
+**Date**: 2026-05-06
+**Status**: Draft
+
+## Problem
+
+Robots built with RobotLab have no memory between sessions and no mechanism for improving their judgment over time. Each run starts from zero. The newsletter reader robot is the motivating case: it should get better at deciding what content belongs in the Obsidian PKM vault without requiring the user to explain their preferences every time.
+
+## Goals
+
+- Robots accumulate knowledge within a session (explicit during operation, reflection at end)
+- Knowledge persists across sessions and across projects
+- Conservative bias: when uncertain and no relevant past learning exists, skip rather than guess
+- Human-readable, auditable, directly editable storage
+- General capability — not newsletter-specific
+
+## Non-goals
+
+- Automated curator/consolidation (YAGNI for now)
+- Confidence decay over time (YAGNI for now)
+- Fine-tuning or model-level learning (out of scope)
+
+---
+
+## Design
+
+### `RobotLab::Durable::Entry`
+
+A single knowledge record. Immutable value object (Ruby `Data.define`).
+
+| Field        | Type    | Description                                                    |
+|--------------|---------|----------------------------------------------------------------|
+| `content`    | String  | The fact, pattern, or preference learned, in plain language    |
+| `reasoning`  | String  | Why — captured from discussion or observation                  |
+| `category`   | Symbol  | `:fact`, `:preference`, `:pattern`, `:correction`              |
+| `domain`     | String  | Topic area ("Ruby tooling", "newsletter curation")             |
+| `confidence` | Float   | 0.1 initial, increments by 0.1 each confirmed application, max 1.0 |
+| `use_count`  | Integer | Times recalled and applied                                     |
+| `created_at` | String  | ISO8601 timestamp                                              |
+| `updated_at` | String  | ISO8601 timestamp                                              |
+
+### `RobotLab::Durable::Store`
+
+Reads and writes `Entry` records. Storage: Markdown files with YAML frontmatter in `lib/robot_lab/durable/`, one file per domain (e.g., `newsletter_curation.md`, `ruby_tooling.md`).
+
+File format mirrors the Obsidian PKM convention — intentionally familiar:
+
+```markdown
+---
+domain: newsletter curation
+entries:
+  - content: Skip LangChain content
+    reasoning: User is Ruby-only and considers Python tooling irrelevant
+    category: preference
+    confidence: 0.4
+    use_count: 3
+    created_at: "2026-05-06T12:00:00Z"
+    updated_at: "2026-05-06T14:30:00Z"
+---
+```
+
+Key methods:
+- `recall(query:, domain: nil, min_confidence: 0.0)` — returns relevant entries, sorted by confidence
+- `record(entry)` — appends or updates an entry in the appropriate domain file
+- `confirm(entry)` — increments `confidence` by 0.1 and `use_count` by 1, updates `updated_at`
+
+Matching strategy: keyword overlap on `content` + `domain` fields. Semantic search via fastembed is a future enhancement.
+
+### `RobotLab::Durable::Reflector`
+
+A lightweight robot that runs at session end. Receives the session's `Memory` (messages, results, data) and the existing `Store`. Its job: identify observations from the session worth promoting to durable knowledge and call `store.record` for each.
+
+Implemented as a `RobotLab.build` robot with a focused system prompt. Uses `RecordKnowledge` tool internally.
+
+### `RobotLab::Durable::Learning` (mixin)
+
+Included in a `Robot` to activate learning capability.
+
+```ruby
+robot = RobotLab.build(
+  name: "newsletter_analyst",
+  system_prompt: "...",
+  local_tools: [FetchLatestNewsletter],
+  learn: true,         # activates Durable::Learning
+  learn_domain: "newsletter curation"
+)
+```
+
+What the mixin does:
+1. Adds `RecallKnowledge` and `RecordKnowledge` to the robot's tool list
+2. Runs a `recall` pass on session start, injecting relevant entries as context
+3. Registers an `on_session_end` hook that triggers `Durable::Reflector`
+
+### `RecallKnowledge` tool
+
+The robot calls this before acting on anything uncertain.
+
+```
+Input:  query (String), domain (String, optional)
+Output: Array of matching Entry records as formatted context
+```
+
+### `RecordKnowledge` tool
+
+The robot calls this during the session when it judges something worth keeping.
+
+```
+Input:  content, reasoning, category, domain
+Output: confirmation the entry was written
+```
+
+---
+
+## Learning Loop
+
+```
+Session start
+  └─ Store.recall → inject relevant entries as context
+
+During session
+  └─ Robot discusses/decides
+  └─ Robot calls RecordKnowledge (explicit, in-moment captures)
+  └─ Robot calls RecallKnowledge before uncertain decisions
+  └─ On confirmed application → Store.confirm (confidence++)
+
+Session end
+  └─ Reflector reviews session Memory
+  └─ Promotes observations not yet explicitly recorded
+  └─ Writes to Store
+```
+
+---
+
+## Conservative Bias
+
+When `recall_knowledge` returns no relevant entries AND the robot's confidence on a candidate decision is below 0.5, the robot skips the action and logs the reason. This is enforced through system prompt guidance, not framework code.
+
+---
+
+## Storage Location
+
+`lib/robot_lab/durable/` — already exists as a placeholder. Domain files live here:
+
+```
+lib/robot_lab/durable/
+  newsletter_curation.md
+  ruby_tooling.md
+  ...
+```
+
+---
+
+## Newsletter Reader Integration
+
+The newsletter robot uses `learn: true, learn_domain: "newsletter curation"`. Its workflow:
+
+1. Fetch newsletter RSS
+2. Follow links one level deep, extract article content
+3. For each article: `RecallKnowledge` to check against past decisions
+4. High-confidence match → act autonomously (include or skip)
+5. No match or low confidence → skip and log
+6. Discussion with user → `RecordKnowledge` captures reasoning
+7. Session end → `Reflector` promotes any missed observations
+
+Over time, the confidence on frequently-confirmed patterns rises, and the robot handles more autonomously with fewer discussions required.
+
+---
+
+## Files to Create
+
+| File | Purpose |
+|------|---------|
+| `lib/robot_lab/durable/entry.rb` | `Entry` data class |
+| `lib/robot_lab/durable/store.rb` | Read/write/confirm operations |
+| `lib/robot_lab/durable/reflector.rb` | End-of-session reflection robot |
+| `lib/robot_lab/durable/learning.rb` | `Learning` mixin for Robot |
+| `lib/robot_lab/tools/recall_knowledge.rb` | `RecallKnowledge` tool |
+| `lib/robot_lab/tools/record_knowledge.rb` | `RecordKnowledge` tool |
+| `test/robot_lab/durable/entry_test.rb` | Unit tests |
+| `test/robot_lab/durable/store_test.rb` | Unit tests |
+| `examples/32_newsletter_reader.rb` | Updated with `learn: true` |

data/examples/33_stock_generator.rb

@@ -0,0 +1,80 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example 33: XYZZY Stock Price Generator
+#
+# Publishes fake streaming prices for ticker XYZZY to a Redis channel
+# using Geometric Brownian Motion with occasional volatility regime shifts.
+#
+# Prerequisites:
+#   gem install redis
+#   Redis server running on localhost:6379
+#
+# Usage:
+#   ruby examples/33_stock_generator.rb
+
+require "redis"
+require "json"
+require "time"
+
+CHANNEL     = "stock:xyzzy"
+START_PRICE = 100.0
+BASE_VOL    = 0.008   # baseline volatility per tick (~0.8%)
+DRIFT       = 0.0001  # slight upward drift per tick
+
+# Box-Muller transform — standard normal sample
+def randn
+  Math.sqrt(-2.0 * Math.log(rand)) * Math.cos(2.0 * Math::PI * rand)
+end
+
+# Occasionally shift the volatility regime to create interesting price dynamics
+def current_volatility(tick)
+  case tick % 60
+  when 0..10  then BASE_VOL * 2.0   # high volatility burst
+  when 30..35 then BASE_VOL * 0.4   # low volatility squeeze
+  else             BASE_VOL
+  end
+end
+
+# ── Main ──────────────────────────────────────────────────────────────────────
+
+redis = Redis.new
+price = START_PRICE
+tick  = 0
+
+trap("INT") { puts "\nGenerator stopped."; exit }
+
+puts "=" * 50
+puts "XYZZY Stock Generator"
+puts "=" * 50
+puts "Channel : #{CHANNEL}"
+puts "Interval: 5 seconds per tick"
+puts "Model   : Geometric Brownian Motion"
+puts "Press Ctrl-C to stop."
+puts "-" * 50
+
+loop do
+  tick += 1
+
+  vol   = current_volatility(tick)
+  price = (price * Math.exp((DRIFT - 0.5 * vol**2) + vol * randn)).round(2)
+  price = [price, 1.0].max  # floor at $1.00
+
+  regime = case vol
+           when BASE_VOL * 2.0 then " [HIGH VOL]"
+           when BASE_VOL * 0.4 then " [low vol]"
+           else ""
+           end
+
+  payload = JSON.generate(
+    ticker:    "XYZZY",
+    price:     price,
+    tick:      tick,
+    timestamp: Time.now.iso8601
+  )
+
+  redis.publish(CHANNEL, payload)
+  puts "Tick %5d  $%8.2f  vol=%.3f%s" % [tick, price, vol, regime]
+
+  sleep 5
+end

data/examples/33_stock_predictor.rb

@@ -0,0 +1,304 @@
+#!/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
+
+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(
+               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/lib/robot_lab/durable/entry.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module Durable
+    Entry = Data.define(:content, :reasoning, :category, :domain, :confidence, :use_count, :created_at, :updated_at) do
+      CONFIDENCE_INCREMENT = 0.1
+      MAX_CONFIDENCE       = 1.0
+
+      # Return a new Entry with confidence incremented and use_count bumped.
+      def confirm
+        new_confidence = [confidence + CONFIDENCE_INCREMENT, MAX_CONFIDENCE].min
+        with(
+          confidence: new_confidence.round(10),
+          use_count:  use_count + 1,
+          updated_at: Time.now.iso8601
+        )
+      end
+
+      # Serialize to a plain Hash with string keys (safe for YAML round-trip).
+      def to_h
+        {
+          "content"    => content,
+          "reasoning"  => reasoning,
+          "category"   => category.to_s,
+          "domain"     => domain,
+          "confidence" => confidence,
+          "use_count"  => use_count,
+          "created_at" => created_at,
+          "updated_at" => updated_at
+        }
+      end
+
+      # Deserialize from a Hash (string or symbol keys).
+      def self.from_h(hash)
+        h = hash.transform_keys(&:to_s)
+        new(
+          content:    h["content"],
+          reasoning:  h["reasoning"],
+          category:   h["category"]&.to_sym,
+          domain:     h["domain"],
+          confidence: h["confidence"].to_f,
+          use_count:  h["use_count"].to_i,
+          created_at: h["created_at"],
+          updated_at: h["updated_at"]
+        )
+      end
+    end
+  end
+end

data/lib/robot_lab/durable/learning.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module Durable
+    module Learning
+      # Configure durable learning on a robot after initialization.
+      #
+      # @param domain [String] topic area for this robot's knowledge
+      # @param store_path [String, nil] override default ~/.robot_lab/durable path
+      def setup_durable_learning(domain:, store_path: nil)
+        @learn_domain  = domain.to_s
+        opts           = store_path ? { path: store_path } : {}
+        @durable_store = Store.new(**opts)
+
+        seed_from_store
+        @local_tools = (@local_tools + [RecallKnowledge, RecordKnowledge]).uniq
+      end
+
+      # Run the end-of-session reflection pass.
+      # Called automatically from Robot#run when durable learning is active.
+      def run_reflector
+        return unless @durable_store && @learn_domain && @learnings&.any?
+
+        Reflector.new(store: @durable_store, domain: @learn_domain).reflect(@learnings)
+      end
+
+      private
+
+      def seed_from_store
+        return unless @durable_store && @learn_domain
+
+        entries = @durable_store.recall(query: @learn_domain, domain: @learn_domain, min_confidence: 0.0)
+        entries.each do |e|
+          learn("[#{e.category}] #{e.content}: #{e.reasoning}")
+        end
+      end
+    end
+  end
+end