robot_lab 0.3.0 → 0.5.0

data/docs/api/messages/index.md

@@ -1,126 +0,0 @@
-# Messages
-
-Message types for LLM conversation representation.
-
-## Overview
-
-RobotLab uses a structured message system to represent conversations between users, assistants, and tools.
-
-```ruby
-# User input
-user_msg = UserMessage.new("Hello", session_id: "123")
-
-# Assistant response
-text_msg = TextMessage.new(role: "assistant", content: "Hi there!")
-
-# Tool interaction
-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)
-├── TextMessage         - role + text content
-├── ToolCallMessage     - role + Array<ToolMessage>
-└── ToolResultMessage   - tool + result content
-
-UserMessage             - Standalone PORO (superclass Object)
-ToolMessage             - Standalone PORO (superclass Object)
-```
-
-`UserMessage` and `ToolMessage` are plain objects — their superclass is `Object`,
-not `Message`. They do not respond to `type`, `role`, or any of the predicates
-below.
-
-## Common Interface
-
-All Message subclasses implement:
-
-```ruby
-message.role       # => String ("system", "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
-```
-
-Valid values are fixed by constants on `Message`, and the constructor raises
-`ArgumentError` for anything else:
-
-```ruby
-RobotLab::Message::VALID_TYPES         # => ["text", "tool_call", "tool_result"]
-RobotLab::Message::VALID_ROLES         # => ["system", "user", "assistant", "tool_result"]
-RobotLab::Message::VALID_STOP_REASONS  # => ["tool", "stop"]
-```
-
-### Nil keys and `to_h`
-
-`Message#to_h` — used as-is by `TextMessage` — ends in `.compact`, so any key
-whose value is `nil` is **absent** from the hash, not present with a `nil` value.
-A `TextMessage` built without a `stop_reason` produces a three-key hash. The same
-applies to `UserMessage#to_h`.
-
-`ToolCallMessage`, `ToolResultMessage`, and `ToolMessage` override `to_h` without
-compacting, so their keys are always present.
-
-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 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 Memory
-
-Messages are typically accessed through memory:
-
-```ruby
-memory.messages  # => Array<Message>
-
-# Format for LLM
-memory.format_history  # => Array<Message>
-```
-
-## Deserializing from Hash
-
-`Message.from_hash` reconstructs the correct subclass from a stored hash:
-
-```ruby
-RobotLab::Message.from_hash({ type: "text", role: "user", content: "Hello" })
-# => #<RobotLab::TextMessage ...>
-
-RobotLab::Message.from_hash({ type: "tool_call", role: "assistant", tools: [...] })
-# => #<RobotLab::ToolCallMessage ...>
-```
-
-When the `type` key is absent or `nil` (e.g. records persisted before the field was introduced), `from_hash` defaults to `TextMessage`:
-
-```ruby
-RobotLab::Message.from_hash({ role: "user", content: "legacy row" })
-# => #<RobotLab::TextMessage ...>
-```
-
-String keys are normalised automatically via `transform_keys(&:to_sym)`.
-
-## See Also
-
-- [Memory](../core/memory.md)
-- [Message Flow Architecture](../../architecture/message-flow.md)

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

@@ -1,170 +0,0 @@
-# TextMessage
-
-Text message from system, user, or assistant.
-
-## Class: `RobotLab::TextMessage`
-
-```ruby
-message = TextMessage.new(role: "assistant", content: "Hello! How can I help you today?")
-```
-
-## Constructor
-
-```ruby
-TextMessage.new(role:, content:, stop_reason: nil)
-```
-
-**Parameters:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `role` | `String` | Message role ("system", "user", or "assistant") |
-| `content` | `String` | The text content |
-| `stop_reason` | `String`, `nil` | Stop reason ("stop" or "tool") |
-
-## Attributes
-
-### content
-
-```ruby
-message.content  # => String
-```
-
-The text content.
-
-### role
-
-```ruby
-message.role  # => "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
-
-### to_h
-
-```ruby
-message.to_h  # => Hash
-```
-
-Hash representation. Inherited from `Message#to_h`, which ends in `.compact` — a
-`nil` `stop_reason` is **omitted** rather than serialized as `nil`.
-
-**Returns:**
-
-```ruby
-TextMessage.new(role: "assistant", content: "Hello! How can I help you today?").to_h
-# => { type: "text", role: "assistant", content: "Hello! How can I help you today?" }
-
-TextMessage.new(role: "assistant", content: "Done.", stop_reason: "stop").to_h
-# => { type: "text", role: "assistant", content: "Done.", stop_reason: "stop" }
-```
-
-### to_json
-
-```ruby
-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
-
-### 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(
-  role: "assistant",
-  content: "Your order has shipped!",
-  stop_reason: "stop"
-)
-message.assistant?  # => true
-message.stopped?    # => true
-```
-
-### In Robot Results
-
-`Robot#run` returns a `RobotResult`, **not** a `TextMessage`. `RobotResult` has no
-`text?` and no `content` — calling either raises `NoMethodError`. Read the reply
-with `last_text_content` (aliased as `reply`):
-
-```ruby
-result = robot.run("Tell me a joke")
-
-puts result.last_text_content   # => the assistant's text
-puts result.reply               # => same thing
-result.stopped?                 # => true whenever there are no tool calls
-result.has_tool_calls?          # => whether the final message carried tool calls
-```
-
-!!! note "`RobotResult#stopped?` is not driven by `stop_reason`"
-    A `RobotResult` produced by `Robot#run` always has `stop_reason == nil`
-    (`RubyLLM::Message` does not define the method, so `build_result` falls back
-    to `nil`), and the `TextMessage` it wraps is built without a `stop_reason`
-    too. `stopped?` therefore reduces to `!has_tool_calls?` — it never becomes
-    true because a `stop_reason` of `"stop"` was reported. The
-    `stop_reason: "stop"` form shown above only applies to `TextMessage`
-    instances you construct yourself.
-
-`result.output` is an `Array` holding a single `TextMessage` rebuilt from the
-final response text — it is not the full turn:
-
-```ruby
-msg = result.output.first
-msg.text?      # => true
-msg.content    # => the assistant's text
-```
-
-### Filtering Text Content
-
-```ruby
-# Get only text messages from memory
-text_messages = memory.messages.select(&:text?).map(&:content)
-```
-
-## See Also
-
-- [UserMessage](user-message.md)
-- [ToolCallMessage](tool-call-message.md)
-- [Robot](../core/robot.md)

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

