robot_lab 0.3.0 → 0.5.0

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

@@ -1,242 +0,0 @@
-# ToolResultMessage
-
-Result from tool execution.
-
-## Class: `RobotLab::ToolResultMessage`
-
-```ruby
-tool = ToolMessage.new(id: "call_abc123", name: "get_weather", input: { city: "NYC" })
-
-message = ToolResultMessage.new(
-  tool: tool,
-  content: { data: { temperature: 72, conditions: "sunny" } }
-)
-```
-
-## Constructor
-
-```ruby
-ToolResultMessage.new(tool:, content:, stop_reason: nil)
-```
-
-**Parameters:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `tool` | `ToolMessage`, `Hash` | The tool call that was executed; a Hash is normalized via `ToolMessage.from_hash` |
-| `content` | `Hash` | Result with `:data` key (success) or `:error` key (failure) |
-| `stop_reason` | `String`, `nil` | Stop reason (defaults to "tool") |
-
-`tool:` accepts a plain Hash as well as a `ToolMessage`; anything else raises
-`ArgumentError: Invalid tool: must be ToolMessage or Hash`. As with
-`ToolCallMessage`, `from_hash` symbolizes keys and accepts `input:` or
-`arguments:` for the parameter hash.
-
-```ruby
-ToolResultMessage.new(
-  tool: { id: "call_1", name: "get_weather", arguments: { city: "NYC" } },
-  content: { data: { temperature: 72 } }
-).tool.input
-# => { city: "NYC" }
-```
-
-`role` is hard-coded to `"tool_result"` — the value you pass for `tool:` has no
-bearing on it.
-
-## Attributes
-
-### tool
-
-```ruby
-message.tool  # => ToolMessage
-```
-
-The `ToolMessage` representing the tool call that produced this result. Provides access to `tool.id`, `tool.name`, and `tool.input`.
-
-### content
-
-```ruby
-message.content  # => Hash
-```
-
-The result content. Contains either a `:data` key (success) or an `:error` key (failure).
-
-### role
-
-```ruby
-message.role  # => "tool_result"
-```
-
-Always returns `"tool_result"`.
-
-### type
-
-```ruby
-message.type  # => "tool_result"
-```
-
-Always returns `"tool_result"`.
-
-### stop_reason
-
-```ruby
-message.stop_reason  # => "tool"
-```
-
-Defaults to `"tool"`.
-
-## Methods
-
-### success?
-
-```ruby
-message.success?  # => Boolean
-```
-
-Returns `true` if `content` is a Hash containing the **symbol** key `:data`.
-`content` is stored verbatim — it is not symbolized — so a result built with
-`content: { "data" => ... }` reports `success? == false` and `data == nil`.
-
-### error?
-
-```ruby
-message.error?  # => Boolean
-```
-
-Returns `true` if `content` is a Hash containing the **symbol** key `:error`.
-
-### 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
-message.to_h  # => Hash
-```
-
-Hash representation. `ToolResultMessage` overrides `Message#to_h` and does
-**not** compact, so all five keys are always present.
-
-**Returns:**
-
-```ruby
-{
-  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"
-}
-```
-
-### to_json
-
-```ruby
-message.to_json  # => String
-```
-
-JSON representation.
-
-### Predicates
-
-```ruby
-message.tool_result?  # => true
-message.tool_call?    # => false
-message.text?         # => false
-message.tool_stop?    # => true
-```
-
-## Examples
-
-### Successful Result
-
-```ruby
-tool = ToolMessage.new(id: "call_1", name: "search_orders", input: { user_id: "123" })
-
-result = ToolResultMessage.new(
-  tool: tool,
-  content: { data: { order_id: "ord_123", status: "shipped" } }
-)
-
-result.success?  # => true
-result.data      # => { order_id: "ord_123", status: "shipped" }
-```
-
-### Error Result
-
-```ruby
-tool = ToolMessage.new(id: "call_order", name: "get_order", input: { id: "bad" })
-
-result = ToolResultMessage.new(
-  tool: tool,
-  content: { error: "Order not found" }
-)
-
-result.error?  # => true
-result.error   # => "Order not found"
-result.data    # => nil
-```
-
-### Accessing Tool Information
-
-```ruby
-result = ToolResultMessage.new(
-  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 Tool Calls with Results
-
-```ruby
-# 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 Memory History
-
-```ruby
-# Find all tool results from memory
-tool_results = memory.messages.select(&:tool_result?)
-
-tool_results.each do |tr|
-  if tr.success?
-    puts "#{tr.tool.name}: #{tr.data}"
-  else
-    puts "#{tr.tool.name} error: #{tr.error}"
-  end
-end
-```
-
-## See Also
-
-- [ToolCallMessage](tool-call-message.md)
-- [Tool](../core/tool.md)
-- [Using Tools Guide](../../guides/using-tools.md)

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

