robot_lab 0.0.1 → 0.0.6

data/docs/architecture/index.md

@@ -8,28 +8,30 @@ RobotLab is designed around a few core architectural principles that enable flex
 
 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
+- **Robot**: LLM-powered agent (subclass of `RubyLLM::Agent`) with personality, tools, and memory
+- **Network**: Orchestrates robot execution as a DAG pipeline via SimpleFlow
+- **Memory**: Reactive key-value store for robot and network data
+- **Tool**: Provides external capabilities to robots (inherits from `RubyLLM::Tool`)
+- **Task**: Wraps a robot for pipeline execution with per-task configuration
 
 ### 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
+- Robots can be used standalone or within networks
+- Tools can be shared across robots or scoped per-robot via `local_tools:`
+- Networks define DAG pipelines with sequential, parallel, and optional execution
+- Memory can be standalone (per-robot) or shared (per-network)
+- `with_*` methods return `self` for fluent chaining
 
 ### 3. Provider Agnostic
 
-RobotLab abstracts away LLM provider differences:
+RobotLab abstracts away LLM provider differences through RubyLLM:
 
-- Unified message format across providers
+- Unified interface across Anthropic, OpenAI, Gemini, DeepSeek, Mistral, and others
 - Consistent tool calling interface
 - Automatic provider detection from model names
-- Easy switching between providers
+- Easy switching between providers via configuration
 
 ## System Architecture
 
@@ -41,98 +43,134 @@ graph TB
 
     subgraph "RobotLab Core"
         B[Network]
-        C[Router]
-        D[Robot]
-        E[State]
-        F[Memory]
+        C[Task]
+        D[Robot < RubyLLM::Agent]
+        E[Memory]
+        F[RobotResult]
+    end
+
+    subgraph "Configuration"
+        G[Config < MywayConfig::Base]
     end
 
     subgraph "Integration Layer"
-        G[Adapters]
         H[MCP Client]
-        I[Tools]
+        I[Tools < RubyLLM::Tool]
+        J[Templates / prompt_manager]
+    end
+
+    subgraph "Execution Layer"
+        K[SimpleFlow::Pipeline]
+        L[RubyLLM Chat]
     end
 
     subgraph "Provider Layer"
-        J[Anthropic]
-        K[OpenAI]
-        L[Gemini]
-        M[MCP Servers]
+        M[Anthropic]
+        N[OpenAI]
+        O[Gemini]
+        P[MCP Servers]
     end
 
     A --> B
+    A --> D
     B --> C
-    B --> D
+    C --> D
+    B --> K
     B --> E
-    E --> F
-    D --> G
+    D --> E
+    D --> L
     D --> H
     D --> I
-    G --> J
-    G --> K
+    D --> J
+    D --> F
+    G --> D
     G --> L
-    H --> M
+    L --> M
+    L --> N
+    L --> O
+    H --> P
 ```
 
 ## 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) |
+| **Robot** | LLM agent (subclass of `RubyLLM::Agent`) with template-based prompts, tools, and memory | [Core Concepts](core-concepts.md) |
+| **Network** | Orchestrates multiple robots as a SimpleFlow pipeline | [Network Orchestration](network-orchestration.md) |
+| **Memory** | Reactive key-value store with pub/sub and blocking reads | [Memory Management](state-management.md) |
+| **Task** | Wraps a robot for pipeline execution with per-task config | [Network Orchestration](network-orchestration.md) |
+| **RobotResult** | Captures LLM output, tool calls, and metadata from a run | [Message Flow](message-flow.md) |
+| **Config** | MywayConfig-based configuration with env var and file support | [Configuration](#configuration) |
+
+## Configuration
+
+RobotLab uses MywayConfig (`Config < MywayConfig::Base`) instead of a `configure` block. Configuration is loaded from multiple sources in priority order:
+
+1. **Bundled defaults** (`lib/robot_lab/config/defaults.yml`)
+2. **Environment overrides** (development, test, production sections)
+3. **XDG user config** (`~/.config/robot_lab/config.yml`)
+4. **Project config** (`./config/robot_lab.yml`)
+5. **Environment variables** (`ROBOT_LAB_*` prefix, double underscore for nesting)
+
+```ruby
+# Access configuration
+RobotLab.config.ruby_llm.model            #=> "claude-sonnet-4"
+RobotLab.config.ruby_llm.request_timeout  #=> 120
+```
 
 ## 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
+1. **Input**: User calls `robot.run("message")` or `network.run(message: "...")`
+2. **Memory**: Robot resolves active memory (standalone or network-shared)
+3. **MCP**: Robot resolves and initializes MCP clients from hierarchical config
+4. **Tools**: Robot resolves and filters tools from hierarchical config
+5. **Execution**: Robot delegates to `Agent#ask` which calls `@chat.ask` on RubyLLM
+6. **Tool Loop**: LLM may invoke tools; RubyLLM handles the tool call/result loop
+7. **Result**: Robot builds and returns a `RobotResult`
+8. **Network**: If in a network, result flows to dependent tasks via SimpleFlow
 
 ## Key Patterns
 
