robot_lab 0.0.1

data/docs/api/mcp/transports.md

@@ -0,0 +1,264 @@
+# MCP Transports
+
+Communication methods for MCP connections.
+
+## Overview
+
+Transports handle the low-level communication between MCP clients and servers. RobotLab supports multiple transport types for different deployment scenarios.
+
+## Transport Types
+
+### Stdio
+
+Standard input/output for local process communication.
+
+```ruby
+{
+  type: "stdio",
+  command: "npx",
+  args: ["@modelcontextprotocol/server-filesystem", "/path"],
+  env: { "DEBUG" => "true" }
+}
+```
+
+**Options:**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `command` | `String` | Executable command |
+| `args` | `Array` | Command arguments |
+| `env` | `Hash` | Environment variables |
+| `cwd` | `String` | Working directory |
+
+**Use Cases:**
+
+- Local development
+- CLI tools
+- Subprocess servers
+
+### WebSocket
+
+Bidirectional real-time communication.
+
+```ruby
+{
+  type: "websocket",
+  url: "wss://mcp.example.com/ws",
+  headers: { "Authorization" => "Bearer token" }
+}
+```
+
+**Options:**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `url` | `String` | WebSocket endpoint |
+| `headers` | `Hash` | HTTP headers |
+| `ping_interval` | `Integer` | Keep-alive interval (seconds) |
+
+**Use Cases:**
+
+- Remote servers
+- Real-time applications
+- Long-running connections
+
+### SSE (Server-Sent Events)
+
+Unidirectional server-to-client streaming.
+
+```ruby
+{
+  type: "sse",
+  url: "https://mcp.example.com/sse",
+  headers: { "Authorization" => "Bearer token" }
+}
+```
+
+**Options:**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `url` | `String` | SSE endpoint |
+| `headers` | `Hash` | HTTP headers |
+| `post_url` | `String` | Endpoint for client messages |
+
+**Use Cases:**
+
+- Firewall-friendly connections
+- Browser-based clients
+- Streaming responses
+
+### HTTP
+
+Request/response communication.
+
+```ruby
+{
+  type: "http",
+  url: "https://mcp.example.com/mcp",
+  headers: { "Authorization" => "Bearer token" },
+  timeout: 30
+}
+```
+
+**Options:**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `url` | `String` | HTTP endpoint |
+| `headers` | `Hash` | HTTP headers |
+| `timeout` | `Integer` | Request timeout (seconds) |
+| `retry` | `Integer` | Retry attempts |
+
+**Use Cases:**
+
+- Simple integrations
+- Stateless operations
+- Load-balanced servers
+
+## Examples
+
+### Local Server with Stdio
+
+```ruby
+network = RobotLab.create_network do
+  mcp [
+    {
+      name: "filesystem",
+      transport: {
+        type: "stdio",
+        command: "npx",
+        args: ["@modelcontextprotocol/server-filesystem", "/home/user/docs"]
+      }
+    }
+  ]
+end
+```
+
+### Remote Server with WebSocket
+
+```ruby
+network = RobotLab.create_network do
+  mcp [
+    {
+      name: "remote_tools",
+      transport: {
+        type: "websocket",
+        url: "wss://tools.example.com/mcp",
+        headers: {
+          "Authorization" => "Bearer #{ENV['MCP_TOKEN']}"
+        }
+      }
+    }
+  ]
+end
+```
+
+### Multiple Transports
+
+```ruby
+network = RobotLab.create_network do
+  mcp [
+    # Local filesystem
+    {
+      name: "fs",
+      transport: { type: "stdio", command: "mcp-fs" }
+    },
+    # Remote API
+    {
+      name: "api",
+      transport: {
+        type: "http",
+        url: "https://api.example.com/mcp"
+      }
+    },
+    # Real-time service
+    {
+      name: "realtime",
+      transport: {
+        type: "websocket",
+        url: "wss://realtime.example.com/mcp"
+      }
+    }
+  ]
+end
+```
+
+### Custom Transport
+
+```ruby
+class CustomTransport
+  def initialize(options)
+    @options = options
+  end
+
+  def connect
+    # Establish connection
+  end
+
+  def disconnect
+    # Close connection
+  end
+
+  def send(message)
+    # Send message to server
+  end
+
+  def receive
+    # Receive message from server
+  end
+end
+
+RobotLab::MCP.register_transport(:custom, CustomTransport)
+
+# Use custom transport
+{
+  type: "custom",
+  option1: "value1"
+}
+```
+
+## Connection Lifecycle
+
+```mermaid
+sequenceDiagram
+    participant C as Client
+    participant T as Transport
+    participant S as Server
+
+    C->>T: connect()
+    T->>S: Establish connection
+    S-->>T: Connection established
+    T-->>C: Connected
+
+    C->>T: send(request)
+    T->>S: Forward request
+    S-->>T: Response
+    T-->>C: receive() → response
+
+    C->>T: disconnect()
+    T->>S: Close connection
+```
+
+## Error Handling
+
+```ruby
+begin
+  client.connect
+rescue RobotLab::MCP::ConnectionError => e
+  case e.transport
+  when "stdio"
+    puts "Command failed: #{e.message}"
+  when "websocket"
+    puts "WebSocket error: #{e.message}"
+  when "http"
+    puts "HTTP error: #{e.status} - #{e.message}"
+  end
+end
+```
+
+## See Also
+
+- [MCP Overview](index.md)
+- [MCP Client](client.md)
+- [MCP Server](server.md)

