robot_lab 0.0.1

data/docs/api/messages/user-message.md

@@ -0,0 +1,171 @@
+# UserMessage
+
+User input with conversation metadata.
+
+## Class: `RobotLab::UserMessage`
+
+```ruby
+message = UserMessage.new(
+  "What's my order status?",
+  thread_id: "thread_123",
+  system_prompt: "Be concise",
+  metadata: { source: "web" }
+)
+```
+
+## Constructor
+
+```ruby
+UserMessage.new(content, thread_id: nil, system_prompt: nil, metadata: {})
+```
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `content` | `String` | Message text |
+| `thread_id` | `String`, `nil` | Conversation thread ID |
+| `system_prompt` | `String`, `nil` | Override system prompt |
+| `metadata` | `Hash` | Additional metadata |
+
+## Attributes
+
+### content
+
+```ruby
+message.content  # => String
+```
+
+The message text.
+
+### thread_id
+
+```ruby
+message.thread_id  # => String | nil
+```
+
+Conversation thread identifier for history persistence.
+
+### system_prompt
+
+```ruby
+message.system_prompt  # => String | nil
+```
+
+Optional system prompt override for this message.
+
+### metadata
+
+```ruby
+message.metadata  # => Hash
+```
+
+Arbitrary metadata (source, timestamp, user info, etc.).
+
+### id
+
+```ruby
+message.id  # => String (UUID)
+```
+
+Unique message identifier.
+
+### created_at
+
+```ruby
+message.created_at  # => Time
+```
+
+Message creation timestamp.
+
+### role
+
+```ruby
+message.role  # => :user
+```
+
+Always returns `:user`.
+
+## Methods
+
+### to_h
+
+```ruby
+message.to_h  # => Hash
+```
+
+Hash representation.
+
+**Returns:**
+
+```ruby
+{
+  role: :user,
+  content: "What's my order status?",
+  id: "uuid-here",
+  thread_id: "thread_123",
+  created_at: "2024-01-15T10:30:00Z"
+}
+```
+
+### to_json
+
+```ruby
+message.to_json  # => String
+```
+
+JSON representation.
+
+## Examples
+
+### Basic Message
+
+```ruby
+message = UserMessage.new("Hello!")
+```
+
+### With Thread ID
+
+```ruby
+message = UserMessage.new(
+  "Continue our conversation",
+  thread_id: "thread_abc123"
+)
+```
+
+### With System Prompt Override
+
+```ruby
+message = UserMessage.new(
+  "Translate this",
+  system_prompt: "You are a translator. Respond in Spanish."
+)
+```
+
+### With Metadata
+
+```ruby
+message = UserMessage.new(
+  "Help with my account",
+  metadata: {
+    source: "mobile_app",
+    user_id: "user_123",
+    session_id: "sess_456",
+    locale: "en-US"
+  }
+)
+```
+
+### Creating State
+
+```ruby
+message = UserMessage.new("Help", thread_id: "thread_123")
+state = RobotLab.create_state(message: message)
+
+state.thread_id  # => "thread_123"
+```
+
+## See Also
+
+- [State](../core/state.md)
+- [TextMessage](text-message.md)

data/docs/api/streaming/context.md