-### Builder Pattern
+### Factory Methods
 
-Robots and networks are constructed using a fluent DSL:
+Robots and networks are created via factory methods on the `RobotLab` module:
 
 ```ruby
-robot = RobotLab.build do
-  name "assistant"
-  model "claude-sonnet-4"
-  template "You are helpful."
+robot = RobotLab.build(
+  name: "assistant",
+  template: :assistant,
+  context: { tone: "friendly" }
+)
+
+network = RobotLab.create_network(name: "pipeline") do
+  task :analyst, analyst_robot, depends_on: :none
+  task :writer, writer_robot, depends_on: [:analyst]
 end
 ```
 
-### Strategy Pattern
+### Fluent Chaining
 
-Routers implement custom selection logic:
+`with_*` methods on Robot delegate to the underlying `@chat` and return `self`:
 
 ```ruby
-router = ->(args) {
-  # Custom routing strategy
-  args.call_count.zero? ? :first_robot : nil
-}
+robot = RobotLab.build(name: "bot")
+  .with_instructions("Be concise.")
+  .with_temperature(0.3)
+  .with_model("gpt-4o")
 ```
 
-### Adapter Pattern
+### Hierarchical Configuration
 
-Provider adapters normalize LLM interfaces:
+Tools and MCP servers use hierarchical resolution: `runtime > robot build > network > global config`. Values can be `:none`, `:inherit`, or explicit arrays.
 
-```ruby
-adapter = Adapters::Registry.for(:anthropic)
-messages = adapter.format_messages(robot_lab_messages)
-```
+### SimpleFlow Pipeline
+
+Networks are thin wrappers around `SimpleFlow::Pipeline`. Each robot is wrapped in a `Task` that implements the `call(result)` interface. Tasks define dependencies (`:none`, `[:task_names]`, or `:optional`) to control execution order.
 
 ## 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
+- [Memory Management](state-management.md) - Managing memory and reactive features
 - [Message Flow](message-flow.md) - How messages move through the system

data/docs/architecture/message-flow.md

@@ -41,9 +41,10 @@ classDiagram
     }
 
     Message <|-- TextMessage
-    Message <|-- ToolMessage
-    ToolMessage <|-- ToolCallMessage
-    ToolMessage <|-- ToolResultMessage
+    Message <|-- ToolCallMessage
+    Message <|-- ToolResultMessage
+    ToolMessage -- ToolCallMessage
+    ToolMessage -- ToolResultMessage
 ```
 
 ### TextMessage
@@ -58,14 +59,14 @@ TextMessage.new(
 
 TextMessage.new(
   role: "assistant",
-  content: "The weather in Paris is sunny and 22°C.",
+  content: "The weather in Paris is sunny and 22 degrees C.",
   stop_reason: "stop"
 )
 ```
 
 ### ToolMessage
 
