robot_lab 0.0.1

data/docs/architecture/core-concepts.md

@@ -0,0 +1,243 @@
+# Core Concepts
+
+This page provides an in-depth look at RobotLab's fundamental building blocks.
+
+## Robot
+
+A Robot is the primary unit of computation in RobotLab. It wraps an LLM with:
+
+- A unique identity (name, description)
+- A personality (system prompt/template)
+- Capabilities (tools, MCP connections)
+- A specific model configuration
+
+### Robot Anatomy
+
+```ruby
+robot = RobotLab.build do
+  name "support_agent"                    # Unique identifier
+  description "Handles support requests"  # Used for routing hints
+  model "claude-sonnet-4"                 # LLM model
+
+  # System prompt - defines personality
+  template <<~PROMPT
+    You are a friendly customer support agent for Acme Corp.
+    Always be polite and helpful. If you don't know something,
+    say so honestly.
+  PROMPT
+
+  # Tools - extend capabilities
+  tool :lookup_account do
+    description "Look up customer account"
+    parameter :email, type: :string, required: true
+    handler { |email:, **_| Account.find_by_email(email)&.to_h }
+  end
+
+  # MCP - external tool servers
+  mcp :inherit  # Use network's MCP servers
+end
+```
+
+### Robot Lifecycle
+
+```mermaid
+stateDiagram-v2
+    [*] --> Created: RobotLab.build
+    Created --> Running: robot.run(state)
+    Running --> ToolExecution: tool_call
+    ToolExecution --> Running: result
+    Running --> Completed: stop_reason
+    Completed --> [*]
+```
+
+### Robot Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `name` | String | Unique identifier within network |
+| `description` | String | What the robot does |
+| `model` | String | LLM model to use |
+| `template` | String | System prompt |
+| `local_tools` | Array | Defined tools |
+| `mcp_clients` | Array | Connected MCP clients |
+
+## Tool
+
+Tools give robots the ability to interact with external systems.
+
+### Tool Structure
+
+```ruby
+tool = RobotLab::Tool.new(
+  name: "get_weather",
+  description: "Get current weather for a location",
+  parameters: {
+    location: {
+      type: "string",
+      description: "City name",
+      required: true
+    },
+    unit: {
+      type: "string",
+      enum: ["celsius", "fahrenheit"],
+      default: "celsius"
+    }
+  },
+  handler: ->(location:, unit: "celsius", **_context) {
+    WeatherAPI.current(location, unit: unit)
+  }
+)
+```
+
+### Tool Execution
+
+When an LLM decides to use a tool:
+
+1. LLM generates a `ToolCallMessage` with tool name and arguments
+2. RobotLab validates arguments against the tool's schema
+3. Tool handler is called with validated arguments
+4. Result is wrapped in a `ToolResultMessage`
+5. Result is sent back to the LLM for continued processing
+
+### Handler Context
+
+Tool handlers receive context about the current execution:
+
+```ruby
+handler: ->(param:, robot:, network:, state:) {
+  # robot - The Robot instance executing the tool
+  # network - The Network (or NetworkRun) context
+  # state - Current State with data, results, memory
+}
+```
+
+!!! tip "Ignoring Context"
+    Use `**_context` to accept but ignore context parameters:
+    ```ruby
+    handler: ->(location:, **_context) { ... }
+    ```
+
+## ToolManifest
+
+When you need to modify tool metadata without changing functionality:
+
+```ruby
+manifest = RobotLab::ToolManifest.new(
+  tool: existing_tool,
+  name: "custom_name",           # Override name
+  description: "New description" # Override description
+)
+```
+
+## Message Types
+
+RobotLab uses a type hierarchy for messages:
+
+```mermaid
+classDiagram
+    Message <|-- TextMessage
+    Message <|-- ToolMessage
+    ToolMessage <|-- ToolCallMessage
+    ToolMessage <|-- ToolResultMessage
+
+    class Message {
+        +String type
+        +String role
+        +String content
+        +String stop_reason
+    }
+
+    class TextMessage {
+        +text?()
+        +user?()
+        +assistant?()
+    }
+
+    class ToolMessage {
+        +String id
+        +String name
+        +Hash input
+    }
+
+    class ToolCallMessage {
+        +Array~ToolMessage~ tools
+    }
+
+    class ToolResultMessage {
+        +ToolMessage tool
+        +Hash content
+    }
+```
+
+### Message Roles
+
+| Role | Description |
+|------|-------------|
+| `user` | Input from the user |
+| `assistant` | Response from the LLM |
+| `system` | System instructions |
+| `tool` | Tool call or result |
+
+### Stop Reasons
+
+| Reason | Description |
+|--------|-------------|
+| `stop` | Natural completion |
+| `tool` | Tool call requested |
+| `max_tokens` | Token limit reached |
+
+## RobotResult
+
+The output from a robot execution:
+
+```ruby
+result = robot.run(state: state, network: network)
+
+result.robot_name   # => "support_agent"
+result.output       # => [TextMessage, ...]
+result.tool_calls   # => [ToolMessage, ...]
+result.stop_reason  # => "stop"
+result.created_at   # => Time
+```
+
+### Accessing Response Content
+
+```ruby
+# Get text response
+text = result.output.select(&:text?).map(&:content).join
+
+# Check if tools were called
+has_tools = result.tool_calls.any?
+
+# Get all tool names called
+tool_names = result.tool_calls.map(&:name)
+```
+
+## Configuration Hierarchy
+
+RobotLab uses a cascading configuration system:
+
+```
+Global (RobotLab.configure)
+│
+├── mcp: [server1, server2]
+├── tools: [tool1, tool2]
+│
+└── Network
+    │
+    ├── mcp: :inherit | :none | [servers]
+    ├── tools: :inherit | :none | [tools]
+    │
+    └── Robot
+        │
+        ├── mcp: :inherit | :none | [servers]
+        └── tools: :inherit | :none | [tools]
+```
+
+The `:inherit` value pulls from the parent level.
+
+## Next Steps
+
+- [Robot Execution](robot-execution.md) - Detailed execution flow
+- [Network Orchestration](network-orchestration.md) - Multi-robot coordination
+- [State Management](state-management.md) - Managing conversation state

