robot_lab 0.0.1 → 0.0.6

data/docs/api/streaming/context.md

@@ -1,171 +1,254 @@
-# StreamingContext
+# Streaming::Context
 
-Manages streaming state during execution.
+Manages streaming event publishing with automatic sequencing, timestamping, and ID generation.
 
 ## Class: `RobotLab::Streaming::Context`
 
 ```ruby
-context = RobotLab::Streaming::Context.new(callback: ->(e) { handle(e) })
+context = RobotLab::Streaming::Context.new(
+  run_id: "run_123",
+  message_id: "msg_456",
+  scope: "network",
+  publish: ->(event) { broadcast(event) }
+)
+
+context.publish_event(event: "text.delta", data: { delta: "Hello" })
 ```
 
 ## Constructor
 
 ```ruby
-Context.new(callback:, robot: nil, network: nil)
+Context.new(
+  run_id:,
+  message_id:,
+  scope:,
+  publish:,
+  parent_run_id: nil,
+  sequence_counter: nil
+)
 ```
 
 **Parameters:**
 
-| Name | Type | Description |
-|------|------|-------------|
-| `callback` | `Proc` | Event handler |
-| `robot` | `Robot`, `nil` | Current robot |
-| `network` | `NetworkRun`, `nil` | Network context |
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `run_id` | `String` | required | Unique identifier for this run |
+| `message_id` | `String` | required | Current message identifier |
+| `scope` | `String`, `Symbol` | required | Context scope (e.g., `"network"`, `"robot"`) |
+| `publish` | `Proc` | required | Callback invoked with each event hash |
+| `parent_run_id` | `String`, `nil` | `nil` | Parent run identifier for nested contexts |
+| `sequence_counter` | `SequenceCounter`, `nil` | `nil` | Shared sequence counter (creates new one if nil) |
 
 ## Attributes
 
-### callback
+### run_id
 
 ```ruby
-context.callback  # => Proc
+context.run_id  # => String
 ```
 
-The event handler callback.
+The unique run identifier for this context.
 
-### robot
+### parent_run_id
 
 ```ruby
-context.robot  # => Robot | nil
+context.parent_run_id  # => String | nil
 ```
 
-The currently executing robot.
+The parent run identifier. Set when this is a child context created by `create_child_context`.
 
-### network
+### message_id
 
 ```ruby
-context.network  # => NetworkRun | nil
+context.message_id  # => String
 ```
 
-The network run context.
+The current message identifier.
 
-### buffer
+### scope
 
 ```ruby
-context.buffer  # => String
+context.scope  # => String
 ```
 
-Accumulated text content.
+The context scope (converted to string). Typically `"network"` or `"robot"`.
+
+## Methods
 
-### tool_calls
+### publish_event
 
 ```ruby
-context.tool_calls  # => Array<ToolCallMessage>
+chunk = context.publish_event(event:, data: {})
 ```
 
-Tool calls received during streaming.
+Publish a streaming event. The event is wrapped in a chunk with automatic sequencing, timestamping, and context metadata injection.
 
-## Methods
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `event` | `String` | Event type (e.g., `"text.delta"`, `"run.started"`) |
+| `data` | `Hash` | Event payload (default: `{}`) |
+
+**Returns:** The constructed event chunk hash.
 
-### emit
+The chunk structure:
 
 ```ruby
-context.emit(event)
+{
+  event: "text.delta",
+  data: {
+    delta: "Hello",          # from data parameter
+    run_id: "run_123",       # injected from context
+    message_id: "msg_456",   # injected from context
+    scope: "robot"           # injected from context
+  },
+  timestamp: 1707900000000,  # millisecond Unix timestamp
+  sequence_number: 1,        # monotonically increasing
+  id: "publish-1:text.delta" # unique event ID
+}
 ```
 
-Send an event to the callback.
+If the publish callback raises an error, it is caught and logged as a warning via `RobotLab.config.logger`. The chunk is still returned.
 
-### emit_text
+### create_child_context
 
 ```ruby
-context.emit_text(text)
+child = context.create_child_context(robot_run_id)
 ```
 
-Emit a text delta event.
+Create a child context for a nested robot execution. The child shares the same publish callback and sequence counter, ensuring events are ordered globally across the parent and child.
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `robot_run_id` | `String` | Run ID for the child context |
+
+**Returns:** A new `Context` with:
+- `run_id` set to `robot_run_id`
+- `parent_run_id` set to the current context's `run_id`
+- `scope` set to `"robot"`
+- A new `message_id` (generated UUID)
+- Shared `sequence_counter` and `publish` callback
 
