robot_lab 0.0.1 → 0.0.4

data/docs/guides/building-robots.md

@@ -4,24 +4,26 @@ This guide covers everything you need to know about creating robots in RobotLab.
 
 ## Basic Robot
 
-Create a simple robot with the builder DSL:
+Create a robot using the `RobotLab.build` factory method with keyword arguments:
 
 ```ruby
-robot = RobotLab.build do
-  name "assistant"
-  description "A helpful AI assistant"
-  template "You are a helpful assistant."
-end
+robot = RobotLab.build(
+  name: "assistant",
+  system_prompt: "You are a helpful assistant."
+)
+
+result = robot.run("Hello!")
+puts result.last_text_content
 ```
 
 ## Robot Properties
 
 ### Name
 
-A unique identifier used for routing and logging:
+A unique identifier used for routing and logging. If omitted, an auto-generated name is used:
 
 ```ruby
-name "support_agent"
+robot = RobotLab.build(name: "support_agent", system_prompt: "...")
 ```
 
 ### Description
@@ -29,348 +31,551 @@ name "support_agent"
 Describes what the robot does (useful for routing decisions):
 
 ```ruby
-description "Handles customer support inquiries about orders and refunds"
+robot = RobotLab.build(
+  name: "support_agent",
+  description: "Handles customer support inquiries about orders and refunds",
+  system_prompt: "..."
+)
 ```
 
 ### Model
 
-The LLM model to use:
+The LLM model to use. Defaults to the value in `RobotLab.config.ruby_llm.model`:
 
 ```ruby
-model "claude-sonnet-4"      # Anthropic
-model "gpt-4o"               # OpenAI
-model "gemini-1.5-pro"       # Google
+robot = RobotLab.build(
+  name: "writer",
+  model: "claude-sonnet-4",
+  system_prompt: "You are a creative writer."
+)
 ```
 
-### Template (System Prompt)
+### System Prompt
 
-Instructions that define the robot's personality and behavior:
+An inline string that defines the robot's personality and behavior:
 
 ```ruby
-template <<~PROMPT
-  You are a customer support specialist for TechCo.
+robot = RobotLab.build(
+  name: "support",
+  system_prompt: <<~PROMPT
+    You are a customer support specialist for TechCo.
 
-  Your responsibilities:
-  - Answer questions about products and services
-  - Help resolve order issues
-  - Provide friendly, professional assistance
+    Your responsibilities:
+    - Answer questions about products and services
+    - Help resolve order issues
+    - Provide friendly, professional assistance
 
-  Always be polite and acknowledge the customer's concerns.
-PROMPT
+    Always be polite and acknowledge the customer's concerns.
+  PROMPT
+)
 ```
 
-## Adding Tools
+## Template Files
 
