robot_lab 0.0.1

data/docs/api/index.md

@@ -0,0 +1,82 @@
+# API Reference
+
+Complete API documentation for RobotLab.
+
+## Core Classes
+
+The fundamental building blocks of RobotLab:
+
+| Class | Description |
+|-------|-------------|
+| [Robot](core/robot.md) | LLM-powered agent with personality and tools |
+| [Network](core/network.md) | Orchestrates multiple robots |
+| [State](core/state.md) | Manages conversation and workflow data |
+| [Tool](core/tool.md) | Custom function robots can call |
+| [Memory](core/memory.md) | Shared key-value store |
+
+## Messages
+
+Message types for LLM communication:
+
+| Class | Description |
+|-------|-------------|
+| [UserMessage](messages/user-message.md) | User input with metadata |
+| [TextMessage](messages/text-message.md) | Assistant text response |
+| [ToolCallMessage](messages/tool-call-message.md) | Tool execution request |
+| [ToolResultMessage](messages/tool-result-message.md) | Tool execution result |
+
+## Adapters
+
+Provider-specific message conversion:
+
+| Class | Description |
+|-------|-------------|
+| [Anthropic](adapters/anthropic.md) | Claude models adapter |
+| [OpenAI](adapters/openai.md) | GPT models adapter |
+| [Gemini](adapters/gemini.md) | Google Gemini adapter |
+
+## MCP (Model Context Protocol)
+
+Connect to external tool servers:
+
+| Class | Description |
+|-------|-------------|
+| [Client](mcp/client.md) | MCP server connection |
+| [Server](mcp/server.md) | Server configuration |
+| [Transports](mcp/transports.md) | Connection transports |
+
+## Streaming
+
+Real-time response streaming:
+
+| Class | Description |
+|-------|-------------|
+| [Context](streaming/context.md) | Streaming context |
+| [Events](streaming/events.md) | Event utilities |
+
+## History
+
+Conversation persistence:
+
+| Class | Description |
+|-------|-------------|
+| [Config](history/config.md) | History configuration |
+| [ThreadManager](history/thread-manager.md) | Thread lifecycle |
+| [ActiveRecordAdapter](history/active-record-adapter.md) | Rails adapter |
+
+## Module Methods
+
+### RobotLab
+
+```ruby
+# Configuration
+RobotLab.configuration
+RobotLab.configure { |config| ... }
+
+# Building
+RobotLab.build { ... }
+RobotLab.create_network { ... }
+RobotLab.create_state(...)
+```
+
+See individual class documentation for detailed method references.

data/docs/api/mcp/client.md

@@ -0,0 +1,221 @@
+# MCP Client
+
+Connects to MCP servers and discovers tools.
+
+## Class: `RobotLab::MCP::Client`
+
+```ruby
+client = RobotLab::MCP::Client.new(
+  name: "filesystem",
+  transport: { type: "stdio", command: "mcp-server-filesystem" }
+)
+
+client.connect
+tools = client.list_tools
+```
+
+## Constructor
+
+```ruby
+Client.new(name:, transport:)
+```
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `name` | `String` | Server identifier |
+| `transport` | `Hash` | Transport configuration |
+
+## Attributes
+
+### name
+
+```ruby
+client.name  # => String
+```
+
+Server identifier.
+
+### transport
+
+```ruby
+client.transport  # => Transport
+```
+
+The underlying transport connection.
+
+### connected?
+
+```ruby
+client.connected?  # => Boolean
+```
+
+Whether the client is connected.
+
+## Methods
+
+### connect
+
+```ruby
+client.connect
+```
+
+Establish connection to the MCP server.
+
+### disconnect
+
+```ruby
+client.disconnect
+```
+
+Close the connection.
+
+### list_tools
+
+```ruby
+client.list_tools  # => Array<Tool>
+```
+
+Discover available tools from the server.
+
+### call_tool
+
+```ruby
+result = client.call_tool(name, params)
+```
+
+Execute a tool on the server.
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `name` | `String` | Tool name |
+| `params` | `Hash` | Tool parameters |
+
+### list_resources
+
+```ruby
+client.list_resources  # => Array<Resource>
+```
+
+List available resources (if supported).
+
+### read_resource
+
+```ruby
+client.read_resource(uri)  # => Resource
+```
+
+Read a resource by URI.
+
+## Transport Configuration
+
+### Stdio
+
+```ruby
+client = Client.new(
+  name: "local",
+  transport: {
+    type: "stdio",
+    command: "npx",
+    args: ["@modelcontextprotocol/server-filesystem", "/path"]
+  }
+)
+```
+
+### WebSocket
+
+```ruby
+client = Client.new(
+  name: "remote",
+  transport: {
+    type: "websocket",
+    url: "wss://mcp.example.com/ws"
+  }
+)
+```
+
+### SSE
+
+```ruby
+client = Client.new(
+  name: "streaming",
+  transport: {
+    type: "sse",
+    url: "https://mcp.example.com/sse"
+  }
+)
+```
+
+### HTTP
+
+```ruby
+client = Client.new(
+  name: "http",
+  transport: {
+    type: "http",
+    url: "https://mcp.example.com/mcp"
+  }
+)
+```
+
+## Examples
+
+### Basic Usage
+
+```ruby
+client = Client.new(
+  name: "github",
+  transport: { type: "stdio", command: "mcp-server-github" }
+)
+
+client.connect
+
+# List available tools
+tools = client.list_tools
+tools.each { |t| puts "#{t.name}: #{t.description}" }
+
+# Call a tool
+result = client.call_tool("search_repositories", { query: "ruby mcp" })
+puts result
+
+client.disconnect
+```
+
+### In Robot
+
+```ruby
+robot = RobotLab.build do
+  name "assistant"
+
+  mcp [
+    { name: "fs", transport: { type: "stdio", command: "mcp-fs" } }
+  ]
+end
+
+# MCP tools are automatically available
+robot.tools.each { |t| puts t.name }
+```
+
+### Error Handling
+
+```ruby
+begin
+  client.connect
+  result = client.call_tool("unknown_tool", {})
+rescue RobotLab::MCP::ConnectionError => e
+  puts "Failed to connect: #{e.message}"
+rescue RobotLab::MCP::ToolError => e
+  puts "Tool error: #{e.message}"
+ensure
+  client.disconnect
+end
+```
+
+## See Also
+
+- [MCP Overview](index.md)
+- [Transports](transports.md)
+- [MCP Server](server.md)

