robot_lab 0.3.0 → 0.5.0

data/docs/api/streaming/events.md

@@ -1,185 +0,0 @@
-# Streaming::Events
-
-Event type constants and classification helpers for the streaming system.
-
-## Module: `RobotLab::Streaming::Events`
-
-Defines all recognized event types as string constants and provides helper methods for classifying events.
-
-```ruby
-RobotLab::Streaming::Events::TEXT_DELTA       # => "text.delta"
-RobotLab::Streaming::Events::RUN_COMPLETED    # => "run.completed"
-RobotLab::Streaming::Events.delta?("text.delta")  # => true
-```
-
-## Event Type Constants
-
-### Run Lifecycle Events
-
-| 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 |
-
-### Step Events
-
-For durable execution tracking:
-
-| 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 |
-
-### Part Events
-
-For message composition tracking:
-
-| 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 |
-
-### Content Delta Events
-
-Token-level streaming events:
-
-| 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 |
-
-### Human-in-the-Loop Events
-
-| Constant | Value | Description |
-|----------|-------|-------------|
-| `HITL_REQUESTED` | `"hitl.requested"` | Human input has been requested |
-| `HITL_RESOLVED` | `"hitl.resolved"` | Human input has been provided |
-
-### Metadata Events
-
-| Constant | Value | Description |
-|----------|-------|-------------|
-| `USAGE_UPDATED` | `"usage.updated"` | Token usage statistics updated |
-| `METADATA_UPDATED` | `"metadata.updated"` | Run metadata updated |
-
-### Terminal Event
-
-| Constant | Value | Description |
-|----------|-------|-------------|
-| `STREAM_ENDED` | `"stream.ended"` | The stream has ended; no more events |
-
-## Event Collections
-
-### ALL_EVENTS
-
-```ruby
-RobotLab::Streaming::Events::ALL_EVENTS
-# => Array of all event type strings (frozen)
-```
-
-### LIFECYCLE_EVENTS
-
-```ruby
-RobotLab::Streaming::Events::LIFECYCLE_EVENTS
-# => ["run.started", "run.completed", "run.failed", "run.interrupted"]
-```
-
-### DELTA_EVENTS
-
-```ruby
-RobotLab::Streaming::Events::DELTA_EVENTS
-# => ["text.delta", "tool_call.arguments.delta", "tool_call.output.delta",
-#     "reasoning.delta", "data.delta"]
-```
-
-## Classification Methods
-
-### Events.lifecycle?
-
-```ruby
-RobotLab::Streaming::Events.lifecycle?("run.started")   # => true
-RobotLab::Streaming::Events.lifecycle?("text.delta")     # => false
-```
-
-Returns `true` if the event is a run lifecycle event.
-
-### Events.delta?
-
-```ruby
-RobotLab::Streaming::Events.delta?("text.delta")         # => true
-RobotLab::Streaming::Events.delta?("run.completed")      # => false
-```
-
-Returns `true` if the event is a content delta (token streaming) event.
-
-### Events.valid?
-
-```ruby
-RobotLab::Streaming::Events.valid?("text.delta")         # => true
-RobotLab::Streaming::Events.valid?("unknown.event")      # => false
-```
-
-Returns `true` if the event is a recognized event type.
-
-## Examples
-
-### Filtering Events by Category
-
-```ruby
-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
-}
-```
-
-### Using Constants for Event Matching
-
-```ruby
-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
-}
-```
-
-### Validating Custom Events
-
-```ruby
-def emit(event_type, data)
-  unless RobotLab::Streaming::Events.valid?(event_type)
-    raise ArgumentError, "Unknown event type: #{event_type}"
-  end
-
-  context.publish_event(event: event_type, data: data)
-end
-```
-
-## See Also
-
-- [Streaming Overview](index.md)
-- [Context](context.md)

data/docs/api/streaming/index.md

