robot_lab 0.0.4 → 0.0.7

data/docs/api/core/robot.md

@@ -36,7 +36,8 @@ Robot.new(
   max_tokens: nil,
   presence_penalty: nil,
   frequency_penalty: nil,
-  stop: nil
+  stop: nil,
+  config: nil
 )
 ```
 
@@ -58,6 +59,7 @@ Robot.new(
 | `on_tool_result` | `Proc`, `nil` | `nil` | Callback invoked when a tool returns a result |
 | `enable_cache` | `Boolean` | `true` | Whether to enable semantic caching |
 | `bus` | `TypedBus::MessageBus`, `nil` | `nil` | Optional message bus for inter-robot communication |
+| `config` | `RunConfig`, `nil` | `nil` | Shared config merged with explicit kwargs (see [RunConfig](#runconfig)) |
 | `temperature` | `Float`, `nil` | `nil` | Controls randomness (0.0-1.0) |
 | `top_p` | `Float`, `nil` | `nil` | Nucleus sampling threshold |
 | `top_k` | `Integer`, `nil` | `nil` | Top-k sampling |
@@ -66,6 +68,8 @@ Robot.new(
 | `frequency_penalty` | `Float`, `nil` | `nil` | Penalize based on frequency |
 | `stop` | `String`, `Array`, `nil` | `nil` | Stop sequences |
 
+When both `config:` and explicit kwargs (e.g., `temperature:`) are provided, explicit kwargs always win.
+
 ## Factory Method
 
 ```ruby
@@ -97,6 +101,7 @@ If `name` is omitted, it defaults to `"robot"`.
 | `memory` | `Memory` | Inherent memory (used when standalone, not in network) |
 | `bus` | `TypedBus::MessageBus`, `nil` | Message bus instance (nil if not configured) |
 | `outbox` | `Hash` | Sent messages tracked by composite key with status and replies |
+| `config` | `RunConfig` | Effective RunConfig (merged from constructor kwargs and passed-in config) |
 | `mcp_config` | `Symbol`, `Array` | Build-time MCP configuration (raw, unresolved) |
 | `tools_config` | `Symbol`, `Array` | Build-time tools configuration (raw, unresolved) |
 
@@ -279,24 +284,6 @@ Publish a correlated reply to a specific message. The `in_reply_to` composite ke
 
 **Raises:** `BusError` if no bus is configured.
 
-### reply
-
-```ruby
-robot.reply(message, "Here's my response")
-# => RobotMessage
-```
-
-Convenience method that wraps `send_reply`. Extracts the `from` and `key` from the incoming `RobotMessage` automatically.
-
-**Parameters:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `message` | `RobotMessage` | The message being replied to |
-| `content` | `String`, `Hash` | Reply payload |
-
-**Returns:** `RobotMessage`
-
 ### on_message
 
 ```ruby
@@ -315,14 +302,14 @@ Register a custom handler for incoming bus messages. Block arity controls delive
 # Auto-ack mode (1 arg)
 robot.on_message do |message|
   joke = run(message.content.to_s).last_text_content
-  reply(message, joke)
+  send_reply(to: message.from.to_sym, content: joke, in_reply_to: message.key)
 end
 
 # Manual mode (2 args)
 robot.on_message do |delivery, message|
   if message.content.to_s.length > 10
     delivery.ack!
-    reply(message, "Got it!")
+    send_reply(to: message.from.to_sym, content: "Got it!", in_reply_to: message.key)
   else
     delivery.nack!
   end
@@ -459,6 +446,27 @@ Front matter supports two categories of keys:
 | `tools` | `Array<String>` | Tool class names resolved via `Object.const_get` |
 | `mcp` | `Array<Hash>` | MCP server configurations |
 
+## RunConfig
+
+`RunConfig` provides shared operational defaults that flow through the configuration hierarchy. Pass it via the `config:` parameter on `Robot.new` or `RobotLab.build`.
+
+```ruby
+shared = RobotLab::RunConfig.new(model: "claude-sonnet-4", temperature: 0.7)
+
+robot = RobotLab.build(
+  name: "writer",
+  system_prompt: "You write creatively.",
+  config: shared,
+  temperature: 0.9  # explicit kwargs override config
+)
+
+robot.config  #=> RunConfig with model: "claude-sonnet-4", temperature: 0.9, ...
+```
+
+RunConfig fields: `model`, `temperature`, `top_p`, `top_k`, `max_tokens`, `presence_penalty`, `frequency_penalty`, `stop`, `mcp`, `tools`, `on_tool_call`, `on_tool_result`, `bus`, `enable_cache`.
+
+See [Configuration: RunConfig](../../getting-started/configuration.md#runconfig-shared-operational-defaults) for full details.
+
 ## Configuration Hierarchy
 
 Tools and MCP servers use hierarchical resolution: **runtime > robot > network > global config**.
@@ -466,11 +474,15 @@ Tools and MCP servers use hierarchical resolution: **runtime > robot > network >
 ```
 RobotLab.config (global)
   |
