robot_lab 0.0.4 → 0.0.7

data/docs/guides/streaming.md

@@ -2,9 +2,9 @@
 
 Stream LLM responses in real-time for better user experience.
 
-## Basic Streaming
+## Streaming via Callbacks
 
-Pass a block to `robot.run` to receive streaming events:
+RobotLab robots support streaming through callback methods inherited from RubyLLM::Agent. Register callbacks before calling `run`:
 
 ```ruby
 robot = RobotLab.build(
@@ -12,89 +12,105 @@ robot = RobotLab.build(
   system_prompt: "You are a creative storyteller."
 )
 
-robot.run("Tell me a story about a brave robot") do |event|
-  puts event.inspect
+# Register streaming callback
+robot.on_new_message do |message|
+  print message.content if message.content
 end
+
+result = robot.run("Tell me a story about a brave robot")
 ```
 
-## Event Types
+## Available Callbacks
 
-### Text Deltas
+### on_new_message
 
-Receive text as it is generated:
+Called when the assistant starts generating a new message, with streaming chunks:
 
 ```ruby
-robot.run("Tell me a story") do |event|
-  if event[:event] == "text.delta"
-    print event[:data][:content]
-  end
+robot.on_new_message do |message|
+  print message.content if message.content
 end
 ```
 
-### Tool Calls
+### on_end_message
 
-Know when tools are being called:
+Called when the assistant finishes a message:
 
 ```ruby
-robot.run("What's the weather in Tokyo?") do |event|
-  case event[:event]
-  when "tool_call.start"
-    puts "\nCalling: #{event[:data][:name]}"
-  when "tool_call.complete"
-    puts "Done: #{event[:data][:result]}"
-  end
+robot.on_end_message do |message|
+  puts "\n--- Response complete ---"
+  puts "Content length: #{message.content&.length}"
 end
 ```
 
-### Lifecycle Events
+### on_tool_call
 
-Track execution lifecycle:
+Called when the LLM invokes a tool:
 
 ```ruby
-robot.run("Help me with my task") do |event|
-  case event[:event]
-  when "run.started"
-    puts "Starting..."
-  when "run.completed"
-    puts "Completed!"
-  when "run.failed"
-    puts "Failed: #{event[:data][:error]}"
-  end
+robot.on_tool_call do |tool_call|
+  puts "Calling tool: #{tool_call.name}"
 end
 ```
 
-## Event Reference
+### on_tool_result
 
-| Event | Description | Data |
-|-------|-------------|------|
-| `run.started` | Execution began | `run_id` |
-| `run.completed` | Execution finished | `run_id` |
-| `run.failed` | Error occurred | `run_id`, `error` |
-| `text.delta` | Text content chunk | `content` |
-| `tool_call.start` | Tool execution starting | `name`, `input` |
-| `tool_call.complete` | Tool execution done | `name`, `result` |
+Called when a tool returns its result:
+
+```ruby
+robot.on_tool_result do |tool_call, result|
+  puts "Tool #{tool_call.name} returned: #{result}"
+end
+```
 
-## Comprehensive Event Handling
+## Comprehensive Callback Setup
 
-Handle all event types in a single block:
+Register all callbacks for full visibility:
 
 ```ruby
-robot.run("Analyze this data and generate a report") do |event|
-  case event[:event]
-  when "text.delta"
-    print event[:data][:content]
-  when "tool_call.start"
-    puts "\n[Tool] Calling: #{event[:data][:name]}"
-  when "tool_call.complete"
-    puts "[Tool] Done: #{event[:data][:name]}"
-  when "run.completed"
-    puts "\n--- Complete ---"
-  when "run.failed"
-    puts "\n[Error] #{event[:data][:error]}"
-  end
+robot = RobotLab.build(
+  name: "assistant",
+  system_prompt: "You are helpful.",
+  local_tools: [WeatherTool]
+)
+
+robot.on_new_message do |message|
+  print message.content if message.content
+end
+
+robot.on_end_message do |_message|
+  puts "\n--- Done ---"
+end
+
+robot.on_tool_call do |tool_call|
+  puts "\n[Tool] Calling: #{tool_call.name}"
+end
+
+robot.on_tool_result do |tool_call, result|
+  puts "[Tool] #{tool_call.name} returned: #{result}"
 end
+
+result = robot.run("What's the weather in Tokyo?")
 ```
 