-### emit_tool_call
+### create_context_with_shared_sequence
 
 ```ruby
-context.emit_tool_call(id:, name:, input:)
+sibling = context.create_context_with_shared_sequence(
+  run_id: "run_789",
+  message_id: "msg_789",
+  scope: "robot"
+)
 ```
 
-Emit a tool call event.
+Create a new context that shares the same sequence counter as this context, but with different identifiers.
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `run_id` | `String` | Run ID for the new context |
+| `message_id` | `String` | Message ID for the new context |
+| `scope` | `String` | Scope for the new context |
+
+**Returns:** A new `Context` sharing the sequence counter and publish callback.
 
-### emit_error
+### generate_part_id
 
 ```ruby
-context.emit_error(error)
+context.generate_part_id  # => "part_run_1234_900123_a1b2c3d4"
 ```
 
-Emit an error event.
+Generate an OpenAI-compatible part ID (max 40 characters). Combines a truncated message ID, a timestamp suffix, and random hex.
 
-### complete
+### generate_step_id
 
 ```ruby
-context.complete
+context.generate_step_id("text_output")  # => "publish-3:text_output"
 ```
 
-Signal streaming completion.
+Generate a step ID for durable execution compatibility. Uses the current sequence number.
 
-### for_robot
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `base_name` | `String` | Base name for the step |
+
+### generate_message_id
 
 ```ruby
-new_context = context.for_robot(robot)
+context.generate_message_id  # => "a1b2c3d4-..."
 ```
 
-Create a child context for a specific robot.
+Generate a new UUID for use as a message identifier.
 
 ## Examples
 
-### Custom Context
+### Basic Event Publishing
 
 ```ruby
+publish = ->(event) {
+  puts "[#{event[:event]}] #{event[:data]}"
+}
+
 context = RobotLab::Streaming::Context.new(
-  callback: ->(event) {
-    case event.type
-    when :text_delta
-      @output << event.text
-    when :complete
-      process_output(@output)
-    end
-  }
+  run_id: SecureRandom.uuid,
+  message_id: SecureRandom.uuid,
+  scope: "robot",
+  publish: publish
 )
 
-# Pass to robot
-robot.run(state: state, streaming: context)
+context.publish_event(event: "run.started", data: { robot_name: "assistant" })
+context.publish_event(event: "text.delta", data: { delta: "Hello " })
+context.publish_event(event: "text.delta", data: { delta: "world!" })
+context.publish_event(event: "run.completed", data: {})
 ```
 
-### Accumulating Content
+### Network with Child Contexts
 
 ```ruby
-context = RobotLab::Streaming::Context.new(
-  callback: ->(event) {
-    print event.text if event.type == :text_delta
-  }
+# Network-level context
+network_ctx = RobotLab::Streaming::Context.new(
+  run_id: "net_run_1",
+  message_id: "net_msg_1",
+  scope: "network",
+  publish: ->(e) { stream_to_client(e) }
 )
 
-robot.run(state: state, streaming: context)
+network_ctx.publish_event(event: "run.started", data: {})
+
+# Robot 1 executes
+robot1_ctx = network_ctx.create_child_context("robot1_run_1")
+robot1_ctx.publish_event(event: "step.started", data: { robot: "classifier" })
+robot1_ctx.publish_event(event: "text.delta", data: { delta: "Category: billing" })
+robot1_ctx.publish_event(event: "step.completed", data: { robot: "classifier" })
+
+# Robot 2 executes (sequence numbers continue from robot 1)
+robot2_ctx = network_ctx.create_child_context("robot2_run_1")
+robot2_ctx.publish_event(event: "step.started", data: { robot: "responder" })
+robot2_ctx.publish_event(event: "text.delta", data: { delta: "I can help with that." })
+robot2_ctx.publish_event(event: "step.completed", data: { robot: "responder" })
 
-# Access accumulated content
-puts "Total content: #{context.buffer}"
-puts "Tool calls: #{context.tool_calls.size}"
+network_ctx.publish_event(event: "run.completed", data: {})
 ```
 
-### Network Context
+### Error-Safe Publishing
 
 ```ruby
+# Errors in the publish callback are caught and logged,
+# so streaming failures do not interrupt execution.
 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
-  }
+  run_id: "run_1",
+  message_id: "msg_1",
+  scope: "robot",
+  publish: ->(e) { raise "connection lost" }
 )
 
-network.run(state: state, streaming: context)
+# This does not raise -- the error is logged via RobotLab.config.logger
+chunk = context.publish_event(event: "text.delta", data: { delta: "test" })
+# chunk is still returned with the event data
 ```
 
 ## See Also