data/docs/api/mcp/index.md

@@ -0,0 +1,111 @@
+# MCP (Model Context Protocol)
+
+Integration with MCP servers for extended tool capabilities.
+
+## Overview
+
+MCP allows robots to connect to external tool servers, extending their capabilities without modifying robot code.
+
+```ruby
+robot = RobotLab.build do
+  name "developer"
+  template "You help with coding tasks."
+
+  mcp [
+    {
+      name: "filesystem",
+      transport: { type: "stdio", command: "npx @modelcontextprotocol/server-filesystem" }
+    }
+  ]
+end
+```
+
+## Components
+
+| Component | Description |
+|-----------|-------------|
+| [Client](client.md) | Connects to MCP servers |
+| [Server](server.md) | Exposes tools via MCP |
+| [Transports](transports.md) | Communication methods |
+
+## Quick Start
+
+### Using MCP Tools
+
+```ruby
+network = RobotLab.create_network do
+  name "with_mcp"
+
+  mcp [
+    { name: "github", transport: { type: "stdio", command: "mcp-server-github" } }
+  ]
+
+  add_robot RobotLab.build {
+    name "assistant"
+    template "You help with GitHub tasks."
+    mcp :inherit  # Use network's MCP servers
+  }
+end
+```
+
+### Creating an MCP Server
+
+```ruby
+server = RobotLab::MCP::Server.new(name: "my_tools")
+
+server.add_tool(
+  name: "get_user",
+  description: "Get user by ID",
+  parameters: { id: { type: "string", required: true } },
+  handler: ->(id:) { User.find(id).to_h }
+)
+
+server.start(transport: :stdio)
+```
+
+## Transport Types
+
+| Type | Use Case |
+|------|----------|
+| `stdio` | Local command execution |
+| `websocket` | Real-time bidirectional |
+| `sse` | Server-sent events |
+| `http` | HTTP request/response |
+
+## Configuration Levels
+
+### Network Level
+
+```ruby
+network = RobotLab.create_network do
+  mcp [
+    { name: "server1", transport: { type: "stdio", command: "..." } }
+  ]
+end
+```
+
+### Robot Level
+
+```ruby
+robot = RobotLab.build do
+  mcp :inherit  # Use network's servers
+  # or
+  mcp :none     # No MCP servers
+  # or
+  mcp [...]     # Specific servers
+end
+```
+
+### Tool Filtering
+
+```ruby
+robot = RobotLab.build do
+  mcp :inherit
+  tools %w[read_file write_file]  # Only allow these tools
+end
+```
+
+## See Also
+
+- [MCP Integration Guide](../../guides/mcp-integration.md)
+- [Tool](../core/tool.md)