-Base class for tool-related messages:
+Represents a tool invocation with its parameters:
 
 ```ruby
 ToolMessage.new(
@@ -77,7 +78,7 @@ ToolMessage.new(
 
 ### ToolCallMessage
 
-LLM's request to execute tools:
+LLM's request to execute one or more tools:
 
 ```ruby
 ToolCallMessage.new(
@@ -101,147 +102,159 @@ ToolResultMessage.new(
 )
 ```
 
-## Message Flow Diagram
+## Message Flow: Standalone Robot
+
+The primary execution path is `robot.run("message")`:
 
 ```mermaid
 sequenceDiagram
     participant User
-    participant State
     participant Robot
-    participant Adapter
+    participant Memory
+    participant MCP
+    participant Tools
+    participant Agent
+    participant Chat
     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
-```
+    User->>Robot: robot.run("message")
+    Robot->>Memory: resolve_active_memory
+    Memory-->>Robot: active memory
 
-## Adapter Layer
+    Robot->>MCP: resolve_mcp_hierarchy
+    MCP-->>Robot: resolved MCP config
+    Robot->>Robot: ensure_mcp_clients
 
-Adapters convert between RobotLab's message format and provider-specific formats.
+    Robot->>Tools: resolve_tools_hierarchy
+    Tools-->>Robot: filtered tools
+    Robot->>Chat: @chat.with_tools(...)
 
-### Anthropic Adapter
+    Robot->>Agent: ask("message")
+    Agent->>Chat: @chat.ask("message")
+    Chat->>LLM: Provider API call
 
-```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!" }
-]
+    loop Tool Loop (handled by RubyLLM)
+        LLM-->>Chat: Tool call response
+        Chat->>Tools: Execute tool
+        Tools-->>Chat: Tool result
+        Chat->>LLM: Send tool result
+    end
+
+    LLM-->>Chat: Final response
+    Chat-->>Agent: RubyLLM::Response
+    Agent-->>Robot: response
+
+    Robot->>Robot: build_result(response, memory)
+    Robot-->>User: RobotResult
 ```
 
-### System Message Handling
+### Step-by-Step
 
-System messages are handled specially:
+1. **`robot.run("message")`**: Entry point. Accepts a positional string argument.
 
-```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
-```
+2. **Resolve Memory**: Determines which memory to use:
+   - `network_memory` if provided (network execution)
+   - `network.memory` if in a network context
+   - `robot.memory` (standalone, the default)
 
-### Tool Message Conversion
+3. **Merge Runtime Memory**: If a `memory:` keyword argument is passed, it is merged into the active memory.
 
-Tool calls are provider-specific:
+4. **Set Current Writer**: Sets `memory.current_writer = robot.name` so subscription callbacks know which robot wrote a value.
 
-=== "Anthropic"
+5. **Resolve MCP Hierarchy**: Resolves MCP server configuration through the hierarchy: `runtime > robot build > network > global config`.
 
-    ```ruby
-    {
-      type: "tool_use",
-      id: "tool_123",
-      name: "get_weather",
-      input: { location: "Paris" }
-    }
-    ```
+6. **Ensure MCP Clients**: Initializes or updates MCP client connections. Discovers tools from connected MCP servers.
 
-=== "OpenAI"
+7. **Resolve Tools Hierarchy**: Resolves which tools are available through the same hierarchy.
 
-    ```ruby
-    {
-      type: "function",
-      function: {
-        name: "get_weather",
-        arguments: '{"location":"Paris"}'
-      }
-    }
-    ```
+8. **Filter Tools**: Applies the resolved tool list to `@chat.with_tools(...)`.
 
-## Conversation Building
+9. **Agent#ask**: Delegates to the parent class `RubyLLM::Agent#ask`, which calls `@chat.ask(message)`.
 
-### Initial State
+10. **LLM Interaction**: RubyLLM handles the provider-specific API call, including the tool call/result loop.
 
-```ruby
-state = RobotLab.create_state(
-  message: "What's the weather?",
-  data: { location: "Paris" }
-)
+11. **Build Result**: Wraps the LLM response in a `RobotResult` containing output messages, tool calls, and metadata.
 
-state.messages
-# => [TextMessage(role: "user", content: "What's the weather?")]
-```
+12. **Return**: Returns the `RobotResult` to the caller.
 