data/docs/api/streaming/events.md

@@ -1,237 +1,185 @@
-# Streaming Events
+# Streaming::Events
 
-Event types for real-time response handling.
+Event type constants and classification helpers for the streaming system.
 
-## Class: `RobotLab::Streaming::Event`
+## Module: `RobotLab::Streaming::Events`
+
+Defines all recognized event types as string constants and provides helper methods for classifying events.
 
 ```ruby
-event.type        # => Symbol
-event.text        # => String (for text events)
-event.robot_name  # => String (for robot events)
+RobotLab::Streaming::Events::TEXT_DELTA       # => "text.delta"
+RobotLab::Streaming::Events::RUN_COMPLETED    # => "run.completed"
+RobotLab::Streaming::Events.delta?("text.delta")  # => true
 ```
 
-## Event Types
+## Event Type Constants
 
-### :start
+### Run Lifecycle Events
 
-Streaming has begun.
+| Constant | Value | Description |
+|----------|-------|-------------|
+| `RUN_STARTED` | `"run.started"` | A run has begun |
+| `RUN_COMPLETED` | `"run.completed"` | A run completed successfully |
+| `RUN_FAILED` | `"run.failed"` | A run failed with an error |
+| `RUN_INTERRUPTED` | `"run.interrupted"` | A run was interrupted |
 
-```ruby
-case event.type
-when :start
-  puts "Starting..."
-end
-```
+### Step Events
 
-**Attributes:**
+For durable execution tracking:
 
-| Name | Type | Description |
-|------|------|-------------|
-| `robot_name` | `String`, `nil` | Robot name |
+| Constant | Value | Description |
+|----------|-------|-------------|
+| `STEP_STARTED` | `"step.started"` | A processing step has begun |
+| `STEP_COMPLETED` | `"step.completed"` | A processing step completed |
+| `STEP_FAILED` | `"step.failed"` | A processing step failed |
 
-### :text_delta
+### Part Events
 
-A chunk of text was received.
+For message composition tracking:
 
-```ruby
-case event.type
-when :text_delta
-  print event.text
-end
-```
+| Constant | Value | Description |
+|----------|-------|-------------|
+| `PART_CREATED` | `"part.created"` | A message part was created |
+| `PART_COMPLETED` | `"part.completed"` | A message part completed |
+| `PART_FAILED` | `"part.failed"` | A message part failed |
 
-**Attributes:**
+### Content Delta Events
 
-| Name | Type | Description |
-|------|------|-------------|
-| `text` | `String` | Text content |
-| `robot_name` | `String`, `nil` | Source robot |
+Token-level streaming events:
 
-### :tool_call
+| Constant | Value | Description |
+|----------|-------|-------------|
+| `TEXT_DELTA` | `"text.delta"` | A chunk of text content was generated |
+| `TOOL_CALL_ARGUMENTS_DELTA` | `"tool_call.arguments.delta"` | A chunk of tool call arguments |
+| `TOOL_CALL_OUTPUT_DELTA` | `"tool_call.output.delta"` | A chunk of tool call output |
+| `REASONING_DELTA` | `"reasoning.delta"` | A chunk of reasoning/thinking content |
+| `DATA_DELTA` | `"data.delta"` | A chunk of structured data |
 
-A tool is being invoked.
+### Human-in-the-Loop Events
 
-```ruby
-case event.type
-when :tool_call
-  puts "Calling #{event.name} with #{event.input}"
-end
-```
+| Constant | Value | Description |
+|----------|-------|-------------|
+| `HITL_REQUESTED` | `"hitl.requested"` | Human input has been requested |
+| `HITL_RESOLVED` | `"hitl.resolved"` | Human input has been provided |
 
-**Attributes:**
+### Metadata Events
 
-| Name | Type | Description |
-|------|------|-------------|
-| `id` | `String` | Tool call ID |
-| `name` | `String` | Tool name |
-| `input` | `Hash` | Tool parameters |
-| `robot_name` | `String`, `nil` | Source robot |
+| Constant | Value | Description |
+|----------|-------|-------------|
+| `USAGE_UPDATED` | `"usage.updated"` | Token usage statistics updated |
+| `METADATA_UPDATED` | `"metadata.updated"` | Run metadata updated |
 
-### :tool_result
+### Terminal Event
 
-A tool has returned a result.
+| Constant | Value | Description |
+|----------|-------|-------------|
+| `STREAM_ENDED` | `"stream.ended"` | The stream has ended; no more events |
 
