robot_lab 0.0.8 → 0.0.11

data/docs/superpowers/specs/2026-04-14-ractor-integration-design.md

@@ -0,0 +1,258 @@
+# Ractor Integration Design
+
+**Date:** 2026-04-14
+**Status:** Approved
+**Gems:** `ractor_queue`, `ractor-wrapper`
+
+## Goals
+
+1. True CPU parallelism (GIL-bypassing) for CPU-bound tool execution
+2. True CPU parallelism for parallel robot execution in Networks
+3. Use `ractor_queue` as the queue backbone for both tracks
+4. Use `ractor-wrapper` to expose shared `Memory` to Ractor workers
+5. Deliver both tracks as independent, composable layers
+
+## Non-Goals
+
+- Making `ruby_llm` or the `async` gem Ractor-safe
+- Replacing the existing `:async` concurrency model (it remains the default)
+- Ractor-isolating `Robot` instances that are long-lived across multiple tasks
+
+---
+
+## Architecture Overview
+
+Two parallel tracks share a frozen-message convention and `ractor_queue` as the communication backbone.
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        Thread/Fiber World                        │
+│  Robot (ruby_llm, async)  ──▶  Tool.call()  ──▶  RobotResult  │
+│           │                        │                             │
+│     BusPoller                 ractor_safe?                       │
+│    (ractor_queue)              │        │                        │
+└────────────────────────────────│────────│────────────────────────┘
+                                 │  yes   │  no
+             ┌───────────────────┘        └──► Thread executor
+             ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                        Ractor World                              │
+│  RactorWorkerPool  ◀──ractor_queue──  frozen RactorJob          │
+│  (N Ractor workers)                                              │
+│         │                                                        │
+│  RactorMemoryProxy  (ractor-wrapper around Memory)              │
+│  ◀── get/set via Ractor messages ──▶                            │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+**Key constraint:** only frozen, `Ractor.shareable?` objects cross Ractor boundaries. A `RactorJob` is a `Data.define` struct (shareable by design) carrying a frozen payload and a per-job reply `ractor_queue`.
+
+---
+
+## Shared Infrastructure
+
+### `RactorJob`
+
+```ruby
+RactorJob = Data.define(:id, :type, :payload, :reply_queue)
+```
+
+Single cross-boundary carrier for both tracks. `payload` must be frozen by the caller before submission. `reply_queue` is a `ractor_queue` instance (Ractor-safe).
+
+### `RactorJobError`
+
+```ruby
+RactorJobError = Data.define(:message, :backtrace)
+```
+
+Frozen error representation for exceptions that occur inside a Ractor worker. Serialized at the Ractor boundary, re-raised on the thread side.
+
+### `RobotSpec`
+
+```ruby
+RobotSpec = Data.define(:name, :template, :system_prompt, :config_hash)
+```
+
+Carries everything needed to reconstruct a `Robot` inside a Ractor. All fields must be frozen strings/hashes.
+
+### `RactorBoundary`
+
+A utility module with a `freeze_deep(obj)` method that recursively freezes nested `Hash`/`Array` structures before they cross a Ractor boundary. Similar in spirit to the existing `deep_dup` in `Utils`. Raises `RobotLab::RactorBoundaryError` (a subclass of `RobotLab::Error`) if a value cannot be made shareable (e.g., a live IO or Proc).
+
+```ruby
+module RactorBoundary
+  def self.freeze_deep(obj)
+    case obj
+    when Hash  then obj.transform_values { freeze_deep(_1) }.freeze
+    when Array then obj.map { freeze_deep(_1) }.freeze
+    else            obj.frozen? ? obj : obj.dup.freeze
+    end
+  rescue TypeError => e
+    raise RobotLab::RactorBoundaryError, "Cannot make value Ractor-shareable: #{e.message}"
+  end
+end
+```
+
+---
+
+## Track 1: RactorWorkerPool (Tool CPU Parallelism)
+
+### Tool opt-in
+
+`RobotLab::Tool` gets a `ractor_safe` class macro (default `false`). Ractor-safe tools must be stateless — no captured mutable closures, no non-shareable constants.
+
+```ruby
+class EmbeddingTool < RobotLab::Tool
+  ractor_safe true
+
+  def execute(text:)
+    # CPU-bound embedding work — runs inside a Ractor worker
+  end
+end
+```
+
+The framework raises `RobotLab::ConfigurationError` at class-definition time if a declared-safe tool captures unshareable state (detected via `Ractor.shareable?` check on the class object).
+
+### `RactorWorkerPool`
+
+A pool of N Ractor workers (configurable via `RunConfig#ractor_pool_size`, default `Etc.nprocessors`). Each worker runs:
+
+```ruby
+loop do
+  job = work_queue.pop                    # blocks on ractor_queue
+  result = dispatch(job)                  # instantiates tool class, calls execute
+  job.reply_queue.push(result)            # frozen result back to caller
+rescue => e
+  job.reply_queue.push(RactorJobError.new(message: e.message, backtrace: e.backtrace))
+end
+```
+
+The pool is lazily initialized on first use and shared across robots in a Network via the existing `RunConfig` hierarchy. It lives for the lifetime of the process (or the `RunConfig` that owns it). `RactorWorkerPool#shutdown` drains in-flight jobs, then closes the work `ractor_queue` so all workers exit their loops cleanly. `RunConfig` calls `shutdown` on `ObjectSpace` finalizer or explicit `RobotLab.shutdown` call.
+
+If a worker Ractor crashes (unhandled exception kills the Ractor), the pool detects the dead Ractor via `Ractor#take` and spawns a replacement. The failed job's reply queue receives a `RactorJobError`.
+
+### Submission path (inside `Robot#call_tool`)
+
+1. Look up `tool_class` from `ToolManifest`
+2. Check `tool_class.ractor_safe?`
+3. **If yes:** `RactorBoundary.freeze_deep(args)`, build `RactorJob`, push to pool's work `ractor_queue`, block on reply queue
+4. **If no:** run in current thread/fiber as today
+5. On reply: if result is `RactorJobError`, re-raise as `RobotLab::ToolError` in the calling thread
+
+### `RunConfig` additions
+
+```ruby
+ractor_pool_size: :auto   # :auto = Etc.nprocessors, or an Integer
+```
+
+---
+
+## Track 2: RactorMemoryProxy + RactorNetworkScheduler (Robot Parallelism)
+
+### `RactorMemoryProxy`
+
+Wraps the existing `Memory` instance via `ractor-wrapper`. The wrapper Ractor acts as a method-dispatch server: it receives frozen messages and replies with frozen results.
+
+Supported operations proxied across the Ractor boundary:
+
+| Message | Reply |
+|---------|-------|
+| `[:get, key]` | frozen value or `nil` |
+| `[:set, key, frozen_value]` | `:ok` |
+| `[:keys]` | frozen array of keys |
+
+Subscriptions (callbacks) are **not** proxied — closures are not Ractor-safe. Robots that need reactive subscriptions use the thread-side `Memory` directly. `RactorMemoryProxy` is for Ractor workers that need read/write access to shared state.
+
+No changes to `Memory` itself.
+
+### `RactorNetworkScheduler`
+
+Replaces `SimpleFlow::Pipeline#call_parallel` for Networks with `parallel_mode: :ractor`. Distributes frozen task descriptions to worker Ractors, collects frozen results.
+
+`depends_on` ordering is preserved: the scheduler reads the pipeline's existing dependency graph (from `SimpleFlow::Pipeline`) and uses it to determine which tasks are ready to dispatch. A task is submitted to the `ractor_queue` only once all its dependencies have resolved. This mirrors how `call_parallel` works today — the scheduler wraps the same topological resolution logic.
+
+```
+Scheduler  ──► ractor_queue (frozen RobotSpec + task payload)
+                    │
+                    ▼
+              Worker Ractor
+              (constructs fresh Robot from RobotSpec,
+               runs task, freezes RobotResult,
+               pushes to reply ractor_queue)
+                    │
+Scheduler  ◀── ractor_queue (frozen results)
+```
+
+Each worker Ractor constructs its own `Robot` instance from a `RobotSpec`. The LLM call happens inside the Ractor. This is safe because `ruby_llm` HTTP calls use no shared mutable state between instances — the Ractor constraint is about *shared* non-shareable objects, not fresh instances created inside a Ractor.
+
+Results are collected via a reply `ractor_queue` and assembled into the pipeline's `SimpleFlow::Result` context on the thread side.
+
+### `BusPoller` queue upgrade
+
+`BusPoller#@robot_queues` changes from `Hash<String, Array>` to `Hash<String, ractor_queue>`. Delivery mechanics (mutex-guarded drain, `process_and_drain`) are unchanged — only the backing store is swapped. This makes `BusPoller` capable of receiving deliveries from Ractor workers.
+
+### Network opt-in
+
+```ruby
+network = RobotLab.create_network(name: "analysis", parallel_mode: :ractor) do
+  task :sentiment, sentiment_robot, depends_on: :none
+  task :entities,  entity_robot,    depends_on: :none
+  task :summarize, summary_robot,   depends_on: [:sentiment, :entities]
+end
+```
+
+`parallel_mode: :async` remains the default and is unchanged.
+
+---
+
+## Error Handling
+
+| Scenario | Mechanism |
+|----------|-----------|
+| Tool raises inside Ractor worker | Serialized as `RactorJobError`, re-raised as `RobotLab::ToolError` in calling thread |
+| Robot raises inside `RactorNetworkScheduler` | Serialized as `RactorJobError`, surfaced as failed step in `SimpleFlow::Result` |
+| Worker Ractor crashes (unhandled exception) | Pool detects dead Ractor, spawns replacement, failed job gets `RactorJobError` on reply queue |
+| Non-shareable value submitted to pool | `RobotLab::RactorBoundaryError` raised before the Ractor boundary |
+
+---
+
+## Testing
+
+- `RactorWorkerPool` is testable standalone — no Robot or Network required
+- `RactorMemoryProxy` is testable standalone — wrap a `Memory`, call proxy methods from a test Ractor
+- Tools that declare `ractor_safe true` should pass `assert_ractor_safe(tool_class)` — a test helper that spins up a single-worker pool and round-trips a frozen payload
+- `RactorNetworkScheduler` tests use a minimal two-robot network with `parallel_mode: :ractor`
+- All existing tests are unaffected — `:async` remains the default; no existing class is modified in a breaking way
+
+---
+
+## New Files
+
+| File | Purpose |
+|------|---------|
+| `lib/robot_lab/ractor_job.rb` | `RactorJob`, `RactorJobError`, `RobotSpec` data classes |
+| `lib/robot_lab/ractor_boundary.rb` | `RactorBoundary.freeze_deep` utility |
+| `lib/robot_lab/ractor_worker_pool.rb` | `RactorWorkerPool` — N Ractor workers fed by `ractor_queue` |
+| `lib/robot_lab/ractor_memory_proxy.rb` | `RactorMemoryProxy` — `ractor-wrapper` around `Memory` |
+| `lib/robot_lab/ractor_network_scheduler.rb` | `RactorNetworkScheduler` — distributes robot tasks to Ractor workers |
+
+## Modified Files
+
+| File | Change |
+|------|--------|
+| `lib/robot_lab/tool.rb` | Add `ractor_safe` class macro |
+| `lib/robot_lab/robot.rb` | Check `ractor_safe?` in `call_tool`, submit to pool if true |
+| `lib/robot_lab/run_config.rb` | Add `ractor_pool_size:` field |
+| `lib/robot_lab/bus_poller.rb` | Swap `Array` queues for `ractor_queue` instances |
+| `lib/robot_lab/network.rb` | Add `parallel_mode:` option, delegate to `RactorNetworkScheduler` |
+| `lib/robot_lab/error.rb` | Add `RobotLab::RactorBoundaryError` subclass |
+| `lib/robot_lab.rb` | Require new files |
+
+---
+
+## Dependencies to Add
+
+```ruby
+gem "ractor_queue"
+gem "ractor-wrapper"
+```

