robot_lab 0.0.1

data/docs/architecture/network-orchestration.md

@@ -0,0 +1,216 @@
+# Network Orchestration
+
+Networks coordinate multiple robots using [SimpleFlow](https://github.com/MadBomber/simple_flow) pipelines for DAG-based execution.
+
+## Network Structure
+
+A network is a thin wrapper around `SimpleFlow::Pipeline`:
+
+- **Pipeline**: DAG-based execution engine
+- **Robots**: Named collection of task handlers
+- **Tasks**: Define dependencies and execution order
+
+```ruby
+network = RobotLab.create_network(name: "customer_service") do
+  task :classifier, classifier_robot, depends_on: :none
+  task :billing, billing_robot, depends_on: :optional
+  task :technical, technical_robot, depends_on: :optional
+end
+```
+
+## Task Configuration
+
+Tasks can have per-task configuration that's deep-merged with network run params:
+
+```ruby
+network = RobotLab.create_network(name: "support") do
+  task :classifier, classifier_robot, depends_on: :none
+  task :billing, billing_robot,
+       context: { department: "billing", escalation_level: 2 },
+       tools: [RefundTool],
+       depends_on: :optional
+  task :technical, technical_robot,
+       context: { department: "technical" },
+       mcp: [FilesystemServer],
+       depends_on: :optional
+end
+```
+
+## Execution Model
+
+```mermaid
+stateDiagram-v2
+    [*] --> Start
+    Start --> ExecuteTask: next ready task
+    ExecuteTask --> CheckDependents: task complete
+    CheckDependents --> ExecuteTask: more tasks ready
+    CheckDependents --> Complete: all tasks done
+    ExecuteTask --> Halted: task halts
+    Complete --> [*]
+    Halted --> [*]
+```
+
+### Task Dependency Types
+
+| Type | Description |
+|------|-------------|
+| `:none` | No dependencies, runs first |
+| `[:task1, :task2]` | Waits for listed tasks |
+| `:optional` | Only runs when activated |
+
+## Robot#call Interface
+
+Each robot implements the SimpleFlow step interface:
+
+```ruby
+class Robot
+  def call(result)
+    # Run the LLM
+    robot_result = run(**extract_run_context(result))
+
+    # Return new result with context
+    result
+      .with_context(@name.to_sym, robot_result)
+      .continue(robot_result)
+  end
+end
+```
+
+### Result Methods
+
+| Method | Description |
+|--------|-------------|
+| `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 |
+
+## SimpleFlow::Result
+
+The result object flows through the pipeline:
+
+```ruby
+result.value      # Current task's output
+result.context    # Accumulated context from all tasks
+result.halted?    # Whether execution stopped early
+result.continued? # Whether execution continues
+```
+
+### Context Structure
+
+```ruby
+{
+  run_params: { message: "...", customer_id: 123 },
+  classifier: RobotResult,
+  billing: RobotResult,
+  # ... other task results
+}
+```
+
+## Optional Task Activation
+
+Optional tasks don't run automatically. They must be activated:
+
+```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)
+
+    # Analyze output and activate appropriate task
+    category = robot_result.last_text_content.to_s.downcase
+
+    case category
+    when /billing/
+      new_result.activate(:billing)
+    when /technical/
+      new_result.activate(:technical)
+    else
+      new_result.activate(:general)
+    end
+  end
+end
+```
+
+## Parallel Execution
+
+Tasks with the same dependencies can run in parallel:
+
+```ruby
+network = RobotLab.create_network(name: "analysis", concurrency: :threads) do
+  task :fetch, fetcher, depends_on: :none
+
+  # These three run in parallel
+  task :sentiment, sentiment_bot, depends_on: [:fetch]
+  task :entities, entity_bot, depends_on: [:fetch]
+  task :keywords, keyword_bot, depends_on: [:fetch]
+
+  # Waits for all three
+  task :merge, merger, depends_on: [:sentiment, :entities, :keywords]
+end
+```
+
+### Concurrency Modes
+
+| Mode | Description |
+|------|-------------|
+| `:auto` | SimpleFlow chooses best mode |
+| `:threads` | Use Ruby threads |
+| `:async` | Use async/fiber |
+
+## Data Flow
+
+1. **Initial Value**: `network.run(**params)` creates initial result
+2. **Run Params**: Stored in `result.context[:run_params]`
+3. **Task Results**: Each task adds to context
+4. **Final Value**: Last task's output becomes `result.value`
+
+```ruby
+# Run with context
+result = network.run(
+  message: "Help with billing",
+  customer_id: 123
+)
+
+# Access the flow
+result.context[:run_params]  # { message: "...", customer_id: 123 }
+result.context[:classifier]  # First robot's RobotResult
+result.context[:billing]     # Billing robot's RobotResult
+result.value                 # Final RobotResult
+```
+
+## Visualization
+
+Networks provide visualization methods:
+
+```ruby
+# ASCII representation
+puts network.visualize
+
+# Mermaid diagram
+puts network.to_mermaid
+
+# Execution plan description
+puts network.execution_plan
+```
+
+## Network Configuration
+
+```ruby
+network = RobotLab.create_network(
+  name: "support",
+  concurrency: :threads  # :auto, :threads, or :async
+) do
+  task :classifier, classifier, depends_on: :none
+  task :handler, handler, depends_on: [:classifier]
+end
+```
+
+## Next Steps
+
+- [Creating Networks](../guides/creating-networks.md) - Practical patterns
+- [Robot Execution](robot-execution.md) - How robots process messages
+- [API Reference: Network](../api/core/network.md) - Complete API

data/docs/architecture/robot-execution.md

@@ -0,0 +1,243 @@
+# Robot Execution
+
+This page details how a robot processes messages and generates responses.
+
+## Execution Overview
+
+When you call `robot.run(state:, network:)`, several steps occur:
+
+```mermaid
+sequenceDiagram
+    participant App as Application
+    participant Robot
+    participant Model as RoboticModel
+    participant Adapter
+    participant LLM
+
+    App->>Robot: run(state, network)
+    Robot->>Robot: resolve_tools()
+    Robot->>Model: infer(messages, tools)
+    Model->>Adapter: format_messages()
+    Model->>LLM: API Request
+
+    loop Tool Calls
+        LLM-->>Model: tool_call response
+        Model->>Robot: execute_tool()
+        Robot->>Model: tool_result
+        Model->>LLM: continue
+    end
+
+    LLM-->>Model: final response
+    Model->>Adapter: parse_response()
+    Model-->>Robot: InferenceResponse
+    Robot-->>App: RobotResult
+```
+
+## Step-by-Step Flow
+
+### 1. Tool Resolution
+
+Before making any LLM call, the robot resolves available tools:
+
+```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
+```
+
+### 2. Message Preparation
+
+The robot prepares messages from state:
+
+```ruby
+messages = []
+messages << system_message     # From template
+messages += state.messages     # Conversation history
+messages << user_message       # Current input
+```
+
+### 3. LLM Inference
+
+Messages are sent to the LLM via `RoboticModel`:
+
+```ruby
+response = model.infer(
+  messages,
+  tools,
+  tool_choice: "auto",
+  streaming: streaming_callback
+)
+```
+
+### 4. Tool Execution Loop
+
+If the LLM requests tool calls:
+
+```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
+```
+
+### 5. Result Construction
+
+Finally, a `RobotResult` is created:
+
+```ruby
+RobotResult.new(
+  robot_name: name,
+  output: response.output,
+  tool_calls: executed_tools,
+  stop_reason: response.stop_reason
+)
+```
+
+## Tool Execution
+
+### Tool Call Processing
+
+When the LLM requests a tool:
+
+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
+
+### Execution Context
+
+Tools receive context about their execution environment:
+
+```ruby
+tool.handler.call(
+  **tool_call.input,  # User-provided arguments
+  robot: self,        # The executing robot
+  network: network,   # Network context
+  state: state        # Current state
+)
+```
+
+### Error Handling
+
+Tool errors are captured and returned to the LLM:
+
+```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 })
+end
+```
+
+## Iteration Limits
+
+Robot execution has safeguards:
+
+| Limit | Default | Purpose |
+|-------|---------|---------|
+| `max_tool_iterations` | 10 | Max tool calls per robot run |
+
+When limits are reached, execution stops with the current state.
+
+## Streaming
+
+Robots support streaming responses:
+
+```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
+  }
+)
+```
+
+### Streaming Events
+
+| 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 |
+
+## Model Selection
+
+The model is determined by:
+
+1. Robot's explicit `model` setting
+2. Network's `default_model`
+3. Global `RobotLab.configuration.default_model`
+
+```ruby
+robot = RobotLab.build do
+  model "claude-sonnet-4"  # Takes precedence
+end
+
+network = RobotLab.create_network do
+  default_model "gpt-4"    # Fallback for robots without model
+end
+```
+
+## Provider Detection
+
+If no provider is specified, it's detected from model name:
+
+| Model Pattern | Provider |
+|--------------|----------|
+| `claude-*`, `anthropic-*` | `:anthropic` |
+| `gpt-*`, `o1-*`, `chatgpt-*` | `:openai` |
+| `gemini-*` | `:gemini` |
+| `llama-*`, `mistral-*` | `:ollama` |
+
+## RoboticModel
+
+The `RoboticModel` class handles LLM communication:
+
+```ruby
+model = RoboticModel.new("claude-sonnet-4", provider: :anthropic)
+
+# Full inference
+response = model.infer(messages, tools)
+
+# Quick ask
+response = model.ask("What is 2+2?", system: "You are a math tutor")
+```
+
+### InferenceResponse
+
+The response object provides:
+
+```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
+```
+
+## Next Steps
+
+- [Network Orchestration](network-orchestration.md) - Multi-robot coordination
+- [State Management](state-management.md) - Managing state across robots
+- [Using Tools](../guides/using-tools.md) - Creating and using tools