robot_lab 0.0.1

data/docs/architecture/state-management.md

@@ -0,0 +1,323 @@
+# State Management
+
+State in RobotLab tracks all data and history for a conversation or workflow.
+
+## State Structure
+
+The `State` class holds:
+
+```ruby
+state = RobotLab.create_state(
+  message: "Hello!",           # Current user message
+  data: { user_id: "123" }     # Custom workflow data
+)
+
+state.data        # StateProxy - custom key-value data
+state.results     # Array<RobotResult> - execution history
+state.messages    # Array<Message> - formatted conversation
+state.thread_id   # String - optional persistence ID
+state.memory      # Memory - shared key-value store
+```
+
+## Creating State
+
+### Basic Creation
+
+```ruby
+state = RobotLab.create_state(message: "What's the weather?")
+```
+
+### With Custom Data
+
+```ruby
+state = RobotLab.create_state(
+  message: "Process my order",
+  data: {
+    user_id: "user_123",
+    order_id: "ord_456",
+    priority: "high"
+  }
+)
+```
+
+### From Existing Results
+
+```ruby
+state = RobotLab.create_state(
+  message: "Continue our conversation",
+  results: previous_results,
+  thread_id: "thread_abc"
+)
+```
+
+## StateProxy
+
+The `data` attribute is a `StateProxy` that provides convenient access:
+
+```ruby
+state.data[:user_id]          # Hash-style access
+state.data[:user_id] = "456"  # Assignment
+
+state.data.user_id            # Method-style access
+state.data.user_id = "456"    # Method-style assignment
+
+state.data.key?(:user_id)     # Check existence
+state.data.keys               # Get all keys
+state.data.to_h               # Convert to plain hash
+```
+
+### Change Tracking
+
+StateProxy can track changes:
+
+```ruby
+state = State.new(
+  data: { count: 0 },
+  on_change: ->(key, old_val, new_val) {
+    puts "#{key}: #{old_val} -> #{new_val}"
+  }
+)
+
+state.data[:count] = 1  # Prints: "count: 0 -> 1"
+```
+
+## Memory
+
+Memory provides a shared key-value store across robots:
+
+```ruby
+# Store values
+state.memory.remember("user_name", "Alice")
+state.memory.remember("preferences", { theme: "dark" })
+
+# Retrieve values
+name = state.memory.recall("user_name")  # => "Alice"
+
+# Check existence
+state.memory.exists?("user_name")  # => true
+
+# Remove values
+state.memory.forget("user_name")
+
+# List all
+state.memory.all  # => { "user_name" => "Alice", ... }
+```
+
+### Scoped Memory
+
+Organize memory with namespaces:
+
+```ruby
+# Create scoped view
+user_memory = state.memory.scoped("user:123")
+user_memory.remember("last_login", Time.now)
+
+# Access scoped data
+user_memory.recall("last_login")
+
+# Full key is "user:123:last_login"
+state.memory.recall("user:123:last_login")
+```
+
+### Shared Memory
+
+Use the `SHARED` namespace for cross-robot data:
+
+```ruby
+# In first robot
+state.memory.remember("SHARED:context", important_data)
+
+# In second robot (same or different network run)
+data = state.memory.recall("SHARED:context")
+```
+
+### Memory Operations
+
+```ruby
+# Search by pattern
+matches = state.memory.search("user:*")
+
+# Get statistics
+state.memory.stats
+# => { total_keys: 15, namespaces: ["user", "session"] }
+
+# Clear namespace
+state.memory.scoped("temp").clear
+
+# Clear everything
+state.memory.clear_all
+```
+
+## Results
+
+Results track the history of robot executions:
+
+```ruby
+# Append a result
+state.append_result(robot_result)
+
+# Get all results
+state.results
+
+# Get results from index
+state.results_from(5)  # Results starting at index 5
+
+# Format for LLM conversation
+state.format_history
+```
+
+### Result History
+
+Each `RobotResult` contains:
+
+```ruby
+result.robot_name   # Which robot produced this
+result.output       # Array<Message> - response content
+result.tool_calls   # Array<ToolMessage> - tools called
+result.stop_reason  # "stop", "tool", etc.
+result.created_at   # When it was created
+```
+
+## Messages
+
+The `messages` method formats state for LLM consumption:
+
+```ruby
+messages = state.messages
+
+# Returns Array<Message> with:
+# - System message (if present)
+# - Alternating user/assistant messages
+# - Tool calls and results
+```
+
+## Thread ID
+
+For persistent conversations:
+
+```ruby
+# Set thread ID
+state.thread_id = "thread_123"
+
+# Or via UserMessage
+message = UserMessage.new(
+  "Continue",
+  thread_id: "thread_123"
+)
+state = RobotLab.create_state(message: message)
+```
+
+## State Cloning
+
+Create independent copies:
+
+```ruby
+original = RobotLab.create_state(data: { count: 1 })
+clone = original.clone
+
+clone.data[:count] = 2
+original.data[:count]  # Still 1
+```
+
+## Serialization
+
+Convert state to/from hash:
+
+```ruby
+# To hash
+hash = state.to_h
+json = state.to_json
+
+# From hash
+state = State.from_hash(hash)
+```
+
+### Hash Structure
+
+```ruby
+{
+  data: { ... },
+  results: [
+    {
+      robot_name: "assistant",
+      output: [...],
+      tool_calls: [...],
+      stop_reason: "stop"
+    }
+  ],
+  thread_id: "thread_123"
+}
+```
+
+## UserMessage
+
+Enhanced message with metadata:
+
+```ruby
+message = UserMessage.new(
+  "What's the status of my order?",
+  thread_id: "thread_123",
+  system_prompt: "Respond in Spanish",  # Augment system prompt
+  metadata: {
+    user_id: "user_456",
+    source: "web_chat"
+  }
+)
+
+state = RobotLab.create_state(message: message)
+```
+
+### UserMessage Properties
+
+| Property | Description |
+|----------|-------------|
+| `content` | The message text |
+| `thread_id` | Conversation thread ID |
+| `system_prompt` | Additional system instructions |
+| `metadata` | Custom key-value data |
+| `id` | Unique message identifier |
+| `created_at` | Timestamp |
+
+## Best Practices
+
+### 1. Use Memory for Cross-Robot Data
+
+```ruby
+# Don't pass data through routing
+router = ->(args) {
+  # Bad: parsing previous output for data
+}
+
+# Do: use memory
+state.memory.remember("classification", "billing")
+# Later robot reads it directly
+```
+
+### 2. Scope Memory Appropriately
+
+```ruby
+# Session data
+session = state.memory.scoped("session:#{session_id}")
+
+# User preferences
+user = state.memory.scoped("user:#{user_id}")
+
+# Temporary working data
+temp = state.memory.scoped("temp")
+```
+
+### 3. Keep Data Minimal
+
+```ruby
+# Don't store large objects
+state.data[:huge_response] = api_response  # Bad
+
+# Store references instead
+state.data[:response_id] = response.id  # Good
+```
+
+## Next Steps
+
+- [Memory System](../guides/memory.md) - Advanced memory patterns
+- [History Guide](../guides/history.md) - Persisting state
+- [Message Flow](message-flow.md) - How messages are processed