-Give robots capabilities with tools:
+Templates are `.md` files managed by [prompt_manager](https://github.com/MadBomber/prompt_manager). Reference a template by symbol; RobotLab resolves it through the configured template path.
 
 ```ruby
-robot = RobotLab.build do
-  name "order_assistant"
-
-  tool :lookup_order do
-    description "Look up order details by order ID"
-    parameter :order_id, type: :string, required: true, description: "The order ID"
-    handler do |order_id:, **_context|
-      Order.find_by(id: order_id)&.to_h || { error: "Order not found" }
-    end
-  end
+# Reference template by symbol (loads prompts/support.md)
+robot = RobotLab.build(
+  name: "support",
+  template: :support,
+  context: { company: "TechCo", tone: "friendly" }
+)
+```
 
-  tool :check_inventory do
-    description "Check product inventory"
-    parameter :product_id, type: :string, required: true
-    parameter :warehouse, type: :string, default: "main"
-    handler do |product_id:, warehouse:, **_context|
-      Inventory.check(product_id, warehouse: warehouse)
-    end
-  end
-end
+### Template Format
+
+Templates use `.md` files with YAML front matter:
+
+```markdown title="prompts/support.md"
+---
+description: Customer support assistant
+parameters:
+  company: "Acme"
+  tone: "professional"
+model: claude-sonnet-4
+temperature: 0.7
+---
+You are a support agent for <%= company %>.
+Your tone should be <%= tone %>.
 ```
 
-### Tool Parameters
+### Front Matter Configuration
+
+The following YAML front matter keys are applied to the robot's chat automatically:
+
+**LLM Configuration:**
+
+| Key | Description |
+|-----|-------------|
+| `model` | Override the LLM model |
+| `temperature` | Controls randomness (0.0 - 1.0) |
+| `top_p` | Nucleus sampling threshold |
+| `top_k` | Top-k sampling |
+| `max_tokens` | Maximum tokens in response |
+| `presence_penalty` | Penalize based on presence |
+| `frequency_penalty` | Penalize based on frequency |
+| `stop` | Stop sequences |
+
+**Robot Identity and Capabilities:**
+
+| Key | Description |
+|-----|-------------|
+| `robot_name` | Override the robot's name (when constructor uses the default) |
+| `description` | Human-readable description of the robot |
+| `tools` | Array of tool class names (resolved via `Object.const_get`) |
+| `mcp` | Array of MCP server configurations |
+
+Constructor-provided values always take precedence over frontmatter values.
+
+### Self-Contained Templates
+
+Templates can declare everything a robot needs — identity, tools, MCP servers, and LLM config — making the `.md` file a complete robot definition:
+
+```markdown title="prompts/github_assistant.md"
+---
+description: GitHub assistant with MCP tool access
+robot_name: github_bot
+mcp:
+  - name: github
+    transport: stdio
+    command: npx
+    args: ["-y", "@modelcontextprotocol/server-github"]
+model: claude-sonnet-4
+temperature: 0.3
+---
+You are a helpful GitHub assistant with access to GitHub tools via MCP.
+Use the available tools to help answer questions about GitHub repositories.
+```
 
-Define parameters with types and descriptions:
+Build the robot with minimal constructor arguments:
 
 ```ruby
-tool :search do
-  parameter :query, type: :string, required: true, description: "Search query"
-  parameter :limit, type: :integer, default: 10, description: "Max results"
-  parameter :category, type: :string, enum: %w[books movies music]
-end
+# Template provides name, description, MCP config, model, and temperature
+robot = RobotLab.build(template: :github_assistant)
 ```
 
-| Option | Description |
-|--------|-------------|
-| `type` | Parameter type (`:string`, `:integer`, `:boolean`, `:number`, `:array`, `:object`) |
-| `required` | Whether the parameter is required |
-| `default` | Default value if not provided |
-| `description` | Description for the LLM |
-| `enum` | List of allowed values |
+### Tools in Front Matter
 
-### Tool Handler Context
+Declare tool classes by name in the `tools:` key. RobotLab resolves each string to a Ruby constant and instantiates it:
 
-Handlers receive execution context:
+```markdown title="prompts/order_support.md"
+---
+description: Order support specialist
+tools:
+  - OrderLookup
+  - RefundProcessor
+---
+You help customers with order inquiries and refunds.
+```
 
 ```ruby
-handler do |param1:, param2:, robot:, network:, state:|
-  # robot   - The Robot instance
-  # network - The NetworkRun
-  # state   - Current State
+# Tools are loaded from frontmatter — no local_tools: needed
+robot = RobotLab.build(template: :order_support)
+```
 
-  # Access state data
-  user_id = state.data[:user_id]
+Tool classes must be defined and loaded before the robot is built. If a tool name cannot be resolved, it is skipped with a warning.
 
-  # Use memory
-  state.memory.remember("last_search", param1)
+Constructor `local_tools:` overrides frontmatter `tools:` when provided:
 
-  # Return result (will be sent to LLM)
-  { success: true, data: result }
-end
+```ruby
+# Constructor tools take precedence over frontmatter tools
+robot = RobotLab.build(
+  template: :order_support,
+  local_tools: [OrderLookup]  # Only OrderLookup, not RefundProcessor
+)
 ```
 
-!!! tip "Ignoring Context"
-    Use `**_context` to accept but ignore context:
-    ```ruby
-    handler { |query:, **_context| search(query) }
-    ```
+### MCP in Front Matter
 
-## Template Files
+Declare MCP server configurations directly in the template:
 
-Load templates from files:
+```markdown title="prompts/developer.md"
+---
+description: Developer assistant with filesystem access
+mcp:
+  - name: filesystem
+    transport: stdio
+    command: mcp-server-filesystem
+    args: ["--root", "/home/user/projects"]
+---
+You are a developer assistant with filesystem access.
+```
 
 ```ruby
-# Configure template path
-RobotLab.configure do |config|
-  config.template_path = "prompts"  # or "app/prompts" in Rails
-end
-
-# Reference template by name
-robot = RobotLab.build do
-  name "support"
-  template "support_agent"  # Loads prompts/support_agent.erb
-end
+robot = RobotLab.build(template: :developer)
 ```
 
-### Template Variables
+Constructor `mcp:` overrides frontmatter `mcp:` when provided.
 
-Pass variables to templates:
+### Template with System Prompt
+
+You can combine a template and an inline system prompt. Both are applied to the chat -- the template first, then the system prompt is appended as additional instructions:
 
 ```ruby
-robot = RobotLab.build do
-  name "support"
-  template "support_agent", company: "TechCo", tone: "friendly"
-end
+robot = RobotLab.build(
+  name: "support",
+  template: :support,
+  context: { company: "TechCo" },
+  system_prompt: "Always respond in Spanish."
+)
 ```
 
-```erb title="prompts/support_agent.erb"
-You are a support agent for <%= company %>.
-Your tone should be <%= tone %>.
+## Adding Tools
+
+Give robots capabilities via the `local_tools:` parameter. Tools can be `RubyLLM::Tool` subclasses or `RobotLab::Tool` instances:
+
+```ruby
+robot = RobotLab.build(
+  name: "order_assistant",
+  system_prompt: "You help customers with orders.",
+  local_tools: [OrderLookup, InventoryCheck]
+)
 ```
 
+See the [Using Tools](using-tools.md) guide for details on defining tools.
+
 ## MCP Configuration
 
-Connect to MCP servers:
+Connect to MCP (Model Context Protocol) servers via the `mcp:` parameter:
 
 ```ruby
-robot = RobotLab.build do
-  name "coder"
-
-  # Use specific MCP servers
-  mcp [
+robot = RobotLab.build(
+  name: "coder",
+  template: :developer,
+  mcp: [
     {
       name: "filesystem",
       transport: { type: "stdio", command: "mcp-server-fs", args: ["--root", "/data"] }
     }
   ]
+)
+```
 
-  # Or inherit from network
-  mcp :inherit
+MCP configuration supports hierarchical resolution:
 
-  # Or disable MCP
-  mcp :none
-end
-```
+| Value | Behavior |
+|-------|----------|
+| `:none` | No MCP servers (default) |
+| `:inherit` | Use parent network/config MCP servers |
+| `[...]` | Explicit array of server configurations |
+
+See the [MCP Integration](mcp-integration.md) guide for transport types and advanced patterns.
 
-## Tool Whitelist
+## Chaining Configuration
 
-Restrict available tools:
+Robots support `with_*` method chaining for runtime reconfiguration. Each method returns `self` for fluent usage:
 
 ```ruby
-robot = RobotLab.build do
-  name "reader"
+robot = RobotLab.build(name: "bot")
 
-  # Only allow specific tools
-  tools %w[read_file list_directory]
+result = robot
+  .with_instructions("Be concise and direct.")
+  .with_temperature(0.9)
+  .with_model("claude-sonnet-4")
+  .run("Summarize quantum computing in one sentence.")
+```
 
-  # Or inherit from network
-  tools :inherit
+### Available Chain Methods
 
-  # Or disable all inherited tools
-  tools :none
-end
-```
+| Method | Description |
+|--------|-------------|
+| `with_model(id)` | Change the LLM model |
+| `with_instructions(text)` | Set system instructions |
+| `with_temperature(val)` | Set temperature |
+| `with_top_p(val)` | Set nucleus sampling |
+| `with_top_k(val)` | Set top-k sampling |
+| `with_max_tokens(val)` | Set max output tokens |
+| `with_presence_penalty(val)` | Set presence penalty |
+| `with_frequency_penalty(val)` | Set frequency penalty |
+| `with_stop(sequences)` | Set stop sequences |
+| `with_tool(tool)` | Add a single tool |
+| `with_tools(*tools)` | Add multiple tools |
+| `with_template(id, **ctx)` | Apply a prompt template |
+| `with_schema(schema)` | Set structured output schema |
+| `with_thinking(config)` | Enable extended thinking |
+| `with_bus(bus)` | Connect to a message bus (creates one if nil) |
 
 ## Running Robots
 
 ### Standalone
 
-Run a robot directly:
+Run a robot directly with a string message:
+
+```ruby
+result = robot.run("Hello!")
+puts result.last_text_content
+```
+
+The `run` method returns a `RobotResult` with:
 
 ```ruby
-state = RobotLab.create_state(message: "Hello!")
-result = robot.run(state: state, network: nil)
+result.last_text_content  # => "Hi there! How can I help?"
+result.output             # => Array of output messages
+result.tool_calls         # => Array of tool call results
+result.robot_name         # => "assistant"
+result.stop_reason        # => stop reason from the LLM
+```
+
+### With Runtime Memory
 
-puts result.output.first.content
+Inject memory values for a single run:
+
+```ruby
+result = robot.run("What's my account status?", memory: { user_id: 123 })
 ```
 
 ### In a Network
 
-Run through a network for full orchestration:
+Run through a network for orchestration:
 
 ```ruby
-network = RobotLab.create_network do
-  add_robot robot
+network = RobotLab.create_network(name: "pipeline") do
+  task :assistant, robot, depends_on: :none
 end
 
-state = RobotLab.create_state(message: "Hello!")
-result = network.run(state: state)
+result = network.run(message: "Hello!")
+puts result.value.last_text_content
 ```
 
 ### With Streaming
 
-Stream responses in real-time:
+Stream responses in real-time by passing a block:
 
 ```ruby
-robot.run(
-  state: state,
-  network: network,
-  streaming: ->(event) {
-    case event[:event]
-    when "delta"
-      print event[:data][:content]
-    when "tool_call"
-      puts "\nCalling tool: #{event[:data][:name]}"
-    end
-  }
-)
+robot.run("Tell me a story") do |event|
+  case event[:event]
+  when "text.delta"
+    print event[:data][:content]
+  when "tool_call"
+    puts "\nCalling tool: #{event[:data][:name]}"
+  end
+end
 ```
 
 ## Robot Patterns
 
 ### Classifier Robot
 
-Route requests to specialized handlers:
+Route requests to specialized handlers. Subclass `RobotLab::Robot` and override `call` for custom pipeline behavior:
 
 ```ruby
-classifier = RobotLab.build do
-  name "classifier"
-  description "Classifies incoming requests"
-
-  template <<~PROMPT
-    Analyze the user's message and classify it into exactly one category:
-    - BILLING: Questions about invoices, payments, subscriptions
-    - TECHNICAL: Technical issues, bugs, how-to questions
-    - GENERAL: General inquiries, feedback, other
+class ClassifierRobot < RobotLab::Robot
+  def call(result)
+    context = extract_run_context(result)
+    message = context.delete(:message)
+    robot_result = run(message, **context)
+
+    new_result = result
+      .with_context(@name.to_sym, robot_result)
+      .continue(robot_result)
+
+    category = robot_result.last_text_content.to_s.strip.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
 
+classifier = ClassifierRobot.new(
+  name: "classifier",
+  system_prompt: <<~PROMPT
+    Classify the user's message into exactly one category:
+    - billing
+    - technical
+    - general
     Respond with only the category name, nothing else.
   PROMPT
-end
+)
 ```
 
 ### Specialist Robot
 
-Handle specific domains:
+Handle specific domains with template and tools:
 
 ```ruby
-billing_specialist = RobotLab.build do
-  name "billing_specialist"
-  description "Handles billing and payment inquiries"
+billing_specialist = RobotLab.build(
+  name: "billing_specialist",
+  description: "Handles billing and payment inquiries",
+  template: :billing,
+  context: { department: "billing" },
+  local_tools: [InvoiceLookup, RefundProcessor]
+)
+```
 
-  template <<~PROMPT
-    You are a billing specialist. You help customers with:
-    - Invoice questions
-    - Payment issues
-    - Subscription management
+### Summarizer Robot
 
-    Always verify the customer's account before making changes.
+Condense information:
+
+```ruby
+summarizer = RobotLab.build(
+  name: "summarizer",
+  description: "Summarizes conversations and documents",
+  system_prompt: <<~PROMPT
+    Create concise summaries of the provided content.
+    Focus on key points and actionable items.
+    Use bullet points for clarity.
   PROMPT
+)
+```
 
-  tool :get_invoices do
-    description "Get customer's recent invoices"
-    parameter :customer_id, type: :string, required: true
-    handler { |customer_id:, **_| Invoice.where(customer_id: customer_id).limit(10) }
+### Bus-Connected Robot
+
+Enable bidirectional communication between robots using a message bus. This pattern supports negotiation loops and convergence:
+
+```ruby
+bus = TypedBus::MessageBus.new
+
+class Comedian < RobotLab::Robot
+  def initialize(bus:)
+    super(name: "bob", template: :comedian, bus: bus)
+    on_message do |message|
+      joke = run(message.content.to_s).last_text_content.strip
+      reply(message, joke)
+    end
+  end
+end
+
+class ComedyCritic < RobotLab::Robot
+  def initialize(bus:)
+    super(name: "alice", template: :comedy_critic, bus: bus)
+    @accepted = false
+    on_message do |message|
+      verdict = run("Evaluate: #{message.content}").last_text_content.strip
+      @accepted = verdict.start_with?("FUNNY")
+      send_message(to: :bob, content: "Try again.") unless @accepted
+    end
   end
+  attr_reader :accepted
 end
+
+bob   = Comedian.new(bus: bus)
+alice = ComedyCritic.new(bus: bus)
+alice.send_message(to: :bob, content: "Tell me a funny robot joke.")
 ```
 
-### Summarizer Robot
+The `on_message` block arity controls delivery handling:
+- **1 argument** `|message|` — auto-acknowledges before calling
+- **2 arguments** `|delivery, message|` — manual `delivery.ack!` / `delivery.nack!`
 
-Condense information:
+See [Message Bus](../architecture/core-concepts.md#message-bus) for details.
+
+### Spawning Robots Dynamically
+
+Create new robots at runtime using `spawn`. The bus is created lazily — no upfront wiring required:
 
 ```ruby
-summarizer = RobotLab.build do
-  name "summarizer"
-  description "Summarizes conversations and documents"
+class Dispatcher < RobotLab::Robot
+  attr_reader :spawned
 
-  template <<~PROMPT
-    Create concise summaries of the provided content.
-    Focus on key points and actionable items.
-    Use bullet points for clarity.
-  PROMPT
+  def initialize(bus: nil)
+    super(name: "dispatcher", template: :dispatcher, bus: bus)
+    @spawned = {}
+
+    on_message do |message|
+      puts "#{message.from} replied: #{message.content.to_s.lines.first&.strip}"
+    end
+  end
+
+  def dispatch(question)
+    # Ask LLM what specialist to create
+    plan = run(question).last_text_content.strip
+    role, instruction = plan.split("\n", 2)
+    role = role.strip.downcase.gsub(/\s+/, "_")
+
+    # Spawn (or reuse) a specialist
+    specialist = @spawned[role] ||= spawn(
+      name: role,
+      system_prompt: instruction&.strip || "You are a helpful #{role}."
+    )
+
+    # Have the specialist answer and reply
+    answer = specialist.run(question).last_text_content.strip
+    specialist.send_message(to: :dispatcher, content: answer)
+  end
 end
 ```
 
-## Best Practices
+Key features of `spawn`:
+
+- Creates a child robot on the same bus as the parent
+- Creates a bus lazily if the parent doesn't have one
+- Spawned robots can immediately send and receive messages
+- Multiple robots with the same name enable fan-out messaging
 
-### 1. Clear, Focused Templates
+Robots can also join a bus after creation:
 
 ```ruby
-# Good: Specific and focused
-template <<~PROMPT
-  You are a code reviewer. Review code for:
-  - Security vulnerabilities
-  - Performance issues
-  - Best practice violations
+bot = RobotLab.build(name: "latecomer", system_prompt: "Hello.")
+bot.with_bus(existing_bus)  # now connected and can send/receive messages
+```
 
-  Provide specific line numbers and suggestions.
-PROMPT
+## Configuration
 
-# Bad: Vague and unfocused
-template "You help with code stuff."
+RobotLab uses `MywayConfig` for configuration. Access the config object directly -- there is no `RobotLab.configure` block:
+
+```ruby
+RobotLab.config.ruby_llm.model           # => "claude-sonnet-4"
+RobotLab.config.ruby_llm.request_timeout  # => 120
 ```
 
-### 2. Descriptive Tool Definitions
+Configuration is loaded from:
+
+- Bundled defaults (`lib/robot_lab/config/defaults.yml`)
+- Environment-specific overrides (development, test, production)
+- XDG config files (`~/.config/robot_lab/config.yml`)
+- Project config (`./config/robot_lab.yml`)
+- Environment variables (`ROBOT_LAB_*` prefix)
+
+## Best Practices
+
+### 1. Clear, Focused Prompts
 
 ```ruby
-# Good: Clear description and parameter docs
-tool :search_users do
-  description "Search for users by email, name, or ID. Returns up to 10 matches."
-  parameter :query, type: :string, required: true,
-            description: "Email address, partial name, or user ID"
-end
+# Good: Specific and focused
+robot = RobotLab.build(
+  name: "reviewer",
+  system_prompt: <<~PROMPT
+    You are a code reviewer. Review code for:
+    - Security vulnerabilities
+    - Performance issues
+    - Best practice violations
+
+    Provide specific line numbers and suggestions.
+  PROMPT
+)
 
-# Bad: Missing context
-tool :search do
-  parameter :q, type: :string
-end
+# Bad: Vague and unfocused
+robot = RobotLab.build(
+  name: "reviewer",
+  system_prompt: "You help with code stuff."
+)
 ```
 
-### 3. Handle Tool Errors Gracefully
+### 2. Use Templates for Reusable Prompts
+
+Templates keep prompts in version-controlled files and allow parameterization:
 
 ```ruby
-handler do |user_id:, **_|
-  user = User.find_by(id: user_id)
-  if user
-    { success: true, user: user.to_h }
-  else
-    { success: false, error: "User not found", user_id: user_id }
-  end
-rescue ActiveRecord::ConnectionError => e
-  { success: false, error: "Database unavailable", retry: true }
-end
+robot = RobotLab.build(
+  name: "support",
+  template: :support,
+  context: { company: "TechCo", language: "English" }
+)
 ```
 
+### 3. Handle Tool Errors Gracefully
+
+See [Using Tools: Error Handling](using-tools.md#error-handling) for patterns.
+
 ## Next Steps
 
 - [Creating Networks](creating-networks.md) - Orchestrate multiple robots
+- [Message Bus](../architecture/core-concepts.md#message-bus) - Bidirectional robot communication
+- [Dynamic Spawning](../architecture/core-concepts.md#dynamic-spawning) - Robots creating robots at runtime
 - [Using Tools](using-tools.md) - Advanced tool patterns
+- [Memory Guide](memory.md) - Share data between runs and robots
 - [API Reference: Robot](../api/core/robot.md) - Complete API documentation