robot_lab 0.0.1 → 0.0.6

data/docs/api/messages/tool-call-message.md

@@ -6,20 +6,35 @@ Tool invocation request from the LLM.
 
 ```ruby
 message = ToolCallMessage.new(
-  id: "call_abc123",
-  name: "get_weather",
-  input: { city: "New York", units: "fahrenheit" }
+  role: "assistant",
+  tools: [
+    ToolMessage.new(id: "call_abc123", name: "get_weather", input: { city: "New York" })
+  ]
 )
 ```
 
 ## Constructor
 
 ```ruby
-ToolCallMessage.new(id:, name:, input:)
+ToolCallMessage.new(role:, tools:, stop_reason: nil)
 ```
 
 **Parameters:**
 
+| Name | Type | Description |
+|------|------|-------------|
+| `role` | `String` | Message role (typically "assistant") |
+| `tools` | `Array<ToolMessage>` | Array of tool call objects |
+| `stop_reason` | `String`, `nil` | Stop reason (defaults to "tool") |
+
+## ToolMessage
+
+Each tool call is represented by a standalone `ToolMessage` object:
+
+```ruby
+ToolMessage.new(id:, name:, input:)
+```
+
 | Name | Type | Description |
 |------|------|-------------|
 | `id` | `String` | Unique call identifier |
@@ -28,37 +43,45 @@ ToolCallMessage.new(id:, name:, input:)
 
 ## Attributes
 
-### id
+### tools
 
 ```ruby
-message.id  # => String
+message.tools  # => Array<ToolMessage>
 ```
 
-Unique identifier for this tool call. Used to match with `ToolResultMessage`.
+Array of `ToolMessage` objects representing the tool calls.
 
-### name
+### role
 
 ```ruby
-message.name  # => String
+message.role  # => "assistant"
 ```
 
-Name of the tool being invoked.
+Returns a String. The LLM initiates tool calls, so this is typically `"assistant"`.
 
-### input
+### type
 
 ```ruby
-message.input  # => Hash
+message.type  # => "tool_call"
 ```
 
-Parameters passed to the tool.
+Always returns `"tool_call"`.
 
-### role
+### content
+
+```ruby
+message.content  # => nil
+```
+
+Always `nil` for tool call messages (the tool data is in `tools`).
+
+### stop_reason
 
 ```ruby
-message.role  # => :assistant
+message.stop_reason  # => "tool"
 ```
 
-Always returns `:assistant` (the LLM initiates tool calls).
+Defaults to `"tool"` indicating the conversation stopped for tool execution.
 
 ## Methods
 
@@ -74,12 +97,12 @@ Hash representation.
 
 ```ruby
 {
-  role: :assistant,
-  tool_call: {
-    id: "call_abc123",
-    name: "get_weather",
-    input: { city: "New York", units: "fahrenheit" }
-  }
+  type: "tool_call",
+  role: "assistant",
+  tools: [
+    { type: "tool", id: "call_abc123", name: "get_weather", input: { city: "New York" } }
+  ],
+  stop_reason: "tool"
 }
 ```
 
@@ -91,28 +114,48 @@ message.to_json  # => String
 
 JSON representation.
 
+### Predicates
+
+```ruby
+message.tool_call?  # => true
+message.text?       # => false
+message.assistant?  # => true
+message.tool_stop?  # => true
+```
+
 ## Examples
 
-### Basic Tool Call
+### Single Tool Call
 
 ```ruby
-call = ToolCallMessage.new(
+tool = ToolMessage.new(
   id: "call_1",
   name: "search_orders",
   input: { user_id: "123", status: "pending" }
 )
+
+call = ToolCallMessage.new(role: "assistant", tools: [tool])
+```
+
+### Multiple Tool Calls
+
+```ruby
+tools = [
+  ToolMessage.new(id: "call_1", name: "get_weather", input: { city: "NYC" }),
+  ToolMessage.new(id: "call_2", name: "get_time", input: { timezone: "EST" })
+]
+
+call = ToolCallMessage.new(role: "assistant", tools: tools)
+call.tools.length  # => 2
 ```
 
 ### Processing Tool Calls
 
 ```ruby
-result.output.each do |msg|
-  case msg
-  when ToolCallMessage
-    puts "Tool called: #{msg.name}"
-    puts "Parameters: #{msg.input.inspect}"
-  when ToolResultMessage
-    puts "Result for #{msg.id}: #{msg.result}"
+if message.tool_call?
+  message.tools.each do |tool|
+    puts "Tool called: #{tool.name}"
+    puts "Parameters: #{tool.input.inspect}"
   end
 end
 ```
