robot_lab 0.0.1 → 0.0.6

data/docs/guides/streaming.md

@@ -2,107 +2,115 @@
 
 Stream LLM responses in real-time for better user experience.
 
-## Basic Streaming
+## Streaming via Callbacks
 
-Pass a callback to receive streaming events:
+RobotLab robots support streaming through callback methods inherited from RubyLLM::Agent. Register callbacks before calling `run`:
 
 ```ruby
-robot.run(
-  state: state,
-  network: network,
-  streaming: ->(event) {
-    puts event.inspect
-  }
+robot = RobotLab.build(
+  name: "storyteller",
+  system_prompt: "You are a creative storyteller."
 )
+
+# 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's generated:
+Called when the assistant starts generating a new message, with streaming chunks:
 
 ```ruby
-streaming: ->(event) {
-  if event[:event] == "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
-streaming: ->(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
-streaming: ->(event) {
-  case event[:event]
-  when "run.started"
-    puts "Starting run #{event[:data][:run_id]}"
-  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` | Network run began | `run_id`, `network` |
-| `run.completed` | Network run finished | `run_id`, `robot_count` |
-| `run.failed` | Error occurred | `run_id`, `error` |
-| `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:
 
-## Streaming Context
+```ruby
+robot.on_tool_result do |tool_call, result|
+  puts "Tool #{tool_call.name} returned: #{result}"
+end
+```
 
-For advanced control, use `Streaming::Context`:
+## Comprehensive Callback Setup
+
+Register all callbacks for full visibility:
 
 ```ruby
-context = RobotLab::Streaming::Context.new(
-  run_id: SecureRandom.uuid,
-  message_id: SecureRandom.uuid,
-  scope: "network",
-  publish: ->(event) { broadcast_to_client(event) }
+robot = RobotLab.build(
+  name: "assistant",
+  system_prompt: "You are helpful.",
+  local_tools: [WeatherTool]
 )
-```
 
-### Context Properties
+robot.on_new_message do |message|
+  print message.content if message.content
+end
 
-```ruby
-context.run_id      # Unique run identifier
-context.message_id  # Unique message identifier
-context.scope       # "network" or "robot"
+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?")
 ```
 
-### Publishing Events
+## Streaming via Chat Block
+
+For more control, pass a block directly to `chat.ask` (the underlying RubyLLM method):
 
 ```ruby
-context.publish_event(
-  event: "custom.event",
-  data: { key: "value" }
+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
@@ -110,14 +118,20 @@ context.publish_event(
 ```ruby
 class ChatChannel < ApplicationCable::Channel
   def receive(data)
-    state = RobotLab.create_state(message: data["message"])
-
-    network.run(
-      state: state,
-      streaming: ->(event) {
-        transmit(event)
-      }
+    robot = RobotLab.build(
+      name: "chat_bot",
+      system_prompt: "You are a helpful chat assistant."
     )
+
+    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
 ```
@@ -131,14 +145,20 @@ class StreamController < ApplicationController
   def create
     response.headers["Content-Type"] = "text/event-stream"
 
-    state = RobotLab.create_state(message: params[:message])
-
-    network.run(
-      state: state,
-      streaming: ->(event) {
-        response.stream.write("data: #{event.to_json}\n\n")
-      }
+    robot = RobotLab.build(
+      name: "stream_bot",
+      system_prompt: "You are helpful."
     )
+
+    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
@@ -150,62 +170,17 @@ end
 ```ruby
 # Using Faye WebSocket
 ws.on :message do |msg|
-  state = RobotLab.create_state(message: msg.data)
-
-  network.run(
-    state: state,
-    streaming: ->(event) {
-      ws.send(event.to_json)
-    }
-  )
-end
-```
-
-## Event Filtering
-
-### Check Event Type
-
-```ruby
-streaming: ->(event) {
-  return unless RobotLab::Streaming::Events.delta?(event)
-  print event[:data][:content]
-}
-```
-
-### Available Predicates
-
-```ruby
-Streaming::Events.lifecycle?(event)  # run.started, run.completed, etc.
-Streaming::Events.delta?(event)       # Text content
-Streaming::Events.valid?(event)       # Has required fields
-```
-
-## Buffering
-
-Buffer content for batch processing:
-
-```ruby
-buffer = []
-
-streaming: ->(event) {
-  if event[:event] == "delta"
-    buffer << event[:data][:content]
-
-    # Flush every 10 chunks
-    if buffer.size >= 10
-      process_batch(buffer.join)
-      buffer.clear
-    end
+  robot.on_new_message do |message|
+    ws.send(message.content) if message.content
   end
-}
 
-# Don't forget final flush
-process_batch(buffer.join) if buffer.any?
+  robot.run(msg.data)
+end
 ```
 
 ## Progress Tracking
 
-Track streaming progress:
+Track streaming progress with callbacks:
 
 ```ruby
 class StreamProgress
@@ -214,94 +189,69 @@ class StreamProgress
     @tools = 0
   end
 
-  def handle(event)
-    case event[:event]
-    when "delta"
-      @chars += event[:data][:content].length
-      puts "\rReceived #{@chars} characters..."
-    when "tool_call.start"
+  attr_reader :chars, :tools
+
+  def attach(robot)
+    robot.on_new_message do |message|
+      @chars += message.content.length if message.content
+      print "\rReceived #{@chars} characters..."
+    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
-network.run(state: state, streaming: progress.method(:handle))
-```
-
-## Error Handling
-
-Handle streaming errors gracefully:
+progress.attach(robot)
 
-```ruby
-streaming: ->(event) {
-  case event[:event]
-  when "run.failed"
-    log_error(event[:data][:error])
-    notify_user("An error occurred")
-  when "delta"
-    begin
-      broadcast(event)
-    rescue BroadcastError => e
-      # Client disconnected, but continue processing
-      logger.warn "Broadcast failed: #{e.message}"
-    end
-  end
-}
+result = robot.run("Process this complex request")
+puts "\nTotal: #{progress.chars} chars, #{progress.tools} tool calls"
 ```
 
-## Disabling Streaming
+## Without Streaming
 
-Disable streaming when not needed:
+When streaming is not needed, simply call `run` without registering callbacks:
 
 ```ruby
-RobotLab.configure do |config|
-  config.streaming_enabled = false
-end
-
-# Or per-run
-network.run(state: state, streaming: nil)
+# No streaming - returns RobotResult directly
+result = robot.run("Hello!")
+puts result.last_text_content
 ```
 
 ## Best Practices
 
-### 1. Handle All Event Types
+### 1. Register Callbacks Before Run
 
 ```ruby
-streaming: ->(event) {
-  case event[:event]
-  when "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
-}
+# 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
-streaming: ->(event) {
-  case event[:event]
-  when "run.started"
-    show_typing_indicator
-  when "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
 ```
 
 ### 3. Clean Up Resources
 
 ```ruby
 begin
-  network.run(state: state, streaming: callback)
+  robot.on_new_message do |message|
+    stream_to_client(message.content) if message.content
+  end
+  robot.run("Hello")
 ensure
   close_stream_connection
 end