robot_lab 0.0.1 → 0.0.6

data/docs/architecture/robot-execution.md

@@ -4,240 +4,293 @@ This page details how a robot processes messages and generates responses.
 
 ## Execution Overview
 
-When you call `robot.run(state:, network:)`, several steps occur:
+When you call `robot.run("message")`, several steps occur:
 
 ```mermaid
 sequenceDiagram
     participant App as Application
     participant Robot
-    participant Model as RoboticModel
-    participant Adapter
+    participant Memory
+    participant Chat as @chat (RubyLLM)
     participant LLM
 
-    App->>Robot: run(state, network)
-    Robot->>Robot: resolve_tools()
-    Robot->>Model: infer(messages, tools)
-    Model->>Adapter: format_messages()
-    Model->>LLM: API Request
+    App->>Robot: run("message")
+    Robot->>Memory: resolve_active_memory()
+    Robot->>Robot: resolve_mcp_hierarchy()
+    Robot->>Robot: resolve_tools_hierarchy()
+    Robot->>Robot: ensure_mcp_clients()
+    Robot->>Robot: filtered_tools()
+    Robot->>Chat: with_tools(*filtered)
+    Robot->>Chat: ask("message")
+    Chat->>LLM: API Request
 
     loop Tool Calls
-        LLM-->>Model: tool_call response
-        Model->>Robot: execute_tool()
-        Robot->>Model: tool_result
-        Model->>LLM: continue
+        LLM-->>Chat: tool_call response
+        Chat->>Chat: execute tool
+        Chat->>LLM: tool result
     end
 
-    LLM-->>Model: final response
-    Model->>Adapter: parse_response()
-    Model-->>Robot: InferenceResponse
+    LLM-->>Chat: final response
+    Chat-->>Robot: RubyLLM::Response
+    Robot->>Robot: build_result(response)
     Robot-->>App: RobotResult
 ```
 
 ## Step-by-Step Flow
 
-### 1. Tool Resolution
+### 1. Memory Resolution
 
-Before making any LLM call, the robot resolves available tools:
+The robot determines which memory to use for this run:
 
 ```ruby
-# Internal process
-tools = []
-tools += local_tools           # Tools defined on robot
-tools += mcp_tools             # Tools from MCP servers
-tools = apply_whitelist(tools) # Filter by allowed tools
+# Priority order:
+# 1. Explicit network_memory: parameter
+# 2. Network's memory (if running in a network)
+# 3. Robot's inherent @memory (standalone mode)
+run_memory = resolve_active_memory(network: network, network_memory: network_memory)
+
+# Merge runtime memory if provided
+case memory
+when Memory then run_memory = memory
+when Hash   then run_memory.merge!(memory)
+end
+
+# Track who is writing to memory
+run_memory.current_writer = @name
 ```
 
-### 2. Message Preparation
+### 2. MCP Hierarchy Resolution
 
-The robot prepares messages from state:
+MCP servers are resolved through a hierarchy: **runtime > robot build-time > network > global config**.
 
 ```ruby
-messages = []
-messages << system_message     # From template
-messages += state.messages     # Conversation history
-messages << user_message       # Current input
+# Resolve build-time config against network/global
+parent_value = network&.network&.mcp || RobotLab.config.mcp
+build_resolved = ToolConfig.resolve_mcp(@mcp_config, parent_value: parent_value)
+
+# Then resolve runtime override against build-time
+resolved_mcp = ToolConfig.resolve_mcp(runtime_mcp, parent_value: build_resolved)
 ```
 
-### 3. LLM Inference
+Values at each level:
 
-Messages are sent to the LLM via `RoboticModel`:
+- `:none` -- no MCP servers at this level
+- `:inherit` -- use parent level's MCP config
+- `Array` -- explicit list of server configurations
+
+### 3. MCP Client Initialization
+
+If MCP servers need to be connected (or reconnected), the robot initializes clients:
 
 ```ruby
-response = model.infer(
-  messages,
-  tools,
-  tool_choice: "auto",
-  streaming: streaming_callback
-)
+# Connect to each MCP server
+mcp_servers.each do |server_config|
+  client = MCP::Client.new(server_config)
+  client.connect
+
+  if client.connected?
+    @mcp_clients[client.server.name] = client
+    discover_mcp_tools(client, server_name)  # Auto-discover tools
+  end
+end
 ```
 
-### 4. Tool Execution Loop
+### 4. Tools Resolution
 
-If the LLM requests tool calls:
+Tools are resolved through the same hierarchy and filtered:
 
 ```ruby
-loop do
-  if response.wants_tools?
-    response.tool_calls.each do |tool_call|
-      result = execute_tool(tool_call)
-      # Result sent back to LLM
-    end
-    response = model.continue_with_results(results)
-  else
-    break
-  end
-end
+# Collect all available tools
+available = @local_tools + @mcp_tools
+
+# Apply whitelist if specified
+filtered = ToolConfig.filter_tools(available, allowed_names: resolved_tools)
+
+# Apply tools to the persistent chat
+@chat.with_tools(*filtered) if filtered.any?
 ```
 