data/docs/api/mcp/server.md

@@ -0,0 +1,225 @@
+# MCP Server
+
+Expose tools via Model Context Protocol.
+
+## Class: `RobotLab::MCP::Server`
+
+```ruby
+server = RobotLab::MCP::Server.new(name: "my_tools")
+
+server.add_tool(
+  name: "get_time",
+  description: "Get current time",
+  handler: ->(**_) { Time.now.iso8601 }
+)
+
+server.start(transport: :stdio)
+```
+
+## Constructor
+
+```ruby
+Server.new(name:, version: "1.0.0")
+```
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `name` | `String` | Server name |
+| `version` | `String` | Server version |
+
+## Attributes
+
+### name
+
+```ruby
+server.name  # => String
+```
+
+Server identifier.
+
+### version
+
+```ruby
+server.version  # => String
+```
+
+Server version.
+
+### tools
+
+```ruby
+server.tools  # => Array<Tool>
+```
+
+Registered tools.
+
+## Methods
+
+### add_tool
+
+```ruby
+server.add_tool(
+  name:,
+  description:,
+  parameters: {},
+  handler:
+)
+```
+
+Register a tool with the server.
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `name` | `String` | Tool name |
+| `description` | `String` | Tool description |
+| `parameters` | `Hash` | Parameter schema |
+| `handler` | `Proc` | Execution function |
+
+### remove_tool
+
+```ruby
+server.remove_tool(name)
+```
+
+Unregister a tool.
+
+### start
+
+```ruby
+server.start(transport: :stdio, **options)
+```
+
+Start the server.
+
+**Transport Options:**
+
+| Transport | Options |
+|-----------|---------|
+| `:stdio` | None |
+| `:websocket` | `port:`, `host:` |
+| `:sse` | `port:`, `host:`, `path:` |
+| `:http` | `port:`, `host:`, `path:` |
+
+### stop
+
+```ruby
+server.stop
+```
+
+Stop the server.
+
+## Examples
+
+### Basic Server
+
+```ruby
+server = RobotLab::MCP::Server.new(name: "utilities")
+
+server.add_tool(
+  name: "echo",
+  description: "Echo back the input",
+  parameters: {
+    message: { type: "string", required: true }
+  },
+  handler: ->(message:) { message }
+)
+
+server.start(transport: :stdio)
+```
+
+### Database Tools Server
+
+```ruby
+server = RobotLab::MCP::Server.new(name: "database")
+
+server.add_tool(
+  name: "query_users",
+  description: "Query users by criteria",
+  parameters: {
+    status: { type: "string", enum: ["active", "inactive"] },
+    limit: { type: "integer", default: 10 }
+  },
+  handler: ->(status: nil, limit: 10) {
+    scope = User.all
+    scope = scope.where(status: status) if status
+    scope.limit(limit).map(&:to_h)
+  }
+)
+
+server.add_tool(
+  name: "get_user",
+  description: "Get user by ID",
+  parameters: {
+    id: { type: "string", required: true }
+  },
+  handler: ->(id:) {
+    user = User.find_by(id: id)
+    user ? user.to_h : { error: "Not found" }
+  }
+)
+
+server.start(transport: :websocket, port: 8080)
+```
+
+### From Robot Tools
+
+```ruby
+# Convert existing robot tools to MCP server
+robot = RobotLab.build do
+  name "assistant"
+
+  tool :calculate do
+    description "Perform calculation"
+    parameter :expression, type: :string, required: true
+    handler { |expression:, **_| eval(expression) }
+  end
+end
+
+server = RobotLab::MCP::Server.from_robot(robot)
+server.start(transport: :stdio)
+```
+
+### HTTP Server
+
+```ruby
+server = RobotLab::MCP::Server.new(name: "api_tools")
+
+server.add_tool(
+  name: "fetch_data",
+  description: "Fetch data from API",
+  parameters: {
+    endpoint: { type: "string", required: true }
+  },
+  handler: ->(endpoint:) {
+    response = HTTP.get("https://api.example.com/#{endpoint}")
+    JSON.parse(response.body)
+  }
+)
+
+server.start(transport: :http, port: 3001, path: "/mcp")
+```
+
+### With Resources
+
+```ruby
+server = RobotLab::MCP::Server.new(name: "files")
+
+server.add_resource(
+  uri: "file://config",
+  name: "Configuration",
+  description: "Application configuration",
+  handler: -> { File.read("config.yml") }
+)
+
+server.start(transport: :stdio)
+```
+
+## See Also
+
+- [MCP Overview](index.md)
+- [MCP Client](client.md)
+- [Transports](transports.md)