data/docs/assets/css/custom.css

@@ -0,0 +1,56 @@
+/* Custom styles for RobotLab documentation */
+
+/* Robot-themed accent colors */
+:root {
+  --md-primary-fg-color: #673ab7;
+  --md-primary-fg-color--light: #9575cd;
+  --md-primary-fg-color--dark: #512da8;
+  --md-accent-fg-color: #ffc107;
+}
+
+/* Code block styling */
+.md-typeset code {
+  background-color: rgba(103, 58, 183, 0.1);
+}
+
+/* Admonition customization */
+.md-typeset .admonition.robot,
+.md-typeset details.robot {
+  border-color: #673ab7;
+}
+
+.md-typeset .robot > .admonition-title,
+.md-typeset .robot > summary {
+  background-color: rgba(103, 58, 183, 0.1);
+}
+
+.md-typeset .robot > .admonition-title::before,
+.md-typeset .robot > summary::before {
+  background-color: #673ab7;
+  -webkit-mask-image: var(--md-admonition-icon--robot);
+  mask-image: var(--md-admonition-icon--robot);
+}
+
+/* Grid cards spacing */
+.md-typeset .grid.cards > ul > li {
+  margin-bottom: 1em;
+}
+
+/* API reference table styling */
+.md-typeset table:not([class]) th {
+  background-color: rgba(103, 58, 183, 0.1);
+}
+
+/* Mermaid diagram styling */
+.mermaid {
+  background: transparent !important;
+}
+
+/* Dark mode adjustments */
+[data-md-color-scheme="slate"] {
+  --md-code-bg-color: #1e1e2e;
+}
+
+[data-md-color-scheme="slate"] .md-typeset code {
+  background-color: rgba(149, 117, 205, 0.2);
+}