@@ -121,19 +164,15 @@ end
 
 ```ruby
 # LLM returns a tool call
-tool_call = ToolCallMessage.new(
-  id: "call_weather_1",
-  name: "get_weather",
-  input: { city: "Seattle" }
-)
+tool = ToolMessage.new(id: "call_weather_1", name: "get_weather", input: { city: "Seattle" })
+tool_call = ToolCallMessage.new(role: "assistant", tools: [tool])
 
-# Tool is executed
-result = tool.call(tool_call.input, state: state)
+# Execute the tool and record the result
+result_data = execute_tool(tool.name, tool.input)
 
-# Result is recorded
 tool_result = ToolResultMessage.new(
-  id: tool_call.id,
-  result: result
+  tool: tool,
+  content: { data: result_data }
 )
 ```
 

data/docs/api/messages/tool-result-message.md

@@ -5,53 +5,104 @@ Result from tool execution.
 ## Class: `RobotLab::ToolResultMessage`
 
 ```ruby
+tool = ToolMessage.new(id: "call_abc123", name: "get_weather", input: { city: "NYC" })
+
 message = ToolResultMessage.new(
-  id: "call_abc123",
-  result: { temperature: 72, conditions: "sunny" }
+  tool: tool,
+  content: { data: { temperature: 72, conditions: "sunny" } }
 )
 ```
 
 ## Constructor
 
 ```ruby
-ToolResultMessage.new(id:, result:)
+ToolResultMessage.new(tool:, content:, stop_reason: nil)
 ```
 
 **Parameters:**
 
 | Name | Type | Description |
 |------|------|-------------|
-| `id` | `String` | Matching tool call ID |
-| `result` | `Object` | Tool execution result |
+| `tool` | `ToolMessage` | The tool call that was executed |
+| `content` | `Hash` | Result with `:data` key (success) or `:error` key (failure) |
+| `stop_reason` | `String`, `nil` | Stop reason (defaults to "tool") |
 
 ## Attributes
 
-### id
+### tool
 
 ```ruby
-message.id  # => String
+message.tool  # => ToolMessage
 ```
 
-Identifier matching the corresponding `ToolCallMessage`.
+The `ToolMessage` representing the tool call that produced this result. Provides access to `tool.id`, `tool.name`, and `tool.input`.
 
-### result
+### content
 
 ```ruby
-message.result  # => Object
+message.content  # => Hash
 ```
 
-The result returned by the tool. Can be any serializable object.
+The result content. Contains either a `:data` key (success) or an `:error` key (failure).
 
 ### role
 
 ```ruby
-message.role  # => :tool
+message.role  # => "tool_result"
+```
+
+Always returns `"tool_result"`.
+
+### type
+
+```ruby
+message.type  # => "tool_result"
 ```
 
-Always returns `:tool`.
+Always returns `"tool_result"`.
+
+### stop_reason
+
+```ruby
+message.stop_reason  # => "tool"
+```
+
+Defaults to `"tool"`.
 
 ## Methods
 
