robot_lab 0.0.1 → 0.0.4

data/docs/guides/using-tools.md

@@ -1,256 +1,228 @@
 # Using Tools
 
-Tools give robots the ability to interact with external systems.
+Tools give robots the ability to interact with external systems. RobotLab supports three approaches: `RubyLLM::Tool` subclasses, `RobotLab::Tool` subclasses (with robot access), and `RobotLab::Tool.create` for dynamic tools.
 
 ## Defining Tools
 
-### In Robot Builder
+### RubyLLM::Tool Subclass
+
+For reusable tools that don't need robot access:
 
 ```ruby
-robot = RobotLab.build do
-  name "assistant"
+class GetWeather < RubyLLM::Tool
+  description "Get current weather for a location"
+
+  param :location, type: :string, desc: "City name or zip code"
+  param :unit, type: :string, desc: "Temperature unit", required: false
 
-  tool :get_weather do
-    description "Get current weather for a location"
-    parameter :location, type: :string, required: true
-    handler { |location:, **_| WeatherService.current(location) }
+  def execute(location:, unit: "celsius")
+    WeatherService.current(location, unit: unit)
   end
 end
 ```
 
-### Standalone Tool
+### RobotLab::Tool Subclass
 
-```ruby
-weather_tool = RobotLab::Tool.new(
-  name: "get_weather",
-  description: "Get current weather for a location",
-  parameters: {
-    location: {
-      type: "string",
-      description: "City name",
-      required: true
-    }
-  },
-  handler: ->(location:, **_context) {
-    WeatherService.current(location)
-  }
-)
-```
+For tools that need access to their owning robot (self-modification, spawning, etc.):
 
-## Parameter Types
+```ruby
+class AdjustEnergy < RobotLab::Tool
+  description "Adjust the robot's creativity level"
 
-### String
+  param :level, type: "number", desc: "Temperature from 0.0 to 1.0"
 
-```ruby
-parameter :name, type: :string, required: true
+  def execute(level:)
+    robot.with_temperature(level)
+    "Temperature adjusted to #{level}"
+  end
+end
 ```
 
-### Integer
+Pass `robot: self` when constructing:
 
 ```ruby
-parameter :count, type: :integer, default: 10
+class MyRobot < RobotLab::Robot
+  def initialize
+    super(
+      name: "creative_bot",
+      system_prompt: "You are creative.",
+      local_tools: [AdjustEnergy.new(robot: self)]
+    )
+  end
+end
 ```
 
-### Number (Float)
+### RobotLab::Tool.create (Dynamic Tools)
+
+For quick, inline tools use the `Tool.create` factory:
 
 ```ruby
-parameter :price, type: :number
+get_time = RobotLab::Tool.create(
+  name: "get_time",
+  description: "Get the current time"
+) { |_args| Time.now.to_s }
 ```
 
-### Boolean
+With parameters:
 
 ```ruby
-parameter :active, type: :boolean, default: true
+weather_tool = RobotLab::Tool.create(
+  name: "get_weather",
+  description: "Get current weather for a location",
+  parameters: {
+    type: "object",
+    properties: {
+      location: { type: "string", description: "City name" }
+    },
+    required: ["location"]
+  }
+) { |args| WeatherService.current(args[:location]) }
 ```
 
-### Array
+## Built-in Tools
 
-```ruby
-parameter :tags, type: :array
-```
+### AskUser
 
-### Enum
+`RobotLab::AskUser` lets a robot ask the user a question via the terminal. The LLM decides when it needs human input and calls the tool with a question, optional choices, and an optional default.
 
 ```ruby
-parameter :status, type: :string, enum: %w[pending active completed]
+robot = RobotLab.build(
+  name: "onboarding",
+  system_prompt: "Walk the user through project setup. Ask questions to understand their needs.",
+  local_tools: [RobotLab::AskUser]
+)
+robot.run("Help the user set up a new project")
 ```
 
-### With Description
+The tool displays the robot's name and question, then waits for terminal input:
 
-```ruby
-parameter :query,
-          type: :string,
-          required: true,
-          description: "Search query (supports wildcards)"
+```
+[onboarding] What programming language will you use?
+  1. Ruby
+  2. Python
+  3. Go
+>
 ```
 
-## Handler Patterns
-
-### Simple Handler
+Features:
 