@@ -1,232 +0,0 @@
-# UserMessage
-
-User input with conversation metadata.
-
-## Class: `RobotLab::UserMessage`
-
-```ruby
-message = UserMessage.new(
-  "What's my order status?",
-  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, session_id: nil, system_prompt: nil, metadata: nil, id: nil)
-```
-
-**Parameters:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `content` | `String` | Message text |
-| `session_id` | `String`, `nil` | Conversation session ID |
-| `system_prompt` | `String`, `nil` | Override system prompt |
-| `metadata` | `Hash`, `nil` | Additional metadata |
-| `id` | `String`, `nil` | Unique message ID (defaults to UUID) |
-
-## Attributes
-
-### content
-
-```ruby
-message.content  # => String
-```
-
-The message text.
-
-### session_id
-
-```ruby
-message.session_id  # => String | nil
-```
-
-Conversation session identifier for history persistence.
-
-### system_prompt
-
-```ruby
-message.system_prompt  # => String | nil
-```
-
-Optional system prompt override for this message.
-
-### metadata
-
-```ruby
-message.metadata  # => Hash
-```
-
-Arbitrary metadata (source, timestamp, user info, etc.).
-
-### id
-
-```ruby
-message.id  # => String (UUID)
-```
-
-Unique message identifier.
-
-### created_at
-
-```ruby
-message.created_at  # => Time
-```
-
-Message creation timestamp.
-
-## Methods
-
-### to_h
-
-```ruby
-message.to_h  # => Hash
-```
-
-Hash representation. The hash ends in `.compact`, so keys whose value is `nil`
-are **omitted** — a message built without `session_id:` or `system_prompt:` has
-no such keys at all. `metadata` always survives because it defaults to `{}`.
-
-`created_at` is serialized with `Time#iso8601`, which carries the **local** UTC
-offset. It is not normalized to `Z`/UTC.
-
-**Returns:**
-
-```ruby
-UserMessage.new(
-  "What's my order status?",
-  session_id: "session_123",
-  system_prompt: "Be concise",
-  metadata: { source: "web" }
-).to_h
-# => {
-#      content: "What's my order status?",
-#      session_id: "session_123",
-#      system_prompt: "Be concise",
-#      metadata: { source: "web" },
-#      id: "uuid-here",
-#      created_at: "2026-07-31T13:04:42-05:00"
-#    }
-
-UserMessage.new("hi").to_h
-# => {
-#      content: "hi",
-#      metadata: {},
-#      id: "uuid-here",
-#      created_at: "2026-07-31T13:04:42-05:00"
-#    }
-```
-
-### to_json
-
-```ruby
-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
-```
-
-Normalizes any input into a `UserMessage`:
-
-| Input | Result |
-|-------|--------|
-| `UserMessage` | Returned unchanged (same object) |
-| `String` | `new(input)` |
-| `Hash` | Keys symbolized, then `new(content, session_id:, system_prompt:, metadata:, id:)` |
-| `TextMessage` | `new(input.content)` — role and stop reason are dropped |
-| anything else | `new(input.to_s)` |
-
-There is no "unsupported input" branch: `from` never raises for an unrecognized
-type, it falls through to `to_s`.
-
-## Examples
-
-### Basic Message
-
-```ruby
-message = UserMessage.new("Hello!")
-```
-
-### With Session ID
-
-```ruby
-message = UserMessage.new(
-  "Continue our conversation",
-  session_id: "session_abc123"
-)
-```
-
-### With System Prompt Override
-
-```ruby
-message = UserMessage.new(
-  "Translate this",
-  system_prompt: "You are a translator. Respond in Spanish."
-)
-```
-
-### With Metadata
-
-```ruby
-message = UserMessage.new(
-  "Help with my account",
-  metadata: {
-    source: "mobile_app",
-    user_id: "user_123",
-    session_id: "sess_456",
-    locale: "en-US"
-  }
-)
-```
-
-### Creating from Various Inputs
-
-```ruby
-# From a string
-msg = UserMessage.from("Hello!")
-
-# From a hash
-msg = UserMessage.from(content: "Hello!", session_id: "123")
-
-# From an existing UserMessage (returns as-is)
-msg = UserMessage.from(existing_message)
-
-# From a TextMessage (only the content is carried over)
-msg = UserMessage.from(TextMessage.new(role: "user", content: "Hello!"))
-msg.content  # => "Hello!"
-
-# Anything else falls back to to_s
-UserMessage.from(42).content  # => "42"
-```
-
-## See Also
-
-- [Memory](../core/memory.md)
-- [TextMessage](text-message.md)