robot_lab 0.0.4 → 0.0.7

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

@@ -7,16 +7,18 @@ User input with conversation metadata.
 ```ruby
 message = UserMessage.new(
   "What's my order status?",
-  thread_id: "thread_123",
+  session_id: "session_123",
   system_prompt: "Be concise",
   metadata: { source: "web" }
 )
 ```
 
+**Note:** `UserMessage` is a standalone class, not a subclass of `Message`.
+
 ## Constructor
 
 ```ruby
-UserMessage.new(content, thread_id: nil, system_prompt: nil, metadata: {})
+UserMessage.new(content, session_id: nil, system_prompt: nil, metadata: nil, id: nil)
 ```
 
 **Parameters:**
@@ -24,9 +26,10 @@ UserMessage.new(content, thread_id: nil, system_prompt: nil, metadata: {})
 | Name | Type | Description |
 |------|------|-------------|
 | `content` | `String` | Message text |
-| `thread_id` | `String`, `nil` | Conversation thread ID |
+| `session_id` | `String`, `nil` | Conversation session ID |
 | `system_prompt` | `String`, `nil` | Override system prompt |
-| `metadata` | `Hash` | Additional metadata |
+| `metadata` | `Hash`, `nil` | Additional metadata |
+| `id` | `String`, `nil` | Unique message ID (defaults to UUID) |
 
 ## Attributes
 
@@ -38,13 +41,13 @@ message.content  # => String
 
 The message text.
 
-### thread_id
+### session_id
 
 ```ruby
-message.thread_id  # => String | nil
+message.session_id  # => String | nil
 ```
 
-Conversation thread identifier for history persistence.
+Conversation session identifier for history persistence.
 
 ### system_prompt
 
@@ -78,14 +81,6 @@ message.created_at  # => Time
 
 Message creation timestamp.
 
-### role
-
-```ruby
-message.role  # => :user
-```
-
-Always returns `:user`.
-
 ## Methods
 
 ### to_h
@@ -100,10 +95,11 @@ Hash representation.
 
 ```ruby
 {
-  role: :user,
   content: "What's my order status?",
+  session_id: "session_123",
+  system_prompt: "Be concise",
+  metadata: { source: "web" },
   id: "uuid-here",
-  thread_id: "thread_123",
   created_at: "2024-01-15T10:30:00Z"
 }
 ```
@@ -116,6 +112,30 @@ message.to_json  # => String
 
 JSON representation.
 
+### to_message
+
+```ruby
+message.to_message  # => TextMessage
+```
+
+Converts to a `TextMessage` with role `"user"` for use in conversation history.
+
+### to_s
+
+```ruby
+message.to_s  # => String
+```
+
+Returns the content string.
+
+### self.from
+
+```ruby
+UserMessage.from(input)  # => UserMessage
+```
+
+Creates a `UserMessage` from a String, Hash, or existing `UserMessage`.
+
 ## Examples
 
 ### Basic Message
@@ -124,12 +144,12 @@ JSON representation.
 message = UserMessage.new("Hello!")
 ```
 
-### With Thread ID
+### With Session ID
 
 ```ruby
 message = UserMessage.new(
   "Continue our conversation",
-  thread_id: "thread_abc123"
+  session_id: "session_abc123"
 )
 ```
 
@@ -156,16 +176,20 @@ message = UserMessage.new(
 )
 ```
 
-### Creating State
+### Creating from Various Inputs
 
 ```ruby
-message = UserMessage.new("Help", thread_id: "thread_123")
-state = RobotLab.create_state(message: message)
+# From a string
+msg = UserMessage.from("Hello!")
+
+# From a hash
+msg = UserMessage.from(content: "Hello!", session_id: "123")
 
-state.thread_id  # => "thread_123"
+# From an existing UserMessage (returns as-is)
+msg = UserMessage.from(existing_message)
 ```
 
 ## See Also
 
-- [State](../core/state.md)
+- [Memory](../core/memory.md)
 - [TextMessage](text-message.md)

data/docs/architecture/core-concepts.md