-### 5. Result Construction
+### 5. LLM Inference
 
-Finally, a `RobotResult` is created:
+The message is sent to the LLM via `Agent#ask`, which delegates to `@chat.ask`:
 
 ```ruby
-RobotResult.new(
-  robot_name: name,
-  output: response.output,
-  tool_calls: executed_tools,
-  stop_reason: response.stop_reason
-)
+# Robot#run calls Agent#ask
+response = ask(message, **kwargs)
+
+# Internally, Agent#ask calls:
+# @chat.ask(message)
 ```
 
-## Tool Execution
+The persistent `@chat` (a `RubyLLM::Chat` instance) handles:
 
-### Tool Call Processing
+- Maintaining conversation history
+- Sending the system prompt
+- Formatting messages for the provider
+- Executing the tool call loop automatically
 
-When the LLM requests a tool:
+### 6. Tool Execution Loop
 
-1. **Identify Tool**: Match tool name to registered tools
-2. **Validate Input**: Check parameters against schema
-3. **Execute Handler**: Call the tool's handler function
-4. **Capture Result**: Wrap response in ToolResultMessage
-5. **Return to LLM**: Send result for continued processing
+RubyLLM's `@chat` handles the tool loop automatically. When the LLM requests a tool call:
 
-### Execution Context
+1. `@chat` identifies the tool from its registered tools
+2. Calls the tool's `execute` method (for `RubyLLM::Tool` subclasses) or `call` method (for `RobotLab::Tool`)
+3. Sends the result back to the LLM
+4. Repeats until the LLM produces a final text response
 
-Tools receive context about their execution environment:
+The `on_tool_call` and `on_tool_result` callbacks fire during this loop if configured:
 
 ```ruby
-tool.handler.call(
-  **tool_call.input,  # User-provided arguments
-  robot: self,        # The executing robot
-  network: network,   # Network context
-  state: state        # Current state
-)
+# These callbacks are registered on @chat during Robot#initialize
+@chat.on_tool_call(&@on_tool_call) if @on_tool_call
+@chat.on_tool_result(&@on_tool_result) if @on_tool_result
 ```
 
-### Error Handling
+### 7. Result Construction
 
-Tool errors are captured and returned to the LLM:
+After the LLM responds, a `RobotResult` is built:
 
 ```ruby
-begin
-  result = tool.handler.call(**args)
-  ToolResultMessage.new(tool: tool_call, content: { data: result })
-rescue StandardError => e
-  ToolResultMessage.new(tool: tool_call, content: { error: e.message })
+def build_result(response, _memory)
+  output = if response.respond_to?(:content) && response.content
+    [TextMessage.new(role: 'assistant', content: response.content)]
+  else
+    []
+  end
+
+  tool_calls = response.respond_to?(:tool_calls) ? (response.tool_calls || []) : []
+
+  RobotResult.new(
+    robot_name: @name,
+    output: output,
+    tool_calls: normalize_tool_calls(tool_calls),
+    stop_reason: response.respond_to?(:stop_reason) ? response.stop_reason : nil
+  )
 end
 ```
 
-## Iteration Limits
+## RobotResult
 
-Robot execution has safeguards:
+The result object from a `robot.run` call:
 
-| Limit | Default | Purpose |
-|-------|---------|---------|
-| `max_tool_iterations` | 10 | Max tool calls per robot run |
-
-When limits are reached, execution stops with the current state.
+```ruby
+result = robot.run("Hello!")
+
+result.robot_name       # => "assistant"
+result.output           # => [TextMessage, ...]
+result.tool_calls       # => [ToolResultMessage, ...]
+result.stop_reason      # => "stop" or nil
+result.created_at       # => Time
+result.id               # => UUID string
+
+# Convenience methods
+result.last_text_content  # => "Hi there!" (last text message content)
+result.has_tool_calls?    # => false
+result.stopped?           # => true
+```
 
 ## Streaming
 
-Robots support streaming responses:
+Robots support streaming by passing a block to `run`:
 
 ```ruby
-robot.run(
-  state: state,
-  network: network,
-  streaming: ->(event) {
-    case event.type
-    when :delta then print event.content
-    when :tool_call then puts "Calling: #{event.tool_name}"
-    end
-  }
-)
+result = robot.run("Tell me a story") do |event|
+  print event.text if event.respond_to?(:text)
+end
 ```
 
-### Streaming Events
+The block is forwarded to `Agent#ask` which passes it to `@chat.ask`. Streaming events are provider-specific but typically include text deltas.
 