-```ruby
-case event.type
-when :tool_result
-  puts "#{event.name} returned: #{event.result}"
-end
-```
+## Event Collections
 
-**Attributes:**
+### ALL_EVENTS
 
-| Name | Type | Description |
-|------|------|-------------|
-| `id` | `String` | Tool call ID |
-| `name` | `String` | Tool name |
-| `result` | `Object` | Tool result |
-| `robot_name` | `String`, `nil` | Source robot |
-
-### :robot_start
+```ruby
+RobotLab::Streaming::Events::ALL_EVENTS
+# => Array of all event type strings (frozen)
+```
 
-A robot has started executing (network only).
+### LIFECYCLE_EVENTS
 
 ```ruby
-case event.type
-when :robot_start
-  puts "Robot #{event.robot_name} starting"
-end
+RobotLab::Streaming::Events::LIFECYCLE_EVENTS
+# => ["run.started", "run.completed", "run.failed", "run.interrupted"]
 ```
 
-**Attributes:**
+### DELTA_EVENTS
 
-| Name | Type | Description |
-|------|------|-------------|
-| `robot_name` | `String` | Robot name |
+```ruby
+RobotLab::Streaming::Events::DELTA_EVENTS
+# => ["text.delta", "tool_call.arguments.delta", "tool_call.output.delta",
+#     "reasoning.delta", "data.delta"]
+```
 
-### :robot_complete
+## Classification Methods
 
-A robot has finished executing (network only).
+### Events.lifecycle?
 
 ```ruby
-case event.type
-when :robot_complete
-  puts "Robot #{event.robot_name} finished"
-end
+RobotLab::Streaming::Events.lifecycle?("run.started")   # => true
+RobotLab::Streaming::Events.lifecycle?("text.delta")     # => false
 ```
 
-**Attributes:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `robot_name` | `String` | Robot name |
-| `result` | `RobotResult` | Execution result |
-
-### :complete
+Returns `true` if the event is a run lifecycle event.
 
-All streaming has finished.
+### Events.delta?
 
 ```ruby
-case event.type
-when :complete
-  puts "All done!"
-end
+RobotLab::Streaming::Events.delta?("text.delta")         # => true
+RobotLab::Streaming::Events.delta?("run.completed")      # => false
 ```
 
-### :error
+Returns `true` if the event is a content delta (token streaming) event.
 
-An error occurred.
+### Events.valid?
 
 ```ruby
-case event.type
-when :error
-  puts "Error: #{event.error.message}"
-end
+RobotLab::Streaming::Events.valid?("text.delta")         # => true
+RobotLab::Streaming::Events.valid?("unknown.event")      # => false
 ```
 
-**Attributes:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `error` | `Exception` | The error |
-| `robot_name` | `String`, `nil` | Source robot |
+Returns `true` if the event is a recognized event type.
 
 ## 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
+### Filtering Events by Category
 
 ```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}"
+publish = ->(event) {
+  event_type = event[:event]
+
+  if RobotLab::Streaming::Events.delta?(event_type)
+    # Handle streaming content
+    print event[:data][:delta]
+  elsif RobotLab::Streaming::Events.lifecycle?(event_type)
+    # Handle lifecycle transitions
+    puts "\n[#{event_type}] run_id=#{event[:data][:run_id]}"
   end
-end
+}
 ```
 
-### Filtering Events
+### Using Constants for Event Matching
 
 ```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)
+include RobotLab::Streaming::Events
+
+publish = ->(event) {
+  case event[:event]
+  when TEXT_DELTA
+    print event[:data][:delta]
+  when TOOL_CALL_ARGUMENTS_DELTA
+    buffer_tool_args(event[:data])
+  when RUN_COMPLETED
+    puts "\nRun complete"
+  when RUN_FAILED
+    puts "\nRun failed: #{event[:data][:error]}"
+  when STREAM_ENDED
+    cleanup
   end
-end
+}
 ```
 
-### Async Processing
+### Validating Custom Events
 
 ```ruby
-queue = Queue.new
-
-Thread.new do
-  loop do
-    event = queue.pop
-    break if event == :done
-    process_event(event)
+def emit(event_type, data)
+  unless RobotLab::Streaming::Events.valid?(event_type)
+    raise ArgumentError, "Unknown event type: #{event_type}"
   end
-end
 
-robot.run(state: state) do |event|
-  queue << event
-  queue << :done if event.type == :complete
+  context.publish_event(event: event_type, data: data)
 end
 ```
 
 ## See Also
 
 - [Streaming Overview](index.md)
-- [StreamingContext](context.md)
-- [Streaming Guide](../../guides/streaming.md)
+- [Context](context.md)