@@ -130,22 +130,21 @@ robot = RobotLab.build(
 )
 ```
 
-### RobotLab::Tool Inline
+### RobotLab::Tool.create Factory
 
 For simpler tools that do not need a class:
 
 ```ruby
-tool = RobotLab::Tool.new(
+tool = RobotLab::Tool.create(
   name: "get_time",
-  description: "Get the current time",
-  handler: ->(_input, **_opts) { Time.now.to_s }
-)
+  description: "Get the current time"
+) { |_args| Time.now.to_s }
 ```
 
 With parameter schema:
 
 ```ruby
-tool = RobotLab::Tool.new(
+tool = RobotLab::Tool.create(
   name: "get_weather",
   description: "Get weather for a location",
   parameters: {
@@ -154,11 +153,8 @@ tool = RobotLab::Tool.new(
       location: { type: "string", description: "City name" }
     },
     required: ["location"]
-  },
-  handler: ->(input, **_opts) {
-    WeatherAPI.current(input[:location])
   }
-)
+) { |args| WeatherAPI.current(args[:location]) }
 ```
 
 ### Tool Execution
@@ -167,10 +163,9 @@ When an LLM decides to use a tool:
 
 1. LLM generates a tool call with tool name and arguments
 2. `@chat` (RubyLLM) identifies the tool from its registered tools
-3. For `RubyLLM::Tool`: calls the `execute` method with keyword arguments
-4. For `RobotLab::Tool`: calls the `call` method with input hash and context
-5. Result is sent back to the LLM for continued processing
-6. Loop repeats until the LLM produces a final text response
+3. Calls the `execute` method with keyword arguments
+4. Result is sent back to the LLM for continued processing
+5. Loop repeats until the LLM produces a final text response
 
 ### Error Handling
 
@@ -414,7 +409,7 @@ alice.send_message(to: :bob, content: "Tell me a joke.")
 # Handle incoming messages with auto-ack (1 arg)
 bob.on_message do |message|
   joke = bob.run(message.content.to_s).last_text_content
-  bob.reply(message, joke)
+  bob.send_reply(to: message.from.to_sym, content: joke, in_reply_to: message.key)
 end
 ```
 

data/docs/concepts.md

@@ -167,10 +167,10 @@ robot = RobotLab.build(
 )
 ```
 
-### RobotLab::Tool with Block Handler
+### RobotLab::Tool.create Factory
 
 ```ruby
-tool = RobotLab::Tool.new(
+tool = RobotLab::Tool.create(
   name: "get_weather",
   description: "Get current weather for a location",
   parameters: {
@@ -180,9 +180,7 @@ tool = RobotLab::Tool.new(
     },
     required: ["location"]
   }
-) do |input, **_opts|
-  WeatherService.current(input[:location])
-end
+) { |args| WeatherService.current(args[:location]) }
 ```
 
 ## RobotResult
@@ -374,7 +372,7 @@ alice = RobotLab.build(name: "alice", system_prompt: "You evaluate jokes.", bus:
 # Register handlers
 bob.on_message do |message|
   joke = bob.run(message.content.to_s).last_text_content
-  bob.reply(message, joke)
+  bob.send_reply(to: message.from.to_sym, content: joke, in_reply_to: message.key)
 end
 
 alice.on_message do |message|
@@ -391,7 +389,7 @@ Key features:
 
 - **Typed channels** — only `RobotMessage` objects accepted per channel
 - **Auto-ACK** — 1-arg `on_message` blocks auto-acknowledge; 2-arg blocks give manual control
-- **Reply correlation** — `reply(message, content)` tracks threads via `in_reply_to`
+- **Reply correlation** — `send_reply(to:, content:, in_reply_to:)` tracks threads via `in_reply_to`
 - **Independent of Network** — bus works without a Network pipeline
 
 ### Dynamic Spawning

data/docs/examples/index.md

@@ -190,7 +190,7 @@ class Comedian < RobotLab::Robot
       temp = [TEMP_START + TEMP_STEP * (@attempts - 1), 1.0].min
       with_temperature(temp)
       joke = run(message.content.to_s).last_text_content.strip
-      reply(message, joke)
+      send_reply(to: message.from.to_sym, content: joke, in_reply_to: message.key)
     end
   end
 
@@ -224,7 +224,7 @@ Key patterns demonstrated:
 
 - **Robot subclasses** with templates for prompt management
 - **Auto-ack** via 1-arg `on_message` blocks
-- **`reply(message, content)`** for correlated responses
+- **`send_reply(to:, content:, in_reply_to:)`** for correlated responses
 - **Temperature ramping** (0.2 &rarr; 1.0) for increasing creativity
 - **Convergence loop** that terminates when the critic approves
 

data/docs/getting-started/configuration.md

@@ -292,6 +292,86 @@ defaults:
     anthropic_api_key: <%= Rails.application.credentials.anthropic_api_key %>
 ```
 