@@ -1,206 +0,0 @@
-# ToolCallMessage
-
-Tool invocation request from the LLM.
-
-## Class: `RobotLab::ToolCallMessage`
-
-```ruby
-message = ToolCallMessage.new(
-  role: "assistant",
-  tools: [
-    ToolMessage.new(id: "call_abc123", name: "get_weather", input: { city: "New York" })
-  ]
-)
-```
-
-## Constructor
-
-```ruby
-ToolCallMessage.new(role:, tools:, stop_reason: nil)
-```
-
-**Parameters:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `role` | `String` | Message role (typically "assistant") |
-| `tools` | `Array<ToolMessage, Hash>` | Tool calls; plain Hashes are normalized via `ToolMessage.from_hash` |
-| `stop_reason` | `String`, `nil` | Stop reason (defaults to "tool") |
-
-Each entry in `tools` may be a `ToolMessage` **or** a Hash. Anything else raises
-`ArgumentError: Invalid tool: must be ToolMessage or Hash`. The `tools` reader
-always returns `ToolMessage` objects.
-
-```ruby
-ToolCallMessage.new(
-  role: "assistant",
-  tools: [{ id: "call_1", name: "get_weather", arguments: { city: "NYC" } }]
-).tools.first.input
-# => { city: "NYC" }
-```
-
-`ToolMessage.from_hash` symbolizes keys and accepts either `input:` or
-`arguments:` for the parameter hash (`input` wins), defaulting to `{}` when
-neither is present. This makes raw provider tool-call payloads usable directly.
-
-## ToolMessage
-
-Each tool call is represented by a standalone `ToolMessage` object. It is a plain
-Ruby object — its superclass is `Object`, **not** `Message` — so it has no
-`type`, `role`, or predicate methods:
-
-```ruby
-ToolMessage.new(id:, name:, input:)
-ToolMessage.from_hash(hash)
-```
-
-| Name | Type | Description |
-|------|------|-------------|
-| `id` | `String` | Unique call identifier |
-| `name` | `String` | Tool name |
-| `input` | `Hash`, `nil` | Tool parameters; `nil` becomes `{}` |
-
-`ToolMessage#to_h` returns `{ type: "tool", id:, name:, input: }`. It is not
-compacted, so every key is always present.
-
-## Attributes
-
-### tools
-
-```ruby
-message.tools  # => Array<ToolMessage>
-```
-
-Array of `ToolMessage` objects representing the tool calls.
-
-### role
-
-```ruby
-message.role  # => "assistant"
-```
-
-Returns a String. The LLM initiates tool calls, so this is typically `"assistant"`.
-
-### type
-
-```ruby
-message.type  # => "tool_call"
-```
-
-Always returns `"tool_call"`.
-
-### content
-
-```ruby
-message.content  # => nil
-```
-
-Always `nil` for tool call messages (the tool data is in `tools`).
-
-### stop_reason
-
-```ruby
-message.stop_reason  # => "tool"
-```
-
-Defaults to `"tool"` indicating the conversation stopped for tool execution.
-
-## Methods
-
-### to_h
-
-```ruby
-message.to_h  # => Hash
-```
-
-Hash representation. `ToolCallMessage` overrides `Message#to_h` and does **not**
-compact, so all four keys are always present (`content` is not included at all).
-
-**Returns:**
-
-```ruby
-{
-  type: "tool_call",
-  role: "assistant",
-  tools: [
-    { type: "tool", id: "call_abc123", name: "get_weather", input: { city: "New York" } }
-  ],
-  stop_reason: "tool"
-}
-```
-
-### to_json
-
-```ruby
-message.to_json  # => String
-```
-
-JSON representation.
-
-### Predicates
-
-```ruby
-message.tool_call?  # => true
-message.text?       # => false
-message.assistant?  # => true
-message.tool_stop?  # => true
-```
-
-## Examples
-
-### Single Tool Call
-
-```ruby
-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
-if message.tool_call?
-  message.tools.each do |tool|
-    puts "Tool called: #{tool.name}"
-    puts "Parameters: #{tool.input.inspect}"
-  end
-end
-```
-
-### In Tool Execution Flow
-
-```ruby
-# LLM returns a tool call
-tool = ToolMessage.new(id: "call_weather_1", name: "get_weather", input: { city: "Seattle" })
-tool_call = ToolCallMessage.new(role: "assistant", tools: [tool])
-
-# Execute the tool and record the result
-result_data = execute_tool(tool.name, tool.input)
-
-tool_result = ToolResultMessage.new(
-  tool: tool,
-  content: { data: result_data }
-)
-```
-
-## See Also
-
-- [ToolResultMessage](tool-result-message.md)
-- [Tool](../core/tool.md)
-- [Using Tools Guide](../../guides/using-tools.md)