-### After Robot Execution
+## Message Flow: Network 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.")
-# ]
+When running through a network, the flow adds pipeline orchestration:
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant Network
+    participant Pipeline
+    participant Task
+    participant Robot
+    participant LLM
+
+    User->>Network: network.run(message: "...")
+    Network->>Network: Inject network_memory into run_context
+    Network->>Pipeline: SimpleFlow::Pipeline.call_parallel(initial_result)
+
+    loop For each ready task
+        Pipeline->>Task: task.call(result)
+        Task->>Task: Deep merge task context with run_params
+        Task->>Robot: robot.call(enhanced_result)
+        Robot->>Robot: extract_run_context(result)
+        Robot->>Robot: run(message, network_memory: ...)
+        Robot->>LLM: Agent#ask -> @chat.ask
+        LLM-->>Robot: Response
+        Robot-->>Task: result.with_context(:name, robot_result).continue(robot_result)
+        Task-->>Pipeline: SimpleFlow::Result
+    end
+
+    Pipeline-->>Network: Final SimpleFlow::Result
+    Network-->>User: result
 ```
 
-### With Tool Calls
+### Key Points
+
+- **Network creates initial result**: `SimpleFlow::Result.new(run_context, context: { run_params: run_context })`
+- **Task wraps robot**: Each `Task` deep-merges its own context with the run params before delegating to the robot
+- **Robot extracts context**: `extract_run_context(result)` pulls the message, MCP, tools, and memory from the SimpleFlow result
+- **Shared memory**: All robots use `network.memory` during network execution
+- **Result accumulation**: Each task stores its `RobotResult` in `result.context[:task_name]`
+
+## RobotResult
+
+The return value of `robot.run("message")`:
 
 ```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.")
-# ]
+result = robot.run("What is Ruby?")
+
+result.last_text_content  #=> "Ruby is a dynamic programming language..."
+result.has_tool_calls?    #=> false
+result.robot_name         #=> "assistant"
+result.output             #=> [TextMessage(role: "assistant", content: "...")]
+result.tool_calls         #=> []
+result.stop_reason        #=> "stop"
+result.created_at         #=> Time
+result.id                 #=> "uuid"
+result.checksum           #=> "sha256-hex"
 ```
 
-## Format History
-
-The `format_history` method prepares messages for LLM:
+### Result Serialization
 
 ```ruby
-# Includes results from previous robots
-formatted = state.format_history
+# Export for persistence (excludes debug fields)
+hash = result.export
+
+# Full hash including debug fields
+hash = result.to_h
+
+# JSON
+json = result.to_json
 
-# Returns alternating user/assistant messages
-# with tool calls/results properly interleaved
+# Reconstruct from hash
+result = RobotResult.from_hash(hash)
 ```
 
 ## Message Predicates
 
-Check message types easily:
+Check message types:
 
 ```ruby
 message.text?         # Is it a TextMessage?
@@ -274,14 +287,6 @@ Message.from_hash(
 )
 ```
 
-### 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:
@@ -289,32 +294,36 @@ Messages can be serialized:
 ```ruby
 # To hash
 hash = message.to_h
-# => { type: "text", role: "user", content: "Hello" }
+#=> { 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
+## Template Resolution
 
-The adapter registry maps providers to adapters:
+When a robot has a template, it is resolved at build time via prompt_manager:
 
 ```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
+robot = RobotLab.build(
+  name: "helper",
+  template: :helper,
+  context: { tone: "friendly" }
+)
 ```
 
+The template resolution process:
+1. `PM.parse(:helper)` loads the template file from the configured prompts directory
+2. YAML front matter is extracted and applied to the chat (model, temperature, etc.)
+3. The template body is rendered with the provided context
+4. The rendered text is set as system instructions via `@chat.with_instructions(rendered)`
+
+If both `template:` and `system_prompt:` are provided, the template is applied first, then the system prompt is appended via a second `@chat.with_instructions` call.
+
 ## 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
+- [Memory Management](state-management.md) - How memory stores conversation data
+- [Network Orchestration](network-orchestration.md) - Multi-robot pipeline execution