+### success?
+
+```ruby
+message.success?  # => Boolean
+```
+
+Returns `true` if the content contains a `:data` key.
+
+### error?
+
+```ruby
+message.error?  # => Boolean
+```
+
+Returns `true` if the content contains an `:error` key.
+
+### data
+
+```ruby
+message.data  # => Object | nil
+```
+
+Returns the result data if successful, `nil` otherwise.
+
+### error
+
+```ruby
+message.error  # => String | nil
+```
+
+Returns the error message if there was an error, `nil` otherwise.
+
 ### to_h
 
 ```ruby
@@ -64,11 +115,11 @@ Hash representation.
 
 ```ruby
 {
-  role: :tool,
-  tool_result: {
-    id: "call_abc123",
-    result: { temperature: 72, conditions: "sunny" }
-  }
+  type: "tool_result",
+  role: "tool_result",
+  tool: { type: "tool", id: "call_abc123", name: "get_weather", input: { city: "NYC" } },
+  content: { data: { temperature: 72, conditions: "sunny" } },
+  stop_reason: "tool"
 }
 ```
 
@@ -80,70 +131,88 @@ message.to_json  # => String
 
 JSON representation.
 
-## Examples
-
-### Basic Result
+### Predicates
 
 ```ruby
-result = ToolResultMessage.new(
-  id: "call_1",
-  result: { success: true, order_id: "ord_123" }
-)
+message.tool_result?  # => true
+message.tool_call?    # => false
+message.text?         # => false
+message.tool_stop?    # => true
 ```
 
-### String Result
+## Examples
+
+### Successful Result
 
 ```ruby
+tool = ToolMessage.new(id: "call_1", name: "search_orders", input: { user_id: "123" })
+
 result = ToolResultMessage.new(
-  id: "call_time",
-  result: "2024-01-15T10:30:00Z"
+  tool: tool,
+  content: { data: { order_id: "ord_123", status: "shipped" } }
 )
+
+result.success?  # => true
+result.data      # => { order_id: "ord_123", status: "shipped" }
 ```
 
-### Array Result
+### Error Result
 
 ```ruby
+tool = ToolMessage.new(id: "call_order", name: "get_order", input: { id: "bad" })
+
 result = ToolResultMessage.new(
-  id: "call_search",
-  result: [
-    { id: 1, name: "Product A" },
-    { id: 2, name: "Product B" }
-  ]
+  tool: tool,
+  content: { error: "Order not found" }
 )
+
+result.error?  # => true
+result.error   # => "Order not found"
+result.data    # => nil
 ```
 
-### Error Result
+### Accessing Tool Information
 
 ```ruby
 result = ToolResultMessage.new(
-  id: "call_order",
-  result: { success: false, error: "Order not found" }
+  tool: ToolMessage.new(id: "call_1", name: "get_weather", input: { city: "Berlin" }),
+  content: { data: { temperature: 15, unit: "celsius" } }
 )
+
+result.tool.name   # => "get_weather"
+result.tool.id     # => "call_1"
+result.tool.input  # => { city: "Berlin" }
+result.data        # => { temperature: 15, unit: "celsius" }
 ```
 
-### Matching with Tool Calls
+### Matching Tool Calls with Results
 
 ```ruby
-# Process all tool interactions
-result.output.each_cons(2) do |a, b|
-  if a.is_a?(ToolCallMessage) && b.is_a?(ToolResultMessage)
-    if a.id == b.id
-      puts "#{a.name}(#{a.input}) => #{b.result}"
-    end
+# Given a ToolCallMessage and its results
+tool_call_msg.tools.each do |tool|
+  # Find the matching result
+  matching_result = results.find { |r| r.tool.id == tool.id }
+
+  if matching_result&.success?
+    puts "#{tool.name}(#{tool.input}) => #{matching_result.data}"
+  elsif matching_result&.error?
+    puts "#{tool.name} failed: #{matching_result.error}"
   end
 end
 ```
 
-### In Result History
+### In Memory History
 
 ```ruby
-# Find all tool results from execution
-tool_results = state.results
-  .flat_map(&:output)
-  .select { |m| m.is_a?(ToolResultMessage) }
+# Find all tool results from memory
+tool_results = memory.messages.select(&:tool_result?)
 
 tool_results.each do |tr|
-  puts "Tool result: #{tr.result}"
+  if tr.success?
+    puts "#{tr.tool.name}: #{tr.data}"
+  else
+    puts "#{tr.tool.name} error: #{tr.error}"
+  end
 end
 ```
 

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)