robot_lab 0.0.4 → 0.0.7

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

@@ -1,24 +1,26 @@
 # TextMessage
 
-Assistant text response.
+Text message from system, user, or assistant.
 
 ## Class: `RobotLab::TextMessage`
 
 ```ruby
-message = TextMessage.new("Hello! How can I help you today?")
+message = TextMessage.new(role: "assistant", content: "Hello! How can I help you today?")
 ```
 
 ## Constructor
 
 ```ruby
-TextMessage.new(content)
+TextMessage.new(role:, content:, stop_reason: nil)
 ```
 
 **Parameters:**
 
 | Name | Type | Description |
 |------|------|-------------|
-| `content` | `String` | Response text |
+| `role` | `String` | Message role ("system", "user", or "assistant") |
+| `content` | `String` | The text content |
+| `stop_reason` | `String`, `nil` | Stop reason ("stop" or "tool") |
 
 ## Attributes
 
@@ -28,15 +30,31 @@ TextMessage.new(content)
 message.content  # => String
 ```
 
-The response text.
+The text content.
 
 ### role
 
 ```ruby
-message.role  # => :assistant
+message.role  # => "assistant"
 ```
 
-Always returns `:assistant`.
+Returns a String: `"system"`, `"user"`, or `"assistant"`.
+
+### type
+
+```ruby
+message.type  # => "text"
+```
+
+Always returns `"text"`.
+
+### stop_reason
+
+```ruby
+message.stop_reason  # => "stop" or nil
+```
+
+The stop reason, if any.
 
 ## Methods
 
@@ -52,8 +70,10 @@ Hash representation.
 
 ```ruby
 {
-  role: :assistant,
-  content: "Hello! How can I help you today?"
+  type: "text",
+  role: "assistant",
+  content: "Hello! How can I help you today?",
+  stop_reason: "stop"
 }
 ```
 
@@ -65,34 +85,60 @@ message.to_json  # => String
 
 JSON representation.
 
+### Predicates
+
+```ruby
+message.text?       # => true
+message.tool_call?  # => false
+message.assistant?  # => true (if role is "assistant")
+message.user?       # => false
+message.stopped?    # => true (if stop_reason is "stop")
+```
+
 ## Examples
 
-### Basic Response
+### System Message
+
+```ruby
+message = TextMessage.new(role: "system", content: "You are a helpful assistant")
+message.system?  # => true
+```
+
+### User Message
+
+```ruby
+message = TextMessage.new(role: "user", content: "What's the weather?")
+message.user?  # => true
+```
+
+### Assistant Response
 
 ```ruby
-message = TextMessage.new("Your order has shipped!")
+message = TextMessage.new(
+  role: "assistant",
+  content: "Your order has shipped!",
+  stop_reason: "stop"
+)
+message.assistant?  # => true
+message.stopped?    # => true
 ```
 
 ### In Robot Results
 
 ```ruby
-result = robot.run(state: state)
+result = robot.run("Tell me a joke")
 
-# Extract text messages
-result.output.each do |msg|
-  if msg.is_a?(TextMessage)
-    puts msg.content
-  end
+# The result is a TextMessage when the assistant replies with text
+if result.text?
+  puts result.content
 end
 ```
 
 ### Filtering Text Content
 
 ```ruby
-# Get only text responses from results
-text_responses = state.results.flat_map(&:output).select do |msg|
-  msg.is_a?(TextMessage)
-end.map(&:content)
+# Get only text messages from memory
+text_messages = memory.messages.select(&:text?).map(&:content)
 ```
 
 ## See Also

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
 ```