@@ -0,0 +1,174 @@
+# StreamingContext
+
+Manages streaming state during execution.
+
+## Class: `RobotLab::Streaming::Context`
+
+```ruby
+context = RobotLab::Streaming::Context.new(callback: ->(e) { handle(e) })
+```
+
+## Constructor
+
+```ruby
+Context.new(callback:, robot: nil, network: nil)
+```
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `callback` | `Proc` | Event handler |
+| `robot` | `Robot`, `nil` | Current robot |
+| `network` | `NetworkRun`, `nil` | Network context |
+
+## Attributes
+
+### callback
+
+```ruby
+context.callback  # => Proc
+```
+
+The event handler callback.
+
+### robot
+
+```ruby
+context.robot  # => Robot | nil
+```
+
+The currently executing robot.
+
+### network
+
+```ruby
+context.network  # => NetworkRun | nil
+```
+
+The network run context.
+
+### buffer
+
+```ruby
+context.buffer  # => String
+```
+
+Accumulated text content.
+
+### tool_calls
+
+```ruby
+context.tool_calls  # => Array<ToolCallMessage>
+```
+
+Tool calls received during streaming.
+
+## Methods
+
+### emit
+
+```ruby
+context.emit(event)
+```
+
+Send an event to the callback.
+
+### emit_text
+
+```ruby
+context.emit_text(text)
+```
+
+Emit a text delta event.
+
+### emit_tool_call
+
+```ruby
+context.emit_tool_call(id:, name:, input:)
+```
+
+Emit a tool call event.
+
+### emit_error
+
+```ruby
+context.emit_error(error)
+```
+
+Emit an error event.
+
+### complete
+
+```ruby
+context.complete
+```
+
+Signal streaming completion.
+
+### for_robot
+
+```ruby
+new_context = context.for_robot(robot)
+```
+
+Create a child context for a specific robot.
+
+## Examples
+
+### Custom Context
+
+```ruby
+context = RobotLab::Streaming::Context.new(
+  callback: ->(event) {
+    case event.type
+    when :text_delta
+      @output << event.text
+    when :complete
+      process_output(@output)
+    end
+  }
+)
+
+# Pass to robot
+robot.run(state: state, streaming: context)
+```
+
+### Accumulating Content
+
+```ruby
+context = RobotLab::Streaming::Context.new(
+  callback: ->(event) {
+    print event.text if event.type == :text_delta
+  }
+)
+
+robot.run(state: state, streaming: context)
+
+# Access accumulated content
+puts "Total content: #{context.buffer}"
+puts "Tool calls: #{context.tool_calls.size}"
+```
+
+### Network Context
+
+```ruby
+context = RobotLab::Streaming::Context.new(
+  callback: ->(event) {
+    prefix = event.robot_name ? "[#{event.robot_name}] " : ""
+    case event.type
+    when :text_delta
+      print "#{prefix}#{event.text}"
+    when :robot_complete
+      puts "\n#{prefix}Complete"
+    end
+  }
+)
+
+network.run(state: state, streaming: context)
+```
+
+## See Also
+
+- [Streaming Overview](index.md)
+- [Events](events.md)

data/docs/api/streaming/events.md

@@ -0,0 +1,237 @@
+# Streaming Events
+
+Event types for real-time response handling.
+
+## Class: `RobotLab::Streaming::Event`
+
+```ruby
+event.type        # => Symbol
+event.text        # => String (for text events)
+event.robot_name  # => String (for robot events)
+```
+
+## Event Types
+
+### :start
+
+Streaming has begun.
+
+```ruby
+case event.type
+when :start
+  puts "Starting..."
+end
+```
+
+**Attributes:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `robot_name` | `String`, `nil` | Robot name |
+
+### :text_delta
+
+A chunk of text was received.
+
+```ruby
+case event.type
+when :text_delta
+  print event.text
+end
+```
+
+**Attributes:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `text` | `String` | Text content |
+| `robot_name` | `String`, `nil` | Source robot |
+
+### :tool_call
+
+A tool is being invoked.
+
+```ruby
+case event.type
+when :tool_call
+  puts "Calling #{event.name} with #{event.input}"
+end
+```
+
+**Attributes:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `id` | `String` | Tool call ID |
+| `name` | `String` | Tool name |
+| `input` | `Hash` | Tool parameters |
+| `robot_name` | `String`, `nil` | Source robot |
+
+### :tool_result
+
+A tool has returned a result.
+
+```ruby
+case event.type
+when :tool_result
+  puts "#{event.name} returned: #{event.result}"
+end
+```
+
+**Attributes:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `id` | `String` | Tool call ID |
+| `name` | `String` | Tool name |
+| `result` | `Object` | Tool result |
+| `robot_name` | `String`, `nil` | Source robot |
+
+### :robot_start
+
+A robot has started executing (network only).
+
+```ruby
+case event.type
+when :robot_start
+  puts "Robot #{event.robot_name} starting"
+end
+```
+
+**Attributes:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `robot_name` | `String` | Robot name |
+
+### :robot_complete
+
+A robot has finished executing (network only).
+
+```ruby
+case event.type
+when :robot_complete
+  puts "Robot #{event.robot_name} finished"
+end
+```
+
+**Attributes:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `robot_name` | `String` | Robot name |
+| `result` | `RobotResult` | Execution result |
+
+### :complete
+
+All streaming has finished.
+
+```ruby
+case event.type
+when :complete
+  puts "All done!"
+end
+```
+
+### :error
+
+An error occurred.
+
+```ruby
+case event.type
+when :error
+  puts "Error: #{event.error.message}"
+end
+```
+
+**Attributes:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `error` | `Exception` | The error |
+| `robot_name` | `String`, `nil` | Source robot |
+
+## Examples
+
+### Complete Handler
+
+```ruby
+robot.run(state: state) do |event|
+  case event.type
+  when :start
+    puts "=== Starting ==="
+  when :text_delta
+    print event.text
+  when :tool_call
+    puts "\n[Tool: #{event.name}]"
+  when :tool_result
+    puts "[Result: #{event.result.to_s.truncate(50)}]"
+  when :complete
+    puts "\n=== Complete ==="
+  when :error
+    puts "\n!!! Error: #{event.error.message}"
+  end
+end
+```
+
+### Network Handler
+
+```ruby
+network.run(state: state) do |event|
+  robot = event.robot_name || "system"
+
+  case event.type
+  when :robot_start
+    puts "[#{robot}] Starting..."
+  when :text_delta
+    print event.text
+  when :tool_call
+    puts "\n[#{robot}] Calling #{event.name}"
+  when :robot_complete
+    puts "\n[#{robot}] Complete"
+  when :error
+    puts "\n[#{robot}] Error: #{event.error.message}"
+  end
+end
+```
+
+### Filtering Events
+
+```ruby
+# Only text
+robot.run(state: state) do |event|
+  print event.text if event.type == :text_delta
+end
+
+# Only tools
+robot.run(state: state) do |event|
+  if event.type == :tool_call
+    log_tool_usage(event.name, event.input)
+  end
+end
+```
+
+### Async Processing
+
+```ruby
+queue = Queue.new
+
+Thread.new do
+  loop do
+    event = queue.pop
+    break if event == :done
+    process_event(event)
+  end
+end
+
+robot.run(state: state) do |event|
+  queue << event
+  queue << :done if event.type == :complete
+end
+```
+
+## See Also
+
+- [Streaming Overview](index.md)
+- [StreamingContext](context.md)
+- [Streaming Guide](../../guides/streaming.md)