+## Streaming via Chat Block
+
+For more control, pass a block directly to `chat.ask` (the underlying RubyLLM method):
+
+```ruby
+robot = RobotLab.build(
+  name: "chat_bot",
+  system_prompt: "You are a helpful assistant."
+)
+
+# Use the underlying chat directly with a streaming block
+robot.chat.ask("Tell me a story") do |chunk|
+  print chunk.content if chunk.content
+end
+```
+
+Note: Using `chat.ask` directly bypasses Robot's memory resolution and tool hierarchy. Use callbacks with `robot.run` when you need those features.
+
 ## Web Integration
 
 ### Rails Action Cable
@@ -107,9 +123,15 @@ class ChatChannel < ApplicationCable::Channel
       system_prompt: "You are a helpful chat assistant."
     )
 
-    robot.run(data["message"]) do |event|
-      transmit(event)
+    robot.on_new_message do |message|
+      transmit({ event: "text.delta", content: message.content }) if message.content
     end
+
+    robot.on_end_message do |_message|
+      transmit({ event: "run.completed" })
+    end
+
+    robot.run(data["message"])
   end
 end
 ```
@@ -128,9 +150,15 @@ class StreamController < ApplicationController
       system_prompt: "You are helpful."
     )
 
-    robot.run(params[:message]) do |event|
-      response.stream.write("data: #{event.to_json}\n\n")
+    robot.on_new_message do |message|
+      response.stream.write("data: #{message.content}\n\n") if message.content
+    end
+
+    robot.on_end_message do |_message|
+      response.stream.write("data: [DONE]\n\n")
     end
+
+    robot.run(params[:message])
   ensure
     response.stream.close
   end
@@ -142,38 +170,17 @@ end
 ```ruby
 # Using Faye WebSocket
 ws.on :message do |msg|
-  robot.run(msg.data) do |event|
-    ws.send(event.to_json)
+  robot.on_new_message do |message|
+    ws.send(message.content) if message.content
   end
-end
-```
-
-## Buffering
 
-Buffer content for batch processing:
-
-```ruby
-buffer = []
-
-robot.run("Generate a long response") do |event|
-  if event[:event] == "text.delta"
-    buffer << event[:data][:content]
-
-    # Flush every 10 chunks
-    if buffer.size >= 10
-      process_batch(buffer.join)
-      buffer.clear
-    end
-  end
+  robot.run(msg.data)
 end
-
-# Final flush
-process_batch(buffer.join) if buffer.any?
 ```
 
 ## Progress Tracking
 
-Track streaming progress:
+Track streaming progress with callbacks:
 
 ```ruby
 class StreamProgress
@@ -182,49 +189,31 @@ class StreamProgress
     @tools = 0
   end
 
-  def handle(event)
-    case event[:event]
-    when "text.delta"
-      @chars += event[:data][:content].length
+  attr_reader :chars, :tools
+
+  def attach(robot)
+    robot.on_new_message do |message|
+      @chars += message.content.length if message.content
       print "\rReceived #{@chars} characters..."
-    when "tool_call.start"
+    end
+
+    robot.on_tool_call do |tool_call|
       @tools += 1
-      puts "\nTool call ##{@tools}: #{event[:data][:name]}"
+      puts "\nTool call ##{@tools}: #{tool_call.name}"
     end
   end
 end
 
 progress = StreamProgress.new
+progress.attach(robot)
 
-robot.run("Process this complex request") do |event|
-  progress.handle(event)
-end
-```
-
-## Error Handling
-
-Handle streaming errors gracefully:
-
-```ruby
-robot.run("Analyze this") do |event|
-  case event[:event]
-  when "run.failed"
-    log_error(event[:data][:error])
-    notify_user("An error occurred")
-  when "text.delta"
-    begin
-      broadcast(event)
-    rescue BroadcastError => e
-      # Client disconnected, but continue processing
-      logger.warn "Broadcast failed: #{e.message}"
-    end
-  end
-end
+result = robot.run("Process this complex request")
+puts "\nTotal: #{progress.chars} chars, #{progress.tools} tool calls"
 ```
 
 ## Without Streaming
 
-When streaming is not needed, simply call `run` without a block:
+When streaming is not needed, simply call `run` without registering callbacks:
 
 ```ruby
 # No streaming - returns RobotResult directly
@@ -234,33 +223,23 @@ puts result.last_text_content
 
 ## Best Practices
 