data/docs/api/messages/index.md

@@ -0,0 +1,67 @@
+# 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", thread_id: "123")
+
+# Assistant response
+text_msg = TextMessage.new("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 })
+```
+
+## 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
+```
+
+## Common Interface
+
+All messages implement:
+
+```ruby
+message.role       # => Symbol (:user, :assistant, :tool)
+message.content    # => String or structured data
+message.to_h       # => Hash representation
+message.to_json    # => JSON string
+```
+
+## 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 |
+| [ToolResultMessage](tool-result-message.md) | Tool execution result |
+
+## Usage in State
+
+Messages are typically accessed through state:
+
+```ruby
+state.messages  # => Array<Message>
+
+# Format for LLM
+state.format_history  # => Array<Hash>
+```
+
+## See Also
+
+- [State](../core/state.md)
+- [Message Flow Architecture](../../architecture/message-flow.md)

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

@@ -0,0 +1,102 @@
+# TextMessage
+
+Assistant text response.
+
+## Class: `RobotLab::TextMessage`
+
+```ruby
+message = TextMessage.new("Hello! How can I help you today?")
+```
+
+## Constructor
+
+```ruby
+TextMessage.new(content)
+```
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `content` | `String` | Response text |
+
+## Attributes
+
+### content
+
+```ruby
+message.content  # => String
+```
+
+The response text.
+
+### role
+
+```ruby
+message.role  # => :assistant
+```
+
+Always returns `:assistant`.
+
+## Methods
+
+### to_h
+
+```ruby
+message.to_h  # => Hash
+```
+
+Hash representation.
+
+**Returns:**
+
+```ruby
+{
+  role: :assistant,
+  content: "Hello! How can I help you today?"
+}
+```
+
+### to_json
+
+```ruby
+message.to_json  # => String
+```
+
+JSON representation.
+
+## Examples
+
+### Basic Response
+
+```ruby
+message = TextMessage.new("Your order has shipped!")
+```
+
+### In Robot Results
+
+```ruby
+result = robot.run(state: state)
+
+# Extract text messages
+result.output.each do |msg|
+  if msg.is_a?(TextMessage)
+    puts msg.content
+  end
+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)
+```
+
+## See Also
+
+- [UserMessage](user-message.md)
+- [ToolCallMessage](tool-call-message.md)
+- [Robot](../core/robot.md)

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

@@ -0,0 +1,144 @@
+# ToolCallMessage
+
+Tool invocation request from the LLM.
+
+## Class: `RobotLab::ToolCallMessage`
+
+```ruby
+message = ToolCallMessage.new(
+  id: "call_abc123",
+  name: "get_weather",
+  input: { city: "New York", units: "fahrenheit" }
+)
+```
+
+## Constructor
+
+```ruby
+ToolCallMessage.new(id:, name:, input:)
+```
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `id` | `String` | Unique call identifier |
+| `name` | `String` | Tool name |
+| `input` | `Hash` | Tool parameters |
+
+## Attributes
+
+### id
+
+```ruby
+message.id  # => String
+```
+
+Unique identifier for this tool call. Used to match with `ToolResultMessage`.
+
+### name
+
+```ruby
+message.name  # => String
+```
+
+Name of the tool being invoked.
+
+### input
+
+```ruby
+message.input  # => Hash
+```
+
+Parameters passed to the tool.
+
+### role
+
+```ruby
+message.role  # => :assistant
+```
+
+Always returns `:assistant` (the LLM initiates tool calls).
+
+## Methods
+
+### to_h
+
+```ruby
+message.to_h  # => Hash
+```
+
+Hash representation.
+
+**Returns:**
+
+```ruby
+{
+  role: :assistant,
+  tool_call: {
+    id: "call_abc123",
+    name: "get_weather",
+    input: { city: "New York", units: "fahrenheit" }
+  }
+}
+```
+
+### to_json
+
+```ruby
+message.to_json  # => String
+```
+
+JSON representation.
+
+## Examples
+
+### Basic Tool Call
+
+```ruby
+call = ToolCallMessage.new(
+  id: "call_1",
+  name: "search_orders",
+  input: { user_id: "123", status: "pending" }
+)
+```
+
+### 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}"
+  end
+end
+```
+
+### In Tool Execution Flow
+
+```ruby
+# LLM returns a tool call
+tool_call = ToolCallMessage.new(
+  id: "call_weather_1",
+  name: "get_weather",
+  input: { city: "Seattle" }
+)
+
+# Tool is executed
+result = tool.call(tool_call.input, state: state)
+
+# Result is recorded
+tool_result = ToolResultMessage.new(
+  id: tool_call.id,
+  result: result
+)
+```
+
+## See Also
+
+- [ToolResultMessage](tool-result-message.md)
+- [Tool](../core/tool.md)
+- [Using Tools Guide](../../guides/using-tools.md)

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

@@ -0,0 +1,154 @@
+# ToolResultMessage
+
+Result from tool execution.
+
+## Class: `RobotLab::ToolResultMessage`
+
+```ruby
+message = ToolResultMessage.new(
+  id: "call_abc123",
+  result: { temperature: 72, conditions: "sunny" }
+)
+```
+
+## Constructor
+
+```ruby
+ToolResultMessage.new(id:, result:)
+```
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `id` | `String` | Matching tool call ID |
+| `result` | `Object` | Tool execution result |
+
+## Attributes
+
+### id
+
+```ruby
+message.id  # => String
+```
+
+Identifier matching the corresponding `ToolCallMessage`.
+
+### result
+
+```ruby
+message.result  # => Object
+```
+
+The result returned by the tool. Can be any serializable object.
+
+### role
+
+```ruby
+message.role  # => :tool
+```
+
+Always returns `:tool`.
+
+## Methods
+
+### to_h
+
+```ruby
+message.to_h  # => Hash
+```
+
+Hash representation.
+
+**Returns:**
+
+```ruby
+{
+  role: :tool,
+  tool_result: {
+    id: "call_abc123",
+    result: { temperature: 72, conditions: "sunny" }
+  }
+}
+```
+
+### to_json
+
+```ruby
+message.to_json  # => String
+```
+
+JSON representation.
+
+## Examples
+
+### Basic Result
+
+```ruby
+result = ToolResultMessage.new(
+  id: "call_1",
+  result: { success: true, order_id: "ord_123" }
+)
+```
+
+### String Result
+
+```ruby
+result = ToolResultMessage.new(
+  id: "call_time",
+  result: "2024-01-15T10:30:00Z"
+)
+```
+
+### Array Result
+
+```ruby
+result = ToolResultMessage.new(
+  id: "call_search",
+  result: [
+    { id: 1, name: "Product A" },
+    { id: 2, name: "Product B" }
+  ]
+)
+```
+
+### Error Result
+
+```ruby
+result = ToolResultMessage.new(
+  id: "call_order",
+  result: { success: false, error: "Order not found" }
+)
+```
+
+### Matching with Tool Calls
+
+```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
+  end
+end
+```
+
+### In Result History
+
+```ruby
+# Find all tool results from execution
+tool_results = state.results
+  .flat_map(&:output)
+  .select { |m| m.is_a?(ToolResultMessage) }
+
+tool_results.each do |tr|
+  puts "Tool result: #{tr.result}"
+end
+```
+
+## See Also
+
+- [ToolCallMessage](tool-call-message.md)
+- [Tool](../core/tool.md)
+- [Using Tools Guide](../../guides/using-tools.md)