data/docs/api/streaming/index.md

@@ -0,0 +1,108 @@
+# Streaming
+
+Real-time response streaming from LLM providers.
+
+## Overview
+
+Streaming allows you to receive LLM responses in real-time, token by token, enabling responsive user interfaces and progressive content display.
+
+```ruby
+result = robot.run(state: state) do |event|
+  case event.type
+  when :text_delta
+    print event.text
+  when :tool_call
+    puts "\nCalling tool: #{event.name}"
+  when :complete
+    puts "\nDone!"
+  end
+end
+```
+
+## Components
+
+| Component | Description |
+|-----------|-------------|
+| [Context](context.md) | Streaming context and state |
+| [Events](events.md) | Event types and handling |
+
+## Quick Start
+
+### Basic Streaming
+
+```ruby
+robot.run(state: state) do |event|
+  print event.text if event.type == :text_delta
+end
+```
+
+### With Network
+
+```ruby
+network.run(state: state) do |event|
+  case event.type
+  when :robot_start
+    puts "Robot #{event.robot_name} starting..."
+  when :text_delta
+    print event.text
+  when :robot_complete
+    puts "\nRobot #{event.robot_name} complete"
+  end
+end
+```
+
+## Event Types
+
+| Event | Description |
+|-------|-------------|
+| `:start` | Streaming started |
+| `:text_delta` | Text chunk received |
+| `:tool_call` | Tool being called |
+| `:tool_result` | Tool result received |
+| `:robot_start` | Robot execution started |
+| `:robot_complete` | Robot execution finished |
+| `:complete` | All streaming finished |
+| `:error` | Error occurred |
+
+## Callback Patterns
+
+### Proc/Lambda
+
+```ruby
+callback = ->(event) {
+  print event.text if event.type == :text_delta
+}
+
+robot.run(state: state, streaming: callback)
+```
+
+### Block
+
+```ruby
+robot.run(state: state) do |event|
+  print event.text if event.type == :text_delta
+end
+```
+
+### Object with `call`
+
+```ruby
+class StreamHandler
+  def call(event)
+    case event.type
+    when :text_delta
+      broadcast(event.text)
+    when :error
+      log_error(event.error)
+    end
+  end
+end
+
+robot.run(state: state, streaming: StreamHandler.new)
+```
+
+## See Also
+
+- [Streaming Guide](../../guides/streaming.md)
+- [Robot](../core/robot.md)
+- [Network](../core/network.md)