data/docs/architecture/index.md

@@ -0,0 +1,138 @@
+# Architecture Overview
+
+RobotLab is designed around a few core architectural principles that enable flexible, composable AI workflows.
+
+## Design Philosophy
+
+### 1. Separation of Concerns
+
+Each component has a single, well-defined responsibility:
+
+- **Robot**: Encapsulates LLM interaction logic and personality
+- **Network**: Orchestrates robot execution and routing
+- **State**: Manages conversation and workflow data
+- **Tool**: Provides external capabilities to robots
+
+### 2. Composability
+
+Components are designed to be mixed and matched:
+
+- Robots can be reused across multiple networks
+- Tools can be shared or robot-specific
+- Networks can be nested or chained
+- State can be persisted and restored
+
+### 3. Provider Agnostic
+
+RobotLab abstracts away LLM provider differences:
+
+- Unified message format across providers
+- Consistent tool calling interface
+- Automatic provider detection from model names
+- Easy switching between providers
+
+## System Architecture
+
+```mermaid
+graph TB
+    subgraph "Application Layer"
+        A[Your Application]
+    end
+
+    subgraph "RobotLab Core"
+        B[Network]
+        C[Router]
+        D[Robot]
+        E[State]
+        F[Memory]
+    end
+
+    subgraph "Integration Layer"
+        G[Adapters]
+        H[MCP Client]
+        I[Tools]
+    end
+
+    subgraph "Provider Layer"
+        J[Anthropic]
+        K[OpenAI]
+        L[Gemini]
+        M[MCP Servers]
+    end
+
+    A --> B
+    B --> C
+    B --> D
+    B --> E
+    E --> F
+    D --> G
+    D --> H
+    D --> I
+    G --> J
+    G --> K
+    G --> L
+    H --> M
+```
+
+## Core Components
+
+| Component | Description | Documentation |
+|-----------|-------------|---------------|
+| **Robot** | LLM-powered agent with personality and tools | [Core Concepts](core-concepts.md) |
+| **Network** | Orchestrates multiple robots | [Network Orchestration](network-orchestration.md) |
+| **State** | Conversation and workflow data | [State Management](state-management.md) |
+| **Router** | Determines robot execution order | [Network Orchestration](network-orchestration.md) |
+| **Memory** | Shared key-value store | [State Management](state-management.md) |
+| **Adapter** | Provider-specific message conversion | [Message Flow](message-flow.md) |
+
+## Data Flow
+
+1. **Input**: User message enters via State
+2. **Routing**: Router selects robot(s) to execute
+3. **Execution**: Robot processes message with LLM
+4. **Tools**: Robot may call tools during execution
+5. **Result**: Robot returns RobotResult
+6. **Iteration**: Router checks for next robot
+7. **Output**: Final results returned to application
+
+## Key Patterns
+
+### Builder Pattern
+
+Robots and networks are constructed using a fluent DSL:
+
+```ruby
+robot = RobotLab.build do
+  name "assistant"
+  model "claude-sonnet-4"
+  template "You are helpful."
+end
+```
+
+### Strategy Pattern
+
+Routers implement custom selection logic:
+
+```ruby
+router = ->(args) {
+  # Custom routing strategy
+  args.call_count.zero? ? :first_robot : nil
+}
+```
+
+### Adapter Pattern
+
+Provider adapters normalize LLM interfaces:
+
+```ruby
+adapter = Adapters::Registry.for(:anthropic)
+messages = adapter.format_messages(robot_lab_messages)
+```
+
+## Next Steps
+
+- [Core Concepts](core-concepts.md) - Deep dive into robots and tools
+- [Robot Execution](robot-execution.md) - How robots process messages
+- [Network Orchestration](network-orchestration.md) - Multi-robot workflows
+- [State Management](state-management.md) - Managing conversation state
+- [Message Flow](message-flow.md) - How messages move through the system