@@ -1,156 +0,0 @@
-# Streaming
-
-A standalone event-publishing toolkit. **Not** the live streaming path.
-
-## Status: not wired in
-
-`RobotLab::Streaming::Context`, `Streaming::Events`, and
-`Streaming::SequenceCounter` exist and work, but **nothing in the framework uses
-them**. `grep -rn "Streaming::" lib/` returns zero hits outside
-`lib/robot_lab/streaming/` itself: no robot, network, task, or hook ever
-constructs a `Streaming::Context`, and no framework code publishes any of the
-events listed below. Enabling this module does not make a robot stream.
-
-Treat this as a set of building blocks you may drive yourself — a vocabulary of
-event names plus a sequencing/ID helper — if you are writing your own
-event-broadcast layer (a websocket relay, a SSE endpoint, an audit feed).
-
-### The real streaming API
-
-To actually receive tokens as a robot generates them, use `on_content:` and/or a
-block on `run`:
-
-```ruby
-# Constructor / RunConfig callback — fires on every run
-robot = RobotLab.build(
-  name: "assistant",
-  system_prompt: "You are helpful.",
-  on_content: ->(chunk) { print chunk.content }
-)
-
-# Or a block passed to run
-robot.run("Tell me a story") { |chunk| print chunk.content }
-```
-
-Each callback receives a `RubyLLM::Chunk`. Use `chunk.content` — there is no
-`chunk.text`. If both are supplied, both fire, with the stored `on_content`
-first. `on_content` is read from the robot's own config at construction time; a
-network-level `config:` does not supply it.
-
-The config key `streaming_enabled` has zero consumers in `lib/` and does nothing.
-
-## Overview
-
-The module provides structured event publishing with automatic sequencing,
-timestamping, and ID generation. Event names cover run lifecycle, content deltas
-(token streaming), tool calls, and metadata updates, and contexts can be nested
-so a network-level run and its child robot runs share one monotonic sequence.
-
-```ruby
-publish = ->(event) {
-  case event[:event]
-  when "text.delta"
-    print event[:data][:delta]
-  when "run.completed"
-    puts "\nDone!"
-  end
-}
-
-context = RobotLab::Streaming::Context.new(
-  run_id: SecureRandom.uuid,
-  message_id: SecureRandom.uuid,
-  scope: "robot",
-  publish: publish
-)
-
-context.publish_event(event: "text.delta", data: { delta: "Hello" })
-```
-
-## Components
-
-| Component | Description |
-|-----------|-------------|
-| [Context](context.md) | Manages streaming state, sequencing, and event publishing |
-| [Events](events.md) | Event type constants and classification helpers |
-| `SequenceCounter` | Thread-safe monotonic counter for event ordering. Its only consumer is `Streaming::Context`, which is itself unused by the framework |
-
-## Event Categories
-
-These are the names defined in `Streaming::Events`. They are constants and
-classification helpers only — no framework code emits any of them.
-
-| Category | Events | Description |
-|----------|--------|-------------|
-| Lifecycle | `run.started`, `run.completed`, `run.failed`, `run.interrupted` | Run-level state changes |
-| Steps | `step.started`, `step.completed`, `step.failed` | Durable execution steps |
-| Parts | `part.created`, `part.completed`, `part.failed` | Message composition parts |
-| Deltas | `text.delta`, `tool_call.arguments.delta`, `tool_call.output.delta`, `reasoning.delta`, `data.delta` | Token-level content streaming |
-| HITL | `hitl.requested`, `hitl.resolved` | Human-in-the-loop events |
-| Metadata | `usage.updated`, `metadata.updated` | Token usage and metadata |
-| Terminal | `stream.ended` | End of stream signal |
-
-`DELTA_EVENTS` has five members — `tool_call.output.delta` is easy to miss.
-`ALL_EVENTS` has twenty.
-
-## Event Structure
-
-Each published event is a hash with the following shape:
-
-```ruby
-{
-  event: "text.delta",           # Event type string
-  data: {                        # Event payload (merged with context info)
-    delta: "Hello",              #   Custom data
-    run_id: "run_123",           #   Injected by context
-    message_id: "msg_456",       #   Injected by context
-    scope: "robot"               #   Injected by context
-  },
-  timestamp: 1707900000000,      # Millisecond Unix timestamp
-  sequence_number: 1,            # Monotonically increasing
-  id: "publish-1:text.delta"     # Unique event ID
-}
-```
-
-## Quick Start
-
-### Publishing Events
-
-```ruby
-context = RobotLab::Streaming::Context.new(
-  run_id: "run_123",
-  message_id: "msg_456",
-  scope: "network",
-  publish: ->(event) { broadcast(event) }
-)
-
-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: {})
-```
-
-### Nested Contexts
-
-Contexts can be nested to model a parent run with child runs sharing one
-sequence. Note that no `Network` creates these — you would build the hierarchy
-yourself.
-
-```ruby
-# Parent context for a run you are orchestrating
-network_context = RobotLab::Streaming::Context.new(
-  run_id: "network_run_1",
-  message_id: "msg_1",
-  scope: "network",
-  publish: ->(event) { stream_to_client(event) }
-)
-
-# Child context for each robot (shares the sequence counter)
-robot_context = network_context.create_child_context("robot_run_1")
-robot_context.publish_event(event: "text.delta", data: { delta: "Response" })
-```
-
-## See Also
-
-- [Context](context.md)
-- [Events](events.md)
-- [Robot](../core/robot.md) -- `on_content:`, and the block form of `run`, which is how streaming actually works