+## RunConfig: Shared Operational Defaults
+
+`RunConfig` is a configuration object that lets you express operational defaults for LLM settings, tools, callbacks, and infrastructure. Unlike `RobotLab.config` (which is global and static), RunConfig flows through the hierarchy and can be customized at each level:
+
+```
+RobotLab.config (global) -> Network RunConfig -> Robot RunConfig -> Template front matter -> Task RunConfig -> Runtime
+```
+
+### Creating a RunConfig
+
+```ruby
+# Keyword construction
+config = RobotLab::RunConfig.new(model: "claude-sonnet-4", temperature: 0.7)
+
+# Block DSL
+config = RobotLab::RunConfig.new do |c|
+  c.model "claude-sonnet-4"
+  c.temperature 0.7
+  c.max_tokens 2000
+end
+
+# Chaining
+config = RobotLab::RunConfig.new
+  .model("claude-sonnet-4")
+  .temperature(0.7)
+```
+
+### Applying RunConfig
+
+Pass `config:` to robots and networks. Explicit constructor kwargs always override the RunConfig:
+
+```ruby
+# Shared config for a team of robots
+shared = RobotLab::RunConfig.new(model: "claude-sonnet-4", temperature: 0.5)
+
+# Robot uses shared config
+robot = RobotLab.build(
+  name: "writer",
+  system_prompt: "You are a creative writer.",
+  config: shared,
+  temperature: 0.9  # overrides shared config's 0.5
+)
+
+# Network applies config to all member robots
+network = RobotLab.create_network(name: "pipeline", config: shared) do
+  task :analyzer, analyzer_robot, depends_on: :none
+  task :writer, writer_robot, depends_on: [:analyzer]
+end
+```
+
+### Merging Configs
+
+RunConfig supports merge semantics where the more-specific config's values win:
+
+```ruby
+network_config = RobotLab::RunConfig.new(model: "claude-sonnet-4", temperature: 0.5)
+robot_config   = RobotLab::RunConfig.new(temperature: 0.9)
+effective      = network_config.merge(robot_config)
+effective.model        #=> "claude-sonnet-4" (inherited)
+effective.temperature  #=> 0.9 (overridden)
+```
+
+### Available Fields
+
+| Category | Fields |
+|----------|--------|
+| **LLM** | `model`, `temperature`, `top_p`, `top_k`, `max_tokens`, `presence_penalty`, `frequency_penalty`, `stop` |
+| **Tools** | `mcp`, `tools` |
+| **Callbacks** | `on_tool_call`, `on_tool_result` |
+| **Infrastructure** | `bus`, `enable_cache` |
+
+### RunConfig vs RobotLab.config
+
+| | `RobotLab.config` | `RunConfig` |
+|---|---|---|
+| **Scope** | Global (all robots) | Per-network, per-robot, or per-task |
+| **Source** | YAML files, env vars | Code (constructor, block DSL) |
+| **Mutability** | Loaded once, rarely changed | Created per use case, merged |
+| **Purpose** | API keys, timeouts, defaults | Model, temperature, tools per workflow |
+
 ## Robot-Level Configuration
 
 Individual robots can override the global model and other settings:

data/docs/guides/building-robots.md

@@ -340,17 +340,18 @@ puts result.value.last_text_content
 
 ### With Streaming
 