-  +-- Network
+  +-- Network (config:)
   |     |
-  |     +-- Robot (build-time mcp:, tools:)
-  |           |
-  |           +-- run() call (runtime mcp:, tools:)
+  |     +-- Task (config:)
+  |     |     |
+  |     |     +-- Robot (config: + build-time mcp:, tools:)
+  |     |           |
+  |     |           +-- Template front matter
+  |     |                 |
+  |     |                 +-- run() call (runtime mcp:, tools:)
 ```
 
 Values at each level:
@@ -572,7 +584,7 @@ end
 
 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.send_message(to: :bob, content: "Tell me a robot joke.")

data/docs/api/core/state.md

@@ -1,54 +1,43 @@
-# State
+# Memory (State Management)
 
-Manages conversation data, results, and memory.
+Memory manages conversation data, results, and runtime state. There is no separate `State` class; `Memory` serves this role.
 
-## Class: `RobotLab::State`
+## Class: `RobotLab::Memory`
 
 ```ruby
-state = RobotLab.create_state(
-  message: "Hello",
+memory = RobotLab.create_memory(
   data: { user_id: "123" }
 )
 ```
 
 ## Attributes
 
-### thread_id
+### session_id
 
 ```ruby
-state.thread_id  # => String | nil
+memory.session_id  # => String | nil
 ```
 
-Conversation thread identifier for persistence.
-
-### memory
-
-```ruby
-state.memory  # => Memory
-```
-
-Shared key-value store.
-
-## Methods
+Conversation session identifier for persistence.
 
 ### data
 
 ```ruby
-state.data  # => StateProxy
+memory.data  # => StateProxy
 ```
 
 Access workflow data as a proxy object.
 
 ```ruby
-state.data[:user_id]          # Hash access
-state.data.user_id            # Method access
-state.data[:status] = "active"
+memory.data[:user_id]          # Hash access
+memory.data.user_id            # Method access
+memory.data[:status] = "active"
 ```
 
 ### results
 
 ```ruby
-state.results  # => Array<RobotResult>
+memory.results  # => Array<RobotResult>
 ```
 
 All robot execution results.
@@ -56,15 +45,17 @@ All robot execution results.
 ### messages
 
 ```ruby
-state.messages  # => Array<Message>
+memory.messages  # => Array<Message>
 ```
 
 Formatted conversation messages for LLM.
 
+## Methods
+
 ### append_result
 
 ```ruby
-state.append_result(robot_result)
+memory.append_result(robot_result)
 ```
 
 Add a robot result to history.
@@ -72,7 +63,7 @@ Add a robot result to history.
 ### set_results
 
 ```ruby
-state.set_results(array_of_results)
+memory.set_results(array_of_results)
 ```
 
 Replace all results.
@@ -80,23 +71,23 @@ Replace all results.
 ### results_from
 
 ```ruby
-state.results_from(5)  # => Array<RobotResult>
+memory.results_from(5)  # => Array<RobotResult>
 ```
 
 Get results starting at index.
 
-### thread_id=
+### session_id=
 
 ```ruby
-state.thread_id = "thread_123"
+memory.session_id = "session_123"
 ```
 
-Set the thread identifier.
+Set the session identifier.
 
 ### format_history
 
 ```ruby
-state.format_history  # => Array<Message>
+memory.format_history  # => Array<Message>
 ```
 
 Format results as conversation history.
@@ -104,7 +95,7 @@ Format results as conversation history.
 ### clone
 
 ```ruby
-new_state = state.clone
+new_memory = memory.clone
 ```
 
 Create a deep copy.
@@ -112,7 +103,7 @@ Create a deep copy.
 ### to_h
 
 ```ruby
-state.to_h  # => Hash
+memory.to_h  # => Hash
 ```
 
 Hash representation.
@@ -120,7 +111,7 @@ Hash representation.
 ### to_json
 
 ```ruby
-state.to_json  # => String
+memory.to_json  # => String
 ```
 
 JSON representation.
@@ -128,7 +119,7 @@ JSON representation.
 ### from_hash (class method)
 
 ```ruby
-state = State.from_hash(hash)
+memory = Memory.from_hash(hash)
 ```
 
 Restore from hash.
@@ -138,7 +129,7 @@ Restore from hash.
 The `data` attribute is a `StateProxy`:
 
 ```ruby
-proxy = state.data
+proxy = memory.data
 
 # Hash-style access
 proxy[:key]
@@ -160,19 +151,18 @@ proxy.empty?
 proxy.size
 ```
 
-## Creating State
+## Creating Memory
 
 ### Basic
 
 ```ruby
-state = RobotLab.create_state(message: "Hello")
+memory = RobotLab.create_memory
 ```
 
 ### With Data
 
 ```ruby
-state = RobotLab.create_state(
-  message: "Process order",
+memory = RobotLab.create_memory(
   data: {
     user_id: "user_123",
     order_id: "ord_456"
@@ -180,25 +170,18 @@ state = RobotLab.create_state(
 )
 ```
 
-### With Thread ID
+### With Session ID
 
 ```ruby
-# Via UserMessage
-message = UserMessage.new("Continue", thread_id: "thread_123")
-state = RobotLab.create_state(message: message)
-
-# Direct assignment
-state = RobotLab.create_state(message: "Continue")
-state.thread_id = "thread_123"
+memory = RobotLab.create_memory
+memory.session_id = "session_123"
 ```
 
 ### With Existing Results
 
 ```ruby
-state = RobotLab.create_state(
-  message: "Follow up",
-  results: previous_results
-)
+memory = RobotLab.create_memory
+memory.set_results(previous_results)
 ```
 
 ## UserMessage
@@ -208,13 +191,13 @@ Enhanced message with metadata:
 ```ruby
 message = UserMessage.new(
   "What's my order status?",
-  thread_id: "thread_123",
+  session_id: "session_123",
   system_prompt: "Respond in Spanish",
   metadata: { source: "web" }
 )
 
 message.content       # => "What's my order status?"
-message.thread_id     # => "thread_123"
+message.session_id    # => "session_123"
 message.system_prompt # => "Respond in Spanish"
 message.metadata      # => { source: "web" }
 message.id            # => UUID
@@ -226,48 +209,47 @@ message.created_at    # => Time
 ### Accessing Data
 
 ```ruby
-state = RobotLab.create_state(
-  message: "Help",
+memory = RobotLab.create_memory(
   data: { user: { name: "Alice", plan: "pro" } }
 )
 
-state.data[:user][:name]  # => "Alice"
-state.data.to_h           # => { user: { name: "Alice", plan: "pro" } }
+memory.data[:user][:name]  # => "Alice"
+memory.data.to_h           # => { user: { name: "Alice", plan: "pro" } }
 ```
 
 ### Working with Results
 
 ```ruby
 # After running network
-state.results.size           # Number of results
-state.results.last           # Most recent
-state.results.map(&:robot_name)  # ["classifier", "support"]
+memory.results.size           # Number of results
+memory.results.last           # Most recent
+memory.results.map(&:robot_name)  # ["classifier", "support"]
 ```
 
-### Using Memory
+### Using Reactive Memory
 
 ```ruby
-state.memory.remember("intent", "billing")
-intent = state.memory.recall("intent")
+memory.set(:intent, "billing")
+intent = memory.get(:intent)
 
-scoped = state.memory.scoped("user:123")
-scoped.remember("preference", "dark_mode")
+memory.subscribe(:status) do |change|
+  puts "Status changed to #{change.value} by #{change.writer}"
+end
 ```
 
 ### Serialization
 
 ```ruby
-# Save state
-json = state.to_json
-File.write("state.json", json)
+# Save memory
+json = memory.to_json
+File.write("memory.json", json)
 
-# Restore state
-data = JSON.parse(File.read("state.json"))
-state = State.from_hash(data)
+# Restore memory
+data = JSON.parse(File.read("memory.json"))
+memory = Memory.from_hash(data)
 ```
 
 ## See Also
 
 - [State Management Architecture](../../architecture/state-management.md)
 - [Memory](memory.md)
-- [History Guide](../../guides/history.md)

data/docs/api/index.md

@@ -10,9 +10,8 @@ The fundamental building blocks of RobotLab:
 |-------|-------------|
 | [Robot](core/robot.md) | LLM-powered agent with personality and tools |
 | [Network](core/network.md) | Orchestrates multiple robots |
-| [State](core/state.md) | Manages conversation and workflow data |
+| [Memory](core/memory.md) | Reactive key-value store for sharing data |
 | [Tool](core/tool.md) | Custom function robots can call |
-| [Memory](core/memory.md) | Shared key-value store |
 
 ## Messages
 
@@ -21,20 +20,10 @@ Message types for LLM communication:
 | Class | Description |
 |-------|-------------|
 | [UserMessage](messages/user-message.md) | User input with metadata |
-| [TextMessage](messages/text-message.md) | Assistant text response |
+| [TextMessage](messages/text-message.md) | Text message with role |
 | [ToolCallMessage](messages/tool-call-message.md) | Tool execution request |
 | [ToolResultMessage](messages/tool-result-message.md) | Tool execution result |
 
-## Adapters
-
-Provider-specific message conversion:
-
-| Class | Description |
-|-------|-------------|
-| [Anthropic](adapters/anthropic.md) | Claude models adapter |
-| [OpenAI](adapters/openai.md) | GPT models adapter |
-| [Gemini](adapters/gemini.md) | Google Gemini adapter |
-
 ## MCP (Model Context Protocol)
 
 Connect to external tool servers:
@@ -54,29 +43,19 @@ Real-time response streaming:
 | [Context](streaming/context.md) | Streaming context |
 | [Events](streaming/events.md) | Event utilities |
 
-## History
-
-Conversation persistence:
-
-| Class | Description |
-|-------|-------------|
-| [Config](history/config.md) | History configuration |
-| [ThreadManager](history/thread-manager.md) | Thread lifecycle |
-| [ActiveRecordAdapter](history/active-record-adapter.md) | Rails adapter |
-
 ## Module Methods
 
 ### RobotLab
 
 ```ruby
 # Configuration
-RobotLab.configuration
-RobotLab.configure { |config| ... }
+RobotLab.config              # => Config instance
+RobotLab.reload_config!      # => reload from all sources
 
 # Building
-RobotLab.build { ... }
-RobotLab.create_network { ... }
-RobotLab.create_state(...)
+RobotLab.build(name:, template:, system_prompt:, context:, **options)
+RobotLab.create_network(name:, concurrency:) { ... }
+RobotLab.create_memory(data:, enable_cache:, **options)
 ```
 
 See individual class documentation for detailed method references.

data/docs/api/messages/index.md

@@ -8,60 +8,75 @@ RobotLab uses a structured message system to represent conversations between use
 
 ```ruby
 # User input
-user_msg = UserMessage.new("Hello", thread_id: "123")
+user_msg = UserMessage.new("Hello", session_id: "123")
 
 # Assistant response
-text_msg = TextMessage.new("Hi there!")
+text_msg = TextMessage.new(role: "assistant", content: "Hi there!")
 
 # Tool interaction
-tool_call = ToolCallMessage.new(id: "call_1", name: "get_weather", input: { city: "NYC" })
-tool_result = ToolResultMessage.new(id: "call_1", result: { temp: 72 })
+tool = ToolMessage.new(id: "call_1", name: "get_weather", input: { city: "NYC" })
+tool_call = ToolCallMessage.new(role: "assistant", tools: [tool])
+tool_result = ToolResultMessage.new(tool: tool, content: { data: { temp: 72 } })
 ```
 
 ## Message Hierarchy
 
 ```
 Message (base)
-├── UserMessage      - User input with metadata
-├── TextMessage      - Assistant text response
-├── ToolMessage      - Tool-related messages
-│   ├── ToolCallMessage   - Tool invocation
-│   └── ToolResultMessage - Tool result
-└── SystemMessage    - System prompts
+├── TextMessage         - role + text content
+├── ToolCallMessage     - role + Array<ToolMessage>
+└── ToolResultMessage   - tool + result content
+
+UserMessage             - Standalone (not a Message subclass)
+ToolMessage             - Standalone (not a Message subclass)
 ```
 
 ## Common Interface
 
-All messages implement:
+All Message subclasses implement:
 
 ```ruby
-message.role       # => Symbol (:user, :assistant, :tool)
+message.role       # => String ("user", "assistant", "tool_result")
 message.content    # => String or structured data
+message.type       # => String ("text", "tool_call", "tool_result")
 message.to_h       # => Hash representation
 message.to_json    # => JSON string
 ```
 
+Type and role predicates:
+
+```ruby
+message.text?       # => true if type is "text"
+message.tool_call?  # => true if type is "tool_call"
+message.tool_result? # => true if type is "tool_result"
+message.system?     # => true if role is "system"
+message.user?       # => true if role is "user"
+message.assistant?  # => true if role is "assistant"
+message.stopped?    # => true if stop_reason is "stop"
+message.tool_stop?  # => true if stop_reason is "tool"
+```
+
 ## Classes
 
 | Class | Description |
 |-------|-------------|
-| [UserMessage](user-message.md) | User input with thread and metadata |
-| [TextMessage](text-message.md) | Assistant text response |
-| [ToolCallMessage](tool-call-message.md) | Tool invocation request |
+| [UserMessage](user-message.md) | User input with session and metadata |
+| [TextMessage](text-message.md) | Text message with role (system, user, or assistant) |
+| [ToolCallMessage](tool-call-message.md) | Tool invocation request containing ToolMessage objects |
 | [ToolResultMessage](tool-result-message.md) | Tool execution result |
 
-## Usage in State
+## Usage in Memory
 
-Messages are typically accessed through state:
+Messages are typically accessed through memory:
 
 ```ruby
-state.messages  # => Array<Message>
+memory.messages  # => Array<Message>
 
 # Format for LLM
-state.format_history  # => Array<Hash>
+memory.format_history  # => Array<Message>
 ```
 
 ## See Also
 
-- [State](../core/state.md)
+- [Memory](../core/memory.md)
 - [Message Flow Architecture](../../architecture/message-flow.md)