data/examples/14_rusty_circuit/.gitignore

@@ -0,0 +1 @@
+/output/

data/examples/14_rusty_circuit/open_mic.rb

@@ -59,7 +59,7 @@ end
 
 bus     = TypedBus::MessageBus.new
 display = Display.new(
-  scout_path: File.join(__dir__, "scout_notes.md"),
+  scout_path: File.join(__dir__, "output", "scout_notes.md"),
   log_path: log_path
 )
 

data/examples/19_token_tracking.rb

@@ -0,0 +1,128 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example 19: Per-Robot Token / Cost Tracking
+#
+# Demonstrates per-run and cumulative token tracking:
+#   - result.input_tokens / result.output_tokens  — tokens used in that run
+#   - robot.total_input_tokens / total_output_tokens — running totals on the robot
+#   - robot.reset_token_totals  — reset the accounting counter (not the chat)
+#
+# Key distinction:
+#   reset_token_totals resets the robot's *accounting counter* only.
+#   The underlying chat history keeps growing, so input_tokens per run
+#   naturally increase as conversation context accumulates.
+#   Use a fresh robot.build when you need a genuinely fresh context.
+#
+# Anthropic and OpenAI both return token counts in every response.
+# Token counts are zero for providers that don't report usage data.
+#
+# Usage:
+#   ANTHROPIC_API_KEY=your_key ruby examples/19_token_tracking.rb
+
+ENV["ROBOT_LAB_TEMPLATE_PATH"] ||= File.join(__dir__, "prompts")
+
+require_relative "../lib/robot_lab"
+
+# Anthropic claude-haiku-4-5 pricing (as of early 2026)
+HAIKU_INPUT_CPM  = 0.80   # $ per 1M input tokens
+HAIKU_OUTPUT_CPM = 4.00   # $ per 1M output tokens
+
+def token_summary(input, output)
+  "in=#{input}  out=#{output}  total=#{input + output}"
+end
+
+def run_cost(input, output)
+  dollars = (input * HAIKU_INPUT_CPM + output * HAIKU_OUTPUT_CPM) / 1_000_000.0
+  "$#{"%.5f" % dollars}"
+end
+
+def first_line(text)
+  text&.strip&.lines&.first&.strip || ""
+end
+
+puts "=" * 60
+puts "Example 19: Per-Robot Token & Cost Tracking"
+puts "=" * 60
+puts
+
+robot = RobotLab.build(
+  name: "analyst",
+  system_prompt: "You are a concise technical analyst. Keep every reply under 40 words.",
+  model: "claude-haiku-4-5-20251001"
+)
+
+prompts = [
+  "What is the difference between a stack and a queue?",
+  "Name three Ruby gems that every Rails project should consider.",
+  "Why does database indexing improve query performance?"
+]
+
+puts "Running #{prompts.size} prompts...\n\n"
+
+prompts.each_with_index do |prompt, i|
+  result = robot.run(prompt)
+
+  puts "Run #{i + 1}: #{prompt}"
+  puts "  Reply:      #{first_line(result.reply)}"
+  puts "  This run:   #{token_summary(result.input_tokens, result.output_tokens)}"
+  puts "  Cost:       #{run_cost(result.input_tokens, result.output_tokens)}"
+  puts "  Cumulative: #{token_summary(robot.total_input_tokens, robot.total_output_tokens)}"
+  puts
+end
+
+puts "-" * 60
+puts "After #{prompts.size} runs:"
+puts "  Total tokens: #{token_summary(robot.total_input_tokens, robot.total_output_tokens)}"
+puts "  Total cost:   #{run_cost(robot.total_input_tokens, robot.total_output_tokens)}"
+puts
+
+# ---------------------------------------------------------------
+# reset_token_totals: resets the accounting counter only.
+# Useful when you want to measure cost for a specific task batch
+# while keeping the robot alive for the next batch.
+#
+# Note: input_tokens will still reflect the full chat history sent
+# to the API — that's the real cost, not an error.
+# ---------------------------------------------------------------
+
+puts "Resetting token totals (batch 1 complete, starting batch 2)..."
+robot.reset_token_totals
+puts "  Counter now:  #{token_summary(robot.total_input_tokens, robot.total_output_tokens)}"
+puts
+puts "  Note: the next run's input_tokens will be larger than run 1's"
+puts "  because the LLM receives the full accumulated chat context."
+puts "  The counter reset tracks *accounting* — it doesn't clear the chat."
+puts
+
+result = robot.run("What is memoization?")
+puts "Batch 2 — Run 1: What is memoization?"
+puts "  Reply:      #{first_line(result.reply)}"
+puts "  This run:   #{token_summary(result.input_tokens, result.output_tokens)}"
+puts "  Batch total: #{token_summary(robot.total_input_tokens, robot.total_output_tokens)}"
+puts
+
+# ---------------------------------------------------------------
+# To start truly fresh (new context, new counter), build a new robot.
+# ---------------------------------------------------------------
+
+puts "-" * 60
+puts "Fresh robot — genuinely zero context:"
+puts
+
+fresh = RobotLab.build(
+  name: "analyst2",
+  system_prompt: "You are a concise technical analyst. Keep every reply under 40 words.",
+  model: "claude-haiku-4-5-20251001"
+)
+
+result = fresh.run("What is memoization?")
+puts "Run 1 (fresh robot): What is memoization?"
+puts "  Reply:      #{first_line(result.reply)}"
+puts "  This run:   #{token_summary(result.input_tokens, result.output_tokens)}"
+puts "  Cumulative: #{token_summary(fresh.total_input_tokens, fresh.total_output_tokens)}"
+puts
+
+puts "=" * 60
+puts "Token tracking demo complete."
+puts "=" * 60