-Stream responses in real-time by passing a block:
+Stream responses in real-time by registering callbacks before calling `run`:
 
 ```ruby
-robot.run("Tell me a story") do |event|
-  case event[:event]
-  when "text.delta"
-    print event[:data][:content]
-  when "tool_call"
-    puts "\nCalling tool: #{event[:data][:name]}"
-  end
+robot.on_new_message do |message|
+  print message.content if message.content
+end
+
+robot.on_tool_call do |tool_call|
+  puts "\nCalling tool: #{tool_call.name}"
 end
+
+result = robot.run("Tell me a story")
 ```
 
 ## Robot Patterns
@@ -434,7 +435,7 @@ class Comedian < RobotLab::Robot
     super(name: "bob", template: :comedian, bus: bus)
     on_message do |message|
       joke = run(message.content.to_s).last_text_content.strip
-      reply(message, joke)
+      send_reply(to: message.from.to_sym, content: joke, in_reply_to: message.key)
     end
   end
 end

data/docs/guides/creating-networks.md

@@ -122,6 +122,7 @@ end
 | `mcp` | MCP servers for this task (`:none`, `:inherit`, or array) |
 | `tools` | Tools available to this task (`:none`, `:inherit`, or array) |
 | `memory` | Task-specific memory |
+| `config` | Per-task `RunConfig` (merged on top of network's config) |
 | `depends_on` | `:none`, `[:task1]`, or `:optional` |
 
 ## Conditional Routing
@@ -380,6 +381,54 @@ network.memory            # => Memory instance (shared)
 network.to_h              # => Hash representation
 ```
 
+## Configuration Inheritance
+
+Networks accept a `config:` parameter that establishes default LLM settings for all member robots. This is useful when you want consistent behavior across a pipeline without configuring each robot individually.
+
+### Network-Wide Defaults
+
+```ruby
+# All robots in this network use the same model and temperature
+shared = RobotLab::RunConfig.new(model: "claude-sonnet-4", temperature: 0.5)
+
+network = RobotLab.create_network(name: "pipeline", config: shared) do
+  task :analyzer, analyzer_robot, depends_on: :none
+  task :writer, writer_robot, depends_on: [:analyzer]
+  task :reviewer, reviewer_robot, depends_on: [:writer]
+end
+```
+
+### Per-Task Overrides
+
+Individual tasks can override the network's config with their own `config:`:
+
+```ruby
+creative_config = RobotLab::RunConfig.new(temperature: 0.9)
+
+network = RobotLab.create_network(name: "pipeline", config: shared) do
+  task :analyzer, analyzer_robot, depends_on: :none
+  task :writer, writer_robot,
+       config: creative_config,  # writer gets higher temperature
+       depends_on: [:analyzer]
+  task :reviewer, reviewer_robot, depends_on: [:writer]
+end
+```
+
+### Inheritance Chain
+
+The full configuration hierarchy (most-specific wins):
+
+```
+RobotLab.config (global)
+  -> Network config
+    -> Task config
+      -> Robot config (from constructor)
+        -> Template front matter
+          -> Constructor kwargs (model:, temperature:, etc.)
+```
+
+Each layer only overrides values it explicitly sets. Unset values pass through from the parent.
+
 ## Best Practices
 
 ### 1. Keep Robots Focused

data/docs/guides/index.md

@@ -34,10 +34,6 @@ If you're new to RobotLab, start here:
 
     Real-time streaming of LLM responses
 
--   [:octicons-database-24: **Conversation History**](history.md)
-
-    Persist and restore conversation threads
-
 -   [:octicons-cpu-24: **Memory System**](memory.md)
 
     Share data between robots with the memory system
@@ -63,6 +59,5 @@ If you're new to RobotLab, start here:
 | [Using Tools](using-tools.md) | Add custom capabilities | 10 min |
 | [MCP Integration](mcp-integration.md) | External tool servers | 10 min |
 | [Streaming](streaming.md) | Real-time responses | 5 min |
-| [History](history.md) | Conversation persistence | 10 min |
 | [Memory](memory.md) | Shared data store | 5 min |
 | [Rails Integration](rails-integration.md) | Rails application setup | 15 min |