-```ruby
-handler { |param:, **_| do_something(param) }
-```
+- **Open-ended**: just a question, free-text response
+- **Multiple choice**: numbered options, user types the number or text
+- **Default value**: shown in the prompt, used when user presses Enter
 
-### With Context Access
+IO is sourced from `robot.input` / `robot.output` (defaulting to `$stdin` / `$stdout`), making it easy to test with `StringIO`:
 
 ```ruby
-handler do |param:, robot:, network:, state:|
-  user_id = state.data[:user_id]
-  result = perform_action(param, user_id)
-  state.memory.remember("last_action", result[:id])
-  result
-end
+robot.input  = StringIO.new("2\n")
+robot.output = StringIO.new
 ```
 
-### Error Handling
+See the [AskUser API reference](../api/core/tool.md#built-in-askuser) for full details.
 
-```ruby
-handler do |id:, **_|
-  record = Record.find_by(id: id)
-  if record
-    { success: true, data: record.to_h }
-  else
-    { success: false, error: "Record not found" }
-  end
-rescue StandardError => e
-  { success: false, error: e.message }
-end
-```
+## Attaching Tools to Robots
 
-### Async Operations
+### Via Constructor
+
+Pass tools via the `local_tools:` parameter when building a robot:
 
 ```ruby
-handler do |url:, **_|
-  # Long-running operation
-  response = HTTP.timeout(30).get(url)
-  { status: response.status, body: response.body.to_s[0..1000] }
-end
+robot = RobotLab.build(
+  name: "assistant",
+  system_prompt: "You are a helpful assistant with tool access.",
+  local_tools: [GetWeather, CalculatorTool]
+)
 ```
 
-## Tool Return Values
+### Via Template Front Matter
 
-### Structured Data
+Declare tool class names in the template's YAML front matter. RobotLab resolves each string to a Ruby constant via `Object.const_get` and instantiates it:
 
-```ruby
-handler do |user_id:, **_|
-  user = User.find(user_id)
-  {
-    id: user.id,
-    name: user.name,
-    email: user.email,
-    created_at: user.created_at.iso8601
-  }
-end
+```markdown title="prompts/weather_bot.md"
+---
+description: Weather assistant with forecast tools
+tools:
+  - GetWeather
+  - GetForecast
+---
+You are a weather assistant. Use your tools to look up weather information.
 ```
 
-### Simple Values
-
 ```ruby
-handler { |**_| Time.now.to_s }
-handler { |**_| 42 }
-handler { |**_| true }
+# Tools are resolved from frontmatter — no local_tools: needed
+robot = RobotLab.build(template: :weather_bot)
 ```
 
-### Lists
+Tool classes must be defined and loaded before building the robot. Unresolvable names are skipped with a warning. Constructor `local_tools:` overrides frontmatter `tools:` when provided.
+
+### Via Chaining
+
+You can also add tools dynamically with chaining:
 
 ```ruby
-handler do |query:, **_|
-  results = Search.query(query)
-  results.map { |r| { id: r.id, title: r.title, score: r.score } }
-end
+robot = RobotLab.build(name: "assistant", system_prompt: "...")
+robot.with_tools(GetWeather, CalculatorTool)
 ```
 
-## Tool Manifests
+## Parameter Types
 
-Wrap existing tools with modified metadata:
+Define parameters on `RubyLLM::Tool` subclasses using `param`:
+
+### String
 
 ```ruby
-# Original tool
-base_tool = RobotLab::Tool.new(
-  name: "search",
-  description: "General search",
-  handler: ->(q:, **_) { Search.query(q) }
-)
+param :name, type: :string, desc: "User's full name"
+```
 
-# Customized version
-product_search = RobotLab::ToolManifest.new(
-  tool: base_tool,
-  name: "search_products",
-  description: "Search the product catalog"
-)
+### Integer
 
-code_search = RobotLab::ToolManifest.new(
-  tool: base_tool,
-  name: "search_code",
-  description: "Search source code"
-)
+```ruby
+param :count, type: :integer, desc: "Number of results"
 ```
 
-## Tool Whitelisting
-
-### At Robot Level
+### Number (Float)
 
 ```ruby
-robot = RobotLab.build do
-  tools %w[read_file list_directory]  # Only these tools
-  tools :inherit                       # Use network's tools
-  tools :none                          # No inherited tools
-end
+param :price, type: :number, desc: "Price in dollars"
 ```
 
-### At Network Level
+### Boolean
 
 ```ruby
-network = RobotLab.create_network do
-  tools %w[search create_issue]  # Global whitelist
-end
+param :active, type: :boolean, desc: "Whether the user is active"
 ```
 
-### Configuration Hierarchy
+### Array
 
+```ruby
+param :tags, type: :array, desc: "List of tags"
 ```
-Global (RobotLab.configure)
-  └── Network (tools: [...])
-        └── Robot (tools: :inherit | :none | [...])
-```
-
-## MCP Tools
 
-Use tools from MCP servers:
+### Enum
 
 ```ruby
-network = RobotLab.create_network do
-  mcp [
-    {
-      name: "github",
-      transport: { type: "stdio", command: "mcp-server-github" }
-    }
-  ]
-
-  # MCP tools automatically available
-  # e.g., search_repositories, create_issue, etc.
-end
+param :status, type: :string, desc: "Order status", enum: %w[pending active completed]
 ```
 
-### Filtering MCP Tools
+### Required vs Optional
+
+Parameters are required by default. Mark optional with `required: false`:
 
 ```ruby
-robot = RobotLab.build do
-  mcp :inherit  # Use network's MCP servers
-  tools %w[search_repositories create_issue]  # Only these MCP tools
-end
+param :query, type: :string, desc: "Search query"                    # required
+param :limit, type: :integer, desc: "Max results", required: false   # optional
 ```
 
-## Common Tool Patterns
+## Tool Patterns
 
 ### Database Lookup
 
 ```ruby
-tool :find_user do
+class FindUser < RubyLLM::Tool
   description "Find user by email or ID"
-  parameter :identifier, type: :string, required: true
-  handler do |identifier:, **_|
+
+  param :identifier, type: :string, desc: "Email address or user ID"
+
+  def execute(identifier:)
     user = User.find_by(id: identifier) || User.find_by(email: identifier)
     user ? user.to_h : { error: "User not found" }
   end
@@ -260,10 +232,12 @@ end
 ### API Integration
 
 ```ruby
-tool :get_stock_price do
-  description "Get current stock price"
-  parameter :symbol, type: :string, required: true
-  handler do |symbol:, **_|
+class GetStockPrice < RubyLLM::Tool
+  description "Get current stock price for a ticker symbol"
+
+  param :symbol, type: :string, desc: "Stock ticker symbol (e.g. AAPL)"
+
+  def execute(symbol:)
     response = HTTP.get("https://api.stocks.example/quote/#{symbol}")
     JSON.parse(response.body)
   rescue HTTP::Error => e
@@ -275,10 +249,12 @@ end
 ### File Operations
 
 ```ruby
-tool :read_file do
+class ReadFile < RubyLLM::Tool
   description "Read contents of a file"
-  parameter :path, type: :string, required: true
-  handler do |path:, **_|
+
+  param :path, type: :string, desc: "Absolute path to the file"
+
+  def execute(path:)
     if File.exist?(path) && File.readable?(path)
       { content: File.read(path), size: File.size(path) }
     else
@@ -288,94 +264,159 @@ tool :read_file do
 end
 ```
 
-### State Modification
+### Multi-Step Operations
 
 ```ruby
-tool :update_preference do
-  description "Update user preference"
-  parameter :key, type: :string, required: true
-  parameter :value, type: :string, required: true
-  handler do |key:, value:, state:, **_|
-    state.memory.remember("pref:#{key}", value)
-    { success: true, key: key, value: value }
-  end
-end
-```
+class ProcessOrder < RubyLLM::Tool
+  description "Validate and process a customer order"
 
-### Multi-Step Operations
+  param :order_id, type: :string, desc: "The order ID to process"
 
-```ruby
-tool :process_order do
-  description "Process a customer order"
-  parameter :order_id, type: :string, required: true
-  handler do |order_id:, state:, **_|
+  def execute(order_id:)
     order = Order.find(order_id)
 
     # Validate
     return { error: "Invalid order" } unless order.valid?
 
-    # Process
+    # Process payment
     result = PaymentProcessor.charge(order)
     return { error: result[:error] } unless result[:success]
 
-    # Update
+    # Update status
     order.update!(status: "paid")
 
-    # Store for later reference
-    state.memory.remember("processed_order", order.id)
-
     { success: true, order_id: order.id, amount: order.total }
   end
 end
 ```
 
+## Tool Return Values
+
+### Structured Data
+
+Return hashes with consistent structure:
+
+```ruby
+def execute(user_id:)
+  user = User.find(user_id)
+  {
+    id: user.id,
+    name: user.name,
+    email: user.email,
+    created_at: user.created_at.iso8601
+  }
+end
+```
+
+### Simple Values
+
+```ruby
+def execute(**_)
+  Time.now.to_s
+end
+```
+
+### Lists
+
+```ruby
+def execute(query:)
+  results = Search.query(query)
+  results.map { |r| { id: r.id, title: r.title, score: r.score } }
+end
+```
+
+## Error Handling
+
+Always handle errors gracefully. Return structured error information so the LLM can decide how to proceed:
+
+```ruby
+class FetchResource < RubyLLM::Tool
+  description "Fetch a resource from an external API"
+
+  param :id, type: :string, desc: "Resource ID"
+
+  def execute(id:)
+    result = ExternalAPI.fetch(id)
+    { success: true, data: result }
+  rescue ExternalAPI::NotFound
+    { success: false, error: "Resource not found", id: id }
+  rescue ExternalAPI::RateLimited => e
+    { success: false, error: "Rate limited", retry_after: e.retry_after }
+  rescue StandardError => e
+    { success: false, error: "Unexpected error: #{e.message}" }
+  end
+end
+```
+
+## Tool Callbacks
+
+Robots support `on_tool_call` and `on_tool_result` callbacks for monitoring tool usage:
+
+```ruby
+robot = RobotLab.build(
+  name: "assistant",
+  system_prompt: "...",
+  local_tools: [GetWeather],
+  on_tool_call: ->(call) { puts "Calling: #{call}" },
+  on_tool_result: ->(result) { puts "Result: #{result}" }
+)
+```
+
+## RobotLab::Tool.create with Schema
+
+For dynamic tools via `Tool.create`, pass parameters as a JSON Schema hash:
+
+```ruby
+tool = RobotLab::Tool.create(
+  name: "search",
+  description: "Search for items",
+  parameters: {
+    type: "object",
+    properties: {
+      query: { type: "string", description: "Search query" },
+      limit: { type: "integer", description: "Max results" }
+    },
+    required: ["query"]
+  }
+) { |args| Search.query(args[:query], limit: args[:limit] || 10) }
+```
+
 ## Best Practices
 
 ### 1. Clear Descriptions
 
+Write descriptions that help the LLM understand when and how to use the tool:
+
 ```ruby
 # Good: Specific and actionable
-tool :search_orders do
-  description "Search customer orders by date range, status, or customer email. Returns up to 50 matching orders."
+class SearchOrders < RubyLLM::Tool
+  description "Search customer orders by date range, status, or customer email. Returns up to 50 matching orders sorted by date."
+  # ...
 end
 
 # Bad: Vague
-tool :search do
+class Search < RubyLLM::Tool
   description "Searches stuff"
+  # ...
 end
 ```
 
 ### 2. Validate Inputs
 
 ```ruby
-handler do |email:, **_|
+def execute(email:)
   unless email.match?(/\A[\w+\-.]+@[a-z\d\-]+(\.[a-z\d\-]+)*\.[a-z]+\z/i)
     return { error: "Invalid email format" }
   end
-  # ... rest of handler
+  # ... rest of logic
 end
 ```
 
-### 3. Handle Errors Gracefully
-
-```ruby
-handler do |id:, **_|
-  result = ExternalAPI.fetch(id)
-  { success: true, data: result }
-rescue ExternalAPI::NotFound
-  { success: false, error: "Resource not found", id: id }
-rescue ExternalAPI::RateLimited => e
-  { success: false, error: "Rate limited", retry_after: e.retry_after }
-rescue StandardError => e
-  { success: false, error: "Unexpected error: #{e.message}" }
-end
-```
-
-### 4. Return Structured Data
+### 3. Return Structured Data
 
 ```ruby
 # Good: Structured and consistent
-handler do |**_|
+def execute(**_)
   {
     success: true,
     data: { id: 1, name: "Item" },
@@ -384,9 +425,15 @@ handler do |**_|
 end
 
 # Bad: Unstructured
-handler { |**_| "Found item with id 1 named Item" }
+def execute(**_)
+  "Found item with id 1 named Item"
+end
 ```
 
+### 4. Keep Tools Focused
+
+Each tool should do one thing well. Prefer multiple focused tools over one tool that does everything.
+
 ## Next Steps
 
 - [MCP Integration](mcp-integration.md) - External tool servers