data/examples/20_circuit_breaker.rb

@@ -0,0 +1,153 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example 20: Tool Loop Circuit Breaker
+#
+# Demonstrates max_tool_rounds to prevent runaway tool call loops.
+#
+# A "process runner" robot is given a step tool whose return value always
+# instructs the LLM to call it again — it would loop forever without a guard.
+# The circuit breaker fires after max_tool_rounds tool calls and raises
+# RobotLab::ToolLoopError.
+#
+# Key behaviour when the breaker fires:
+#   The chat history contains a dangling tool_use with no tool_result.
+#   Anthropic (and most providers) reject any subsequent request with that
+#   broken history.  You MUST call robot.clear_messages before reusing the
+#   same robot instance — or simply build a fresh robot.
+#
+# Demonstrates:
+#   - max_tool_rounds: N on RobotLab.build
+#   - ToolLoopError raised when the limit is exceeded
+#   - clear_messages to flush the corrupted chat and recover the robot
+#   - Contrast: robot without a circuit breaker on a task that terminates
+#
+# Usage:
+#   ANTHROPIC_API_KEY=your_key ruby examples/20_circuit_breaker.rb
+
+ENV["ROBOT_LAB_TEMPLATE_PATH"] ||= File.join(__dir__, "prompts")
+
+require_relative "../lib/robot_lab"
+
+# -------------------------------------------------------------------------
+# A tool that always says "more steps remain" — designed to induce looping
+# -------------------------------------------------------------------------
+
+class MultiStepProcessor < RubyLLM::Tool
+  description <<~DESC
+    Executes one step of a sequential batch process.
+    Returns the result of that step and whether more steps remain.
+    You MUST call this tool again for each remaining step until
+    the status is "complete".
+  DESC
+
+  param :step_number,
+        type: "integer",
+        desc: "Which step to execute. Start at 1, increment by 1 each call."
+
+  TOTAL_STEPS = 50  # far more than any sensible max_tool_rounds
+
+  def execute(step_number:)
+    remaining = TOTAL_STEPS - step_number
+    if remaining <= 0
+      { status: "complete", step: step_number, message: "All steps finished." }
+    else
+      {
+        status: "in_progress",
+        step_completed: step_number,
+        remaining_steps: remaining,
+        instruction: "Call this tool again with step_number: #{step_number + 1}"
+      }
+    end
+  end
+end
+
+puts "=" * 60
+puts "Example 20: Tool Loop Circuit Breaker"
+puts "=" * 60
+puts
+
+TASK = "Run the batch process from step 1 using the MultiStepProcessor tool. " \
+       "Execute every step sequentially until the process reports 'complete'."
+
+# -------------------------------------------------------------------------
+# Part 1: Circuit breaker fires — rescue ToolLoopError, then recover
+#
+# After ToolLoopError the chat contains a dangling tool_use block with no
+# matching tool_result. Anthropic rejects any follow-up request with that
+# history. Call clear_messages to flush the broken context before reuse.
+# -------------------------------------------------------------------------
+
+puts "--- Part 1: Circuit breaker fires (max_tool_rounds: 5) ---"
+puts
+
+robot = RobotLab.build(
+  name: "process_runner",
+  system_prompt: "You are a process runner. Execute tasks exactly as instructed.",
+  local_tools: [MultiStepProcessor],
+  max_tool_rounds: 5,
+  model: "claude-haiku-4-5-20251001"
+)
+
+begin
+  robot.run(TASK)
+  puts "Process completed (unexpected for this demo)."
+rescue RobotLab::ToolLoopError => e
+  puts "Circuit breaker fired!"
+  puts "  #{e.message}"
+end
+
+puts
+
+# -------------------------------------------------------------------------
+# Part 2: Recover by flushing the corrupted chat with clear_messages
+#
+# The robot retains its config (system prompt, tools, max_tool_rounds).
+# Only the conversation history is cleared — the robot is then reusable.
+# -------------------------------------------------------------------------
+
+puts "--- Part 2: Recover with clear_messages ---"
+puts
+
+robot.clear_messages
+puts "Chat flushed. Robot config (tools, max_tool_rounds) is unchanged."
+puts "  max_tool_rounds still: #{robot.config.max_tool_rounds}"
+puts
+
+result = robot.run("What is 3 + 4? Answer in one sentence.")
+puts "Follow-up after recovery: #{result.reply&.strip}"
+puts
+
+# -------------------------------------------------------------------------
+# Part 3: Robot without a circuit breaker on a task that terminates quickly
+#
+# Normal tool use works fine with no guard — the breaker is a safety net,
+# not a tax on well-behaved tool interactions.
+# -------------------------------------------------------------------------
+
+puts "--- Part 3: No circuit breaker — task terminates naturally ---"
+puts
+
+class SingleStep < RubyLLM::Tool
+  description "Doubles a number and returns the result immediately."
+  param :value, type: "integer", desc: "The number to double"
+
+  def execute(value:)
+    { result: value * 2, status: "complete" }
+  end
+end
+
+unguarded = RobotLab.build(
+  name: "calculator",
+  system_prompt: "Use the provided tool to answer questions.",
+  local_tools: [SingleStep],
+  model: "claude-haiku-4-5-20251001"
+)
+
+result = unguarded.run("Double the number 21 using the tool.")
+puts "Result: #{result.reply&.strip}"
+puts
+
+puts "=" * 60
+puts "Circuit breaker demo complete."
+puts "=" * 60