data/docs/architecture/message-flow.md

@@ -0,0 +1,320 @@
+# Message Flow
+
+This page explains how messages move through RobotLab, from user input to LLM response.
+
+## Message Types
+
+RobotLab uses four primary message types:
+
+```mermaid
+classDiagram
+    class Message {
+        <<abstract>>
+        +type: String
+        +role: String
+        +content: String
+        +stop_reason: String
+    }
+
+    class TextMessage {
+        +text?() bool
+        +user?() bool
+        +assistant?() bool
+        +system?() bool
+    }
+
+    class ToolMessage {
+        +id: String
+        +name: String
+        +input: Hash
+        +tool_call?() bool
+    }
+
+    class ToolCallMessage {
+        +tools: Array~ToolMessage~
+    }
+
+    class ToolResultMessage {
+        +tool: ToolMessage
+        +content: Hash
+        +tool_result?() bool
+    }
+
+    Message <|-- TextMessage
+    Message <|-- ToolMessage
+    ToolMessage <|-- ToolCallMessage
+    ToolMessage <|-- ToolResultMessage
+```
+
+### TextMessage
+
+Regular text content from users or assistants:
+
+```ruby
+TextMessage.new(
+  role: "user",
+  content: "What's the weather in Paris?"
+)
+
+TextMessage.new(
+  role: "assistant",
+  content: "The weather in Paris is sunny and 22°C.",
+  stop_reason: "stop"
+)
+```
+
+### ToolMessage
+
+Base class for tool-related messages:
+
+```ruby
+ToolMessage.new(
+  id: "tool_123",
+  name: "get_weather",
+  input: { location: "Paris" }
+)
+```
+
+### ToolCallMessage
+
+LLM's request to execute tools:
+
+```ruby
+ToolCallMessage.new(
+  role: "assistant",
+  content: nil,
+  stop_reason: "tool",
+  tools: [
+    ToolMessage.new(id: "call_1", name: "get_weather", input: { location: "Paris" })
+  ]
+)
+```
+
+### ToolResultMessage
+
+Result from tool execution:
+
+```ruby
+ToolResultMessage.new(
+  tool: tool_message,
+  content: { data: { temp: 22, condition: "sunny" } }
+)
+```
+
+## Message Flow Diagram
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant State
+    participant Robot
+    participant Adapter
+    participant LLM
+
+    User->>State: UserMessage
+    State->>State: Format messages
+    State->>Robot: state.messages
+    Robot->>Adapter: Convert messages
+    Adapter->>LLM: Provider-specific format
+
+    LLM-->>Adapter: Response
+    Adapter-->>Robot: Parse response
+    Robot->>Robot: Execute tools (if any)
+    Robot-->>State: RobotResult
+    State->>State: Append result
+    State-->>User: Response
+```
+
+## Adapter Layer
+
+Adapters convert between RobotLab's message format and provider-specific formats.
+
+### Anthropic Adapter
+
+```ruby
+# RobotLab format
+messages = [
+  TextMessage.new(role: "user", content: "Hello"),
+  TextMessage.new(role: "assistant", content: "Hi there!")
+]
+
+# Converted to Anthropic format
+[
+  { role: "user", content: "Hello" },
+  { role: "assistant", content: "Hi there!" }
+]
+```
+
+### System Message Handling
+
+System messages are handled specially:
+
+```ruby
+# RobotLab
+messages = [
+  TextMessage.new(role: "system", content: "You are helpful."),
+  TextMessage.new(role: "user", content: "Hello")
+]
+
+# Anthropic: system extracted separately
+# OpenAI: system message stays in array
+# Gemini: converted to context
+```
+
+### Tool Message Conversion
+
+Tool calls are provider-specific:
+
+=== "Anthropic"
+
+    ```ruby
+    {
+      type: "tool_use",
+      id: "tool_123",
+      name: "get_weather",
+      input: { location: "Paris" }
+    }
+    ```
+
+=== "OpenAI"
+
+    ```ruby
+    {
+      type: "function",
+      function: {
+        name: "get_weather",
+        arguments: '{"location":"Paris"}'
+      }
+    }
+    ```
+
+## Conversation Building
+
+### Initial State
+
+```ruby
+state = RobotLab.create_state(
+  message: "What's the weather?",
+  data: { location: "Paris" }
+)
+
+state.messages
+# => [TextMessage(role: "user", content: "What's the weather?")]
+```
+
+### After Robot Execution
+
+```ruby
+result = robot.run(state: state, network: network)
+state.append_result(result)
+
+state.messages
+# => [
+#   TextMessage(role: "user", content: "What's the weather?"),
+#   TextMessage(role: "assistant", content: "The weather is sunny.")
+# ]
+```
+
+### With Tool Calls
+
+```ruby
+state.messages
+# => [
+#   TextMessage(role: "user", content: "What's the weather?"),
+#   ToolCallMessage(tools: [ToolMessage(name: "get_weather", ...)]),
+#   ToolResultMessage(content: { temp: 22 }),
+#   TextMessage(role: "assistant", content: "It's 22°C and sunny.")
+# ]
+```
+
+## Format History
+
+The `format_history` method prepares messages for LLM:
+
+```ruby
+# Includes results from previous robots
+formatted = state.format_history
+
+# Returns alternating user/assistant messages
+# with tool calls/results properly interleaved
+```
+
+## Message Predicates
+
+Check message types easily:
+
+```ruby
+message.text?         # Is it a TextMessage?
+message.tool_call?    # Is it a ToolCallMessage?
+message.tool_result?  # Is it a ToolResultMessage?
+
+message.user?         # Is role "user"?
+message.assistant?    # Is role "assistant"?
+message.system?       # Is role "system"?
+
+message.stopped?      # Is stop_reason "stop"?
+message.tool_stop?    # Is stop_reason "tool"?
+```
+
+## Creating Messages
+
+### From Strings
+
+```ruby
+TextMessage.new(role: "user", content: "Hello")
+```
+
+### From Hashes
+
+```ruby
+Message.from_hash(
+  type: "text",
+  role: "user",
+  content: "Hello"
+)
+```
+
+### From UserMessage
+
+```ruby
+user_msg = UserMessage.new("Hello", thread_id: "123")
+text_msg = user_msg.to_message
+# => TextMessage(role: "user", content: "Hello")
+```
+
+## Serialization
+
+Messages can be serialized:
+
+```ruby
+# To hash
+hash = message.to_h
+# => { type: "text", role: "user", content: "Hello" }
+
+# To JSON
+json = message.to_json
+# => '{"type":"text","role":"user","content":"Hello"}'
+
+# From hash
+message = Message.from_hash(hash)
+```
+
+## Provider Registry
+
+The adapter registry maps providers to adapters:
+
+```ruby
+Adapters::Registry.for(:anthropic)  # => Adapters::Anthropic
+Adapters::Registry.for(:openai)     # => Adapters::OpenAI
+Adapters::Registry.for(:gemini)     # => Adapters::Gemini
+
+# Aliases
+Adapters::Registry.for(:azure_openai)  # => Adapters::OpenAI
+Adapters::Registry.for(:bedrock)       # => Adapters::Anthropic
+```
+
+## Next Steps
+
+- [Building Robots](../guides/building-robots.md) - Creating custom robots
+- [Using Tools](../guides/using-tools.md) - Tool message handling
+- [API Reference: Messages](../api/messages/index.md) - Detailed message API