-### 1. Handle All Event Types
+### 1. Register Callbacks Before Run
 
 ```ruby
-robot.run("Hello") do |event|
-  case event[:event]
-  when "text.delta" then handle_delta(event)
-  when "tool_call.start" then show_tool_indicator(event)
-  when "tool_call.complete" then hide_tool_indicator(event)
-  when "run.completed" then finalize_response
-  when "run.failed" then show_error(event)
-  end
-end
+# Correct: register first, then run
+robot.on_new_message { |msg| print msg.content if msg.content }
+robot.run("Hello")
 ```
 
-### 2. Provide User Feedback
+### 2. Handle Errors in Callbacks
 
 ```ruby
-robot.run("Process my request") do |event|
-  case event[:event]
-  when "run.started"
-    show_typing_indicator
-  when "text.delta"
-    update_message(event[:data][:content])
-  when "tool_call.start"
-    show_status("Looking up information...")
-  when "run.completed"
-    hide_typing_indicator
+robot.on_new_message do |message|
+  begin
+    broadcast(message.content) if message.content
+  rescue BroadcastError => e
+    # Client disconnected, but continue processing
+    logger.warn "Broadcast failed: #{e.message}"
   end
 end
 ```
@@ -269,9 +248,10 @@ end
 
 ```ruby
 begin
-  robot.run("Hello") do |event|
-    stream_to_client(event)
+  robot.on_new_message do |message|
+    stream_to_client(message.content) if message.content
   end
+  robot.run("Hello")
 ensure
   close_stream_connection
 end

data/docs/index.md

@@ -68,14 +68,6 @@ Each robot is backed by a persistent LLM chat, configured with keyword arguments
 
     [:octicons-arrow-right-24: Memory System](guides/memory.md)
 
--   :material-history:{ .lg .middle } **Conversation History**
-
-    ---
-
-    Persist and restore conversation threads for long-running interactions.
-
-    [:octicons-arrow-right-24: History Guide](guides/history.md)
-
 </div>
 
 ## Quick Example

data/examples/03_network.rb

@@ -39,33 +39,36 @@ class ClassifierRobot < RobotLab::Robot
   end
 end
 
-# Create specialized robots
+# Shared RunConfig — all robots in this network use the same model
+shared_config = RobotLab::RunConfig.new(model: "claude-3-haiku-20240307")
+
+# Create specialized robots (no model: needed — inherited from RunConfig)
 classifier = ClassifierRobot.new(
   name: "classifier",
   template: :classifier,
-  model: "claude-3-haiku-20240307"
+  config: shared_config
 )
 
 billing_robot = RobotLab.build(
   name: "billing",
   template: :billing,
-  model: "claude-3-haiku-20240307"
+  config: shared_config
 )
 
 technical_robot = RobotLab.build(
   name: "technical",
   template: :technical,
-  model: "claude-3-haiku-20240307"
+  config: shared_config
 )
 
 general_robot = RobotLab.build(
   name: "general",
   template: :general,
-  model: "claude-3-haiku-20240307"
+  config: shared_config
 )
 
-# Create network with optional task routing
-network = RobotLab.create_network(name: "support_network") do
+# Create network with optional task routing and shared config
+network = RobotLab.create_network(name: "support_network", config: shared_config) do
   task :classifier, classifier, depends_on: :none
   task :billing, billing_robot, depends_on: :optional
   task :technical, technical_robot, depends_on: :optional

data/examples/08_llm_config.rb

@@ -77,20 +77,43 @@ puts "-" * 70
 puts "Configuration hierarchy (highest priority first):"
 puts
 puts "  Per-Robot (override global settings for a specific robot):"
-puts "  9. Run-time context:      kwargs to robot.run re-render template"
-puts "  8. with_* methods:        robot.with_temperature(0.9).ask(...)"
-puts "  7. Constructor params:    Robot.new(model: ..., temperature: ...)"
-puts "  6. Template front matter: model, temperature, etc. in .md YAML header"
+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 "  5. Environment variables: ROBOT_LAB_RUBY_LLM__MODEL, etc."
-puts "  4. Project config:        ./config/robot_lab.yml"
-puts "  3. User config:           ~/.config/robot_lab/config.yml"
-puts "  2. Environment overrides: #{env} section in defaults.yml"
-puts "  1. Bundled defaults:      lib/robot_lab/config/defaults.yml"
+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",
@@ -124,9 +147,15 @@ puts <<~FOOTER
   #{"=" * 70}
   Configuration demonstrated successfully!
 
-  Configuration flows through two layers:
+  Configuration flows through three layers:
     Global (MywayConfig): YAML defaults, env overrides, XDG, env vars
-    Per-Robot: template front matter, constructor params, with_* methods
+    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

data/examples/09_chaining.rb

@@ -136,10 +136,49 @@ prev2 = show_config(robot2)
 puts
 
 # =============================================================================
-# Section 5: Bare robot with chaining
+# Section 5: RunConfig as alternative to individual kwargs
 # =============================================================================
 
-puts "--- Section 5: Bare Robot with Chaining ---"
+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.
@@ -158,10 +197,10 @@ prev_bare = show_config(bare, prev_bare)
 puts
 
 # =============================================================================
-# Section 6: with_template() on an existing robot
+# Section 7: with_template() on an existing robot
 # =============================================================================
 
-puts "--- Section 6: with_template() on Existing Robot ---"
+puts "--- Section 7: with_template() on Existing Robot ---"
 puts
 
 # You can apply a template to a robot after creation.
@@ -172,10 +211,10 @@ show_config(bare, prev_bare)
 puts
 
 # =============================================================================
-# Section 7: AskUser tool for gathering template parameters
+# Section 8: AskUser tool for gathering template parameters
 # =============================================================================
 
-puts "--- Section 7: AskUser for 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"

data/examples/11_network_introspection.rb

@@ -55,16 +55,22 @@ puts "Example 11: Network Visualization & Introspection"
 puts "=" * 70
 puts
 
+# Shared RunConfig for all robots in this network
+shared_config = RobotLab::RunConfig.new(model: "claude-sonnet-4", temperature: 0.5)
+
+# Per-task RunConfig override for the writer (higher creativity)
+creative_config = RobotLab::RunConfig.new(temperature: 0.9)
+
 # Build robots (no LLM calls, just instances)
 classifier = RobotLab.build(name: "classifier", system_prompt: "Classify input")
 analyst    = RobotLab.build(name: "analyst",    system_prompt: "Analyze data")
 writer     = RobotLab.build(name: "writer",     system_prompt: "Write summary")
 
-# Build network with dependencies and per-task config
-network = RobotLab.create_network(name: "demo_pipeline") do
+# Build network with RunConfig, dependencies, and per-task config
+network = RobotLab.create_network(name: "demo_pipeline", config: shared_config) do
   task :classify, classifier, depends_on: :none
   task :analyze, analyst, context: { depth: "deep" }, depends_on: [:classify]
-  task :write, writer, depends_on: [:analyze]
+  task :write, writer, config: creative_config, depends_on: [:analyze]
 end
 
 # =============================================================================
@@ -179,10 +185,27 @@ ap network["analyze"].to_h
 puts
 
 # =============================================================================
-# Section 5: Broadcast
+# Section 5: RunConfig Introspection
+# =============================================================================
+
+puts "--- Section 5: RunConfig Introspection ---"
+puts
+
+puts "Network RunConfig (shared defaults):"
+ap network.config.to_h
+puts
+
+puts "Merged effective config for :write task (network + task override):"
+effective = shared_config.merge(creative_config)
+ap effective.to_h
+puts "  model inherited from network, temperature overridden by task"
+puts
+
+# =============================================================================
+# Section 6: Broadcast
 # =============================================================================
 
-puts "--- Section 5: Broadcast ---"
+puts "--- Section 6: Broadcast ---"
 puts
 
 broadcast_messages = []
@@ -207,10 +230,10 @@ end
 puts
 
 # =============================================================================
-# Section 6: Shared memory access
+# Section 7: Shared memory access
 # =============================================================================
 
-puts "--- Section 6: Shared Network Memory ---"
+puts "--- Section 7: Shared Network Memory ---"
 puts
 
 puts "network.memory is a #{network.memory.class}"

data/examples/12_message_bus.rb

@@ -31,7 +31,7 @@ class Comedian < RobotLab::Robot
       with_temperature(temp)
       joke = run(message.content.to_s).reply.strip
       puts "  Bob  [##{@attempts}, t=#{"%.1f" % temp}]: #{joke}"
-      reply(message, joke)
+      send_reply(to: message.from.to_sym, content: joke, in_reply_to: message.key)
     end
   end