-| Event Type | Description |
-|------------|-------------|
-| `run.started` | Robot execution began |
-| `delta` | Text content chunk |
-| `tool_call` | Tool execution starting |
-| `tool_result` | Tool execution complete |
-| `run.completed` | Robot execution finished |
-| `run.failed` | Error occurred |
+## Template Resolution
 
-## Model Selection
+When a robot has a `template:`, it is resolved during initialization:
 
-The model is determined by:
+```ruby
+# 1. Parse the template via prompt_manager
+parsed = PM.parse(@template)
 
-1. Robot's explicit `model` setting
-2. Network's `default_model`
-3. Global `RobotLab.configuration.default_model`
+# 2. Extract and apply front matter config
+#    (model, temperature, top_p, etc.)
+apply_front_matter_config(parsed.metadata)
 
-```ruby
-robot = RobotLab.build do
-  model "claude-sonnet-4"  # Takes precedence
-end
+# 3. Render the template body with context
+rendered = parsed.to_s(**resolved_context)
 
-network = RobotLab.create_network do
-  default_model "gpt-4"    # Fallback for robots without model
-end
+# 4. Set as system instructions on @chat
+@chat.with_instructions(rendered)
 ```
 
-## Provider Detection
+### Front Matter Config Keys
+
+Templates can configure the chat via YAML front matter:
 
-If no provider is specified, it's detected from model name:
+| Key | Effect |
+|-----|--------|
+| `model` | Sets the LLM model |
+| `temperature` | Sets randomness |
+| `top_p` | Sets nucleus sampling |
+| `top_k` | Sets top-k sampling |
+| `max_tokens` | Sets max response tokens |
+| `presence_penalty` | Sets presence penalty |
+| `frequency_penalty` | Sets frequency penalty |
+| `stop` | Sets stop sequences |
 
-| Model Pattern | Provider |
-|--------------|----------|
-| `claude-*`, `anthropic-*` | `:anthropic` |
-| `gpt-*`, `o1-*`, `chatgpt-*` | `:openai` |
-| `gemini-*` | `:gemini` |
-| `llama-*`, `mistral-*` | `:ollama` |
+## Model Selection
 
-## RoboticModel
+The model is determined by:
 
-The `RoboticModel` class handles LLM communication:
+1. Robot's explicit `model:` parameter
+2. Front matter `model` from template
+3. Global `RobotLab.config.ruby_llm.model`
 
 ```ruby
-model = RoboticModel.new("claude-sonnet-4", provider: :anthropic)
-
-# Full inference
-response = model.infer(messages, tools)
+robot = RobotLab.build(
+  name: "bot",
+  model: "claude-sonnet-4"  # Takes precedence
+)
 
-# Quick ask
-response = model.ask("What is 2+2?", system: "You are a math tutor")
+# Or configure globally via config files / environment variables
+# ROBOT_LAB_RUBY_LLM__MODEL=gpt-4o
 ```
 
-### InferenceResponse
+## SimpleFlow Integration
 
-The response object provides:
+When a robot runs inside a network, the `call` method is invoked by SimpleFlow:
+
+```mermaid
+sequenceDiagram
+    participant SF as SimpleFlow
+    participant Task as Task Wrapper
+    participant Robot
+    participant Chat as @chat
+
+    SF->>Task: call(result)
+    Task->>Task: deep_merge(run_params, task_context)
+    Task->>Robot: call(enhanced_result)
+    Robot->>Robot: extract_run_context(result)
+    Robot->>Robot: message = context.delete(:message)
+    Robot->>Robot: run(message, **context)
+    Robot->>Chat: ask(message)
+    Chat-->>Robot: response
+    Robot-->>SF: result.continue(robot_result)
+```
+
+The `Task` wrapper deep-merges per-task configuration (context, mcp, tools) before delegating to the robot's `call`. The base `Robot#call` extracts the message and calls `run`:
 
 ```ruby
-response.output              # Array<Message> - parsed output
-response.raw                 # Original LLM response
-response.stop_reason         # "stop", "tool", etc.
-response.stopped?            # true if naturally completed
-response.wants_tools?        # true if tool calls pending
-response.tool_calls          # Array<ToolMessage>
-response.text_content        # Combined text from output
-response.captured_tool_results  # Auto-executed tool results
+def call(result)
+  run_context = extract_run_context(result)
+  message = run_context.delete(:message)
+  robot_result = run(message, **run_context)
+
+  result
+    .with_context(@name.to_sym, robot_result)
+    .continue(robot_result)
+end
 ```
 
 ## Next Steps
 
 - [Network Orchestration](network-orchestration.md) - Multi-robot coordination
-- [State Management](state-management.md) - Managing state across robots
+- [Core Concepts](core-concepts.md) - Fundamental building blocks
 - [Using Tools](../guides/using-tools.md) - Creating and using tools