data/docs/concepts.md

@@ -0,0 +1,216 @@
+# Core Concepts
+
+Understanding the fundamental concepts in RobotLab will help you build effective AI applications.
+
+## Robot
+
+A **Robot** is an LLM-powered agent with a specific personality, capabilities, and tools. Each robot has:
+
+- **Name**: A unique identifier within a network
+- **Description**: What the robot does (used for routing decisions)
+- **Template/System Prompt**: Instructions that define the robot's behavior
+- **Model**: The LLM model to use (e.g., `claude-sonnet-4`)
+- **Tools**: Custom functions the robot can call
+
+```ruby
+robot = RobotLab.build do
+  name "support_agent"
+  description "Handles customer support inquiries"
+  model "claude-sonnet-4"
+  template "You are a friendly customer support agent..."
+
+  tool :lookup_order do
+    description "Look up order details by order ID"
+    parameter :order_id, type: :string, required: true
+    handler { |order_id:| Order.find(order_id).to_h }
+  end
+end
+```
+
+## Network
+
+A **Network** is a collection of robots orchestrated using [SimpleFlow](https://github.com/MadBomber/simple_flow) pipelines. Networks provide:
+
+- **Task-Based Orchestration**: Define tasks with dependencies and routing
+- **Parallel Execution**: Tasks with the same dependencies run concurrently
+- **Optional Task Activation**: Dynamic routing based on robot output
+- **Per-Task Configuration**: Each task can have its own context, tools, and MCP servers
+
+```ruby
+network = RobotLab.create_network(name: "customer_service") do
+  task :classifier, classifier_robot, depends_on: :none
+  task :billing, billing_robot,
+       context: { department: "billing" },
+       depends_on: :optional
+  task :technical, technical_robot,
+       context: { department: "technical" },
+       depends_on: :optional
+end
+```
+
+## Task
+
+A **Task** wraps a robot for use in a network pipeline with per-task configuration:
+
+- **Context**: Task-specific context deep-merged with network run params
+- **MCP**: MCP servers available to this task
+- **Tools**: Tools available to this task
+- **Memory**: Task-specific memory
+- **Dependencies**: `:none`, `[:task1, :task2]`, or `:optional`
+
+```ruby
+task :billing, billing_robot,
+     context: { department: "billing", escalation_level: 2 },
+     tools: [RefundTool, InvoiceTool],
+     depends_on: :optional
+```
+
+## SimpleFlow::Result
+
+Networks use `SimpleFlow::Result` for data flow between tasks:
+
+```ruby
+result.value      # Current task's output (RobotResult)
+result.context    # Accumulated context from all tasks
+result.halted?    # Whether execution stopped early
+result.continued? # Whether execution continues
+```
+
+### Result Methods
+
+| Method | Purpose |
+|--------|---------|
+| `continue(value)` | Continue to next tasks |
+| `halt(value)` | Stop pipeline execution |
+| `with_context(key, val)` | Add data to context |
+| `activate(task_name)` | Enable optional task |
+
+## Tool
+
+**Tools** are functions that robots can call to interact with external systems:
+
+```ruby
+tool = RobotLab::Tool.new(
+  name: "get_weather",
+  description: "Get current weather for a location",
+  parameters: {
+    location: { type: "string", description: "City name" }
+  },
+  handler: ->(location:, **_context) {
+    WeatherService.current(location)
+  }
+)
+```
+
+## Message Types
+
+RobotLab uses several message types to represent conversation content:
+
+| Type | Purpose |
+|------|---------|
+| `TextMessage` | User or assistant text content |
+| `ToolMessage` | Tool definition with name and parameters |
+| `ToolCallMessage` | Request from LLM to execute a tool |
+| `ToolResultMessage` | Result returned from tool execution |
+
+## Memory
+
+**Memory** provides persistent storage across robot executions:
+
+```ruby
+# Robot with inherent memory
+robot = RobotLab.build(name: "assistant", system_prompt: "You are helpful.")
+robot.run(message: "My name is Alice")
+robot.run(message: "What's my name?")  # Memory persists
+
+# Access robot's memory
+robot.memory[:user_id] = 123
+robot.memory.data[:category] = "billing"
+
+# Runtime memory injection
+robot.run(message: "Help me", memory: { session_id: "abc123" })
+
+# Reset memory
+robot.reset_memory
+```
+
+## MCP (Model Context Protocol)
+
+**MCP** allows robots to connect to external tool servers:
+
+```ruby
+robot = RobotLab.build(
+  name: "developer",
+  mcp: [
+    { name: "filesystem", transport: { type: "stdio", command: "mcp-server-filesystem" } },
+    { name: "github", transport: { type: "stdio", command: "mcp-server-github" } }
+  ]
+)
+```
+
+## Execution Flow
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant Network
+    participant Pipeline
+    participant Task
+    participant Robot
+    participant LLM
+    participant Tool
+
+    User->>Network: run(message, context)
+    Network->>Pipeline: call(initial_result)
+    Pipeline->>Task: call(result)
+    Task->>Robot: call(enhanced_result)
+    Robot->>LLM: inference(messages, tools)
+
+    alt Tool Call
+        LLM-->>Robot: tool_call
+        Robot->>Tool: execute(params)
+        Tool-->>Robot: result
+        Robot->>LLM: continue with result
+    end
+
+    LLM-->>Robot: response
+    Robot-->>Task: RobotResult
+    Task-->>Pipeline: result.continue(value)
+
+    alt Optional Task Activated
+        Pipeline->>Task: call activated task
+    end
+
+    Pipeline-->>Network: final result
+    Network-->>User: SimpleFlow::Result
+```
+
+## Conditional Routing
+
+Use custom Robot subclasses to implement intelligent routing:
+
+```ruby
+class ClassifierRobot < RobotLab::Robot
+  def call(result)
+    robot_result = run(**extract_run_context(result))
+
+    new_result = result
+      .with_context(@name.to_sym, robot_result)
+      .continue(robot_result)
+
+    # Activate appropriate specialist
+    category = robot_result.last_text_content.to_s.downcase
+    case category
+    when /billing/ then new_result.activate(:billing)
+    when /technical/ then new_result.activate(:technical)
+    else new_result.activate(:general)
+    end
+  end
+end
+```
+
+## Next Steps
+
+- [Quick Start Guide](getting-started/quick-start.md) - Build your first robot
+- [Building Robots](guides/building-robots.md) - Detailed robot creation guide
+- [Creating Networks](guides/creating-networks.md) - Network orchestration patterns