robot_lab 0.0.1 → 0.0.6

data/docs/api/core/tool.md

@@ -2,27 +2,67 @@
 
 Callable function that robots can use to interact with external systems.
 
-## Class: `RobotLab::Tool`
+## Class: `RobotLab::Tool < RubyLLM::Tool`
+
+RobotLab::Tool inherits from RubyLLM::Tool, adding a `robot:` constructor parameter and a `Tool.create` factory for dynamic tools.
+
+### Subclass Pattern
+
+```ruby
+class GetWeather < RobotLab::Tool
+  description "Get weather for a location"
+
+  param :location, type: "string", desc: "City name or zip code"
+  param :unit, type: "string", desc: "Temperature unit", required: false
+
+  def execute(location:, unit: "celsius")
+    WeatherService.current(location, unit: unit)
+  end
+end
+```
+
+### Factory Pattern
 
 ```ruby
-tool = RobotLab::Tool.new(
+tool = RobotLab::Tool.create(
   name: "get_weather",
-  description: "Get weather for a location",
-  parameters: { location: { type: "string", required: true } },
-  handler: ->(location:, **_) { WeatherService.fetch(location) }
-)
+  description: "Get current weather for a location",
+  parameters: {
+    type: "object",
+    properties: {
+      location: { type: "string", description: "City name" }
+    },
+    required: ["location"]
+  }
+) { |args| WeatherService.current(args[:location]) }
 ```
 
 ## Constructor
 
 ```ruby
-Tool.new(
+Tool.new(robot: nil)
+```
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `robot` | `Robot, nil` | The owning robot instance |
+
+## Class Methods
+
+### Tool.create
+
+Factory for dynamic tools (MCP wrappers, inline tools).
+
+```ruby
+Tool.create(
   name:,
   description: nil,
-  parameters: {},
-  handler:,
-  mcp: false,
-  strict: false
+  parameters: nil,
+  mcp: nil,
+  robot: nil,
+  &handler
 )
 ```
 
@@ -30,321 +70,277 @@ Tool.new(
 
 | Name | Type | Description |
 |------|------|-------------|
-| `name` | `String` | Tool identifier |
+| `name` | `String, Symbol` | Tool identifier |
 | `description` | `String` | What the tool does |
-| `parameters` | `Hash` | Parameter definitions |
-| `handler` | `Proc` | Execution function |
-| `mcp` | `Boolean` | Is this an MCP tool? |
-| `strict` | `Boolean` | Strict parameter validation |
+| `parameters` | `Hash` | JSON Schema parameter definition |
+| `mcp` | `String` | MCP server name |
+| `robot` | `Robot` | Owning robot instance |
+| `&handler` | `Block` | Receives `args` hash, returns result |
 
-## Attributes
+## Inherited DSL (from RubyLLM::Tool)
 
-### name
+### description
 
 ```ruby
-tool.name  # => String
+class MyTool < RobotLab::Tool
+  description "What this tool does"
+end
 ```
 
-Tool identifier.
+### param
 
-### description
+```ruby
+class MyTool < RobotLab::Tool
+  param :name, type: "string", desc: "User's name"
+  param :age, type: "integer", desc: "User's age", required: false
+end
+```
+
+### execute
 
 ```ruby
-tool.description  # => String
+class MyTool < RobotLab::Tool
+  def execute(name:, age: nil)
+    # Implementation
+  end
+end
 ```
 
-Human-readable description.
+### halt
 
-### parameters
+Stop the tool use loop from within execute:
 
 ```ruby
-tool.parameters  # => Hash
+def execute(**)
+  halt("Done processing")
+end
 ```
 
-Parameter schema.
+### with_params
 
-### handler
+Set provider-specific parameters:
 
 ```ruby
-tool.handler  # => Proc
+class MyTool < RobotLab::Tool
+  with_params(strict: true)
+end
 ```
 
-Function that executes the tool.
+## Attributes
 
-### mcp
+### robot
 
 ```ruby
-tool.mcp  # => Boolean
+tool.robot  # => Robot or nil
+tool.robot = some_robot
 ```
 
-Whether this is an MCP-sourced tool.
+Read/write accessor for the owning robot. Set via constructor or assigned later.
 
-### strict
+### mcp
 
 ```ruby
-tool.strict  # => Boolean
+tool.mcp  # => String or nil
 ```
 
-Whether to use strict parameter validation.
+The MCP server name, set via `Tool.create(mcp: "server_name")`.
 
 ## Methods
 
-### call
+### name
 
 ```ruby
-result = tool.call(
-  params,
-  robot: robot,
-  network: network,
-  state: state
-)
+tool.name  # => String
 ```
 
-Execute the tool with parameters.
+Returns the tool name. For subclasses, derived from the class name (CamelCase to snake_case). For `create`d tools, returns the explicit name.
 
-### to_h
+### mcp?
 
 ```ruby
-tool.to_h  # => Hash
+tool.mcp?  # => Boolean
 ```
 
-Hash representation.
+Whether this is an MCP-provided tool.
 
-### to_json
+### call
 
 ```ruby
-tool.to_json  # => String
+result = tool.call(args_hash)
 ```
 
-JSON representation.
+Inherited from RubyLLM::Tool. Converts string keys to symbols and calls `execute(**args)`.
 
-### to_json_schema
+### params_schema
 
 ```ruby
-tool.to_json_schema  # => Hash
+tool.params_schema  # => Hash or nil
 ```
 
-JSON Schema representation for LLM.
-
-## Parameter Schema
+Inherited. Returns the JSON Schema for tool parameters.
 
-### Basic Types
+### provider_params
 
 ```ruby
-parameters: {
-  name: { type: "string" },
-  count: { type: "integer" },
-  price: { type: "number" },
-  active: { type: "boolean" },
-  tags: { type: "array" }
-}
+tool.provider_params  # => Hash
 ```
 
-### Required Parameters
+Inherited. Returns provider-specific parameters (e.g., `{ strict: true }`).
+
+### to_h
 
 ```ruby
-parameters: {
-  id: { type: "string", required: true }
-}
+tool.to_h  # => Hash
 ```
 
-### Descriptions
+Hash representation with `:name`, `:description`, `:mcp`.
+
+### to_json
 
 ```ruby
-parameters: {
-  query: {
-    type: "string",
-    description: "Search query (supports wildcards)"
-  }
-}
+tool.to_json  # => String
 ```
 
-### Enums
+JSON representation.
+
+### to_json_schema
 
 ```ruby
-parameters: {
-  status: {
-    type: "string",
-    enum: ["pending", "active", "completed"]
-  }
-}
+tool.to_json_schema  # => Hash
 ```
 
-### Defaults
+JSON Schema representation for LLM function calling. Returns `{ name:, description:, parameters: }`.
+
+## Robot-Aware Tools
+
+Tools that modify their owning robot use the `robot` accessor:
 
 ```ruby
-parameters: {
-  limit: {
-    type: "integer",
-    default: 10
-  }
-}
+class AdjustTemperature < RobotLab::Tool
+  description "Adjust the robot's creativity level"
+
+  param :level, type: "number", desc: "Temperature from 0.0 to 1.0"
+
+  def execute(level:)
+    robot.with_temperature(level)
+    "Temperature adjusted to #{level}"
+  end
+end
+
+# Pass robot: self when constructing
+robot = RobotLab.build(
+  name: "creative_bot",
+  system_prompt: "You are creative.",
+  local_tools: [AdjustTemperature.new(robot: self)]
+)
 ```
 
-## Handler
+## Parameter Types
 
-### Basic Handler
+### String
 
 ```ruby
-handler: ->(param:, **_context) {
-  do_something(param)
-}
+param :name, type: "string", desc: "User's full name"
 ```
 
-### With Context
+### Integer
 
 ```ruby
-handler: ->(param:, robot:, network:, state:) {
-  # robot - The executing Robot
-  # network - The NetworkRun
-  # state - Current State
+param :count, type: "integer", desc: "Number of results"
+```
 
-  user = state.data[:user_id]
-  state.memory.remember("last_action", param)
+### Number (Float)
 
-  perform_action(param, user)
-}
+```ruby
+param :price, type: "number", desc: "Price in dollars"
 ```
 
-### Error Handling
+### Boolean
 
 ```ruby
-handler: ->(id:, **_) {
-  record = Record.find_by(id: id)
-
-  if record
-    { success: true, data: record.to_h }
-  else
-    { success: false, error: "Not found" }
-  end
-rescue StandardError => e
-  { success: false, error: e.message }
-}
+param :active, type: "boolean", desc: "Whether the user is active"
 ```
 
-## Builder DSL
+### Required vs Optional
 
-In robot builder:
+Parameters are required by default. Mark optional with `required: false`:
 
 ```ruby
-tool :tool_name do
-  description "What it does"
+param :query, type: "string", desc: "Search query"                    # required
+param :limit, type: "integer", desc: "Max results", required: false   # optional
+```
 
-  parameter :param1, type: :string, required: true
-  parameter :param2, type: :integer, default: 10
+## Built-in: AskUser
 
-  handler do |param1:, param2:, **_context|
-    # Implementation
-  end
+`RobotLab::AskUser` is a built-in tool that lets a robot ask the user a question via the terminal. The LLM decides when human input is needed and calls this tool.
+
+### Class: `RobotLab::AskUser < RobotLab::Tool`
+
+```ruby
+class RobotLab::AskUser < RobotLab::Tool
+  description "Ask the user a question and wait for their typed response"
+  param :question, type: "string",  desc: "The question to ask the user"
+  param :choices,  type: "array",   desc: "Optional list of choices to present", required: false
+  param :default,  type: "string",  desc: "Default value if user presses Enter",  required: false
 end
 ```
 
-## ToolManifest
+### Parameters
 
-Wrap tools with modified metadata:
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `question` | `String` | Yes | The question to display |
+| `choices` | `Array` | No | Numbered choices to present |
+| `default` | `String` | No | Value returned when user presses Enter without typing |
 
-```ruby
-manifest = RobotLab::ToolManifest.new(
-  tool: original_tool,
-  name: "custom_name",
-  description: "Custom description"
-)
+### IO Resolution
 
-# Original tool is used, metadata is overridden
-```
+The tool reads input and writes output using the owning robot's `input`/`output` accessors:
 
-### Attributes
+1. `robot.input` / `robot.output` if set
+2. Falls back to `$stdin` / `$stdout`
 
-- `tool` - The wrapped tool
-- `name` - Override name (or original)
-- `description` - Override description (or original)
-- `aliases` - Alternative names
+### Terminal Output
 
-## Examples
+```
+[robot_name] What programming language do you want to learn?
+  1. Ruby
+  2. Python
+  3. Go
+> [Ruby]
+```
 
-### Simple Tool
+### Usage
 
 ```ruby
-tool = Tool.new(
-  name: "current_time",
-  description: "Get the current time",
-  handler: ->(**, _) { Time.now.iso8601 }
+robot = RobotLab.build(
+  name: "interviewer",
+  system_prompt: "Interview the user about their project needs. Use ask_user to gather information.",
+  local_tools: [RobotLab::AskUser]
 )
+robot.run("Find out what the user wants to build")
 ```
 
-### Tool with Parameters
+### Testing with StringIO
 
 ```ruby
-tool = Tool.new(
-  name: "search_users",
-  description: "Search users by criteria",
-  parameters: {
-    query: {
-      type: "string",
-      description: "Search query",
-      required: true
-    },
-    limit: {
-      type: "integer",
-      description: "Max results",
-      default: 10
-    },
-    status: {
-      type: "string",
-      enum: ["active", "inactive", "all"],
-      default: "active"
-    }
-  },
-  handler: ->(query:, limit:, status:, **_) {
-    User.search(query, limit: limit, status: status)
-  }
-)
+robot = RobotLab::Robot.new(name: "bot", template: :assistant)
+robot.input  = StringIO.new("Ruby\n")
+robot.output = StringIO.new
+
+tool = RobotLab::AskUser.new(robot: robot)
+result = tool.call("question" => "Pick a language:", "choices" => ["Ruby", "Python"])
+# => "Ruby"
 ```
 
-### API Integration Tool
+### Choice Mapping
 
-```ruby
-tool = Tool.new(
-  name: "fetch_stock_price",
-  description: "Get current stock price",
-  parameters: {
-    symbol: { type: "string", required: true }
-  },
-  handler: ->(symbol:, **_) {
-    response = HTTP.get("https://api.stocks.example/#{symbol}")
-
-    if response.status.success?
-      JSON.parse(response.body)
-    else
-      { error: "Failed to fetch", status: response.status.code }
-    end
-  rescue HTTP::Error => e
-    { error: "Network error: #{e.message}" }
-  }
-)
-```
+When `choices` are provided, the user can type either:
 
-### Database Tool
+- A **number** (e.g., `2`) — mapped to the corresponding choice text
+- **Text** (e.g., `Python`) — returned as-is
 
-```ruby
-tool = Tool.new(
-  name: "get_order",
-  description: "Get order details",
-  parameters: {
-    order_id: { type: "string", required: true }
-  },
-  handler: ->(order_id:, state:, **_) {
-    user_id = state.data[:user_id]
-    order = Order.find_by(id: order_id, user_id: user_id)
-
-    if order
-      order.as_json(include: [:items, :shipping])
-    else
-      { error: "Order not found or unauthorized" }
-    end
-  }
-)
-```
+Out-of-range numbers are returned as-is (the LLM can re-ask if needed).
 
 ## See Also
 

data/docs/api/index.md

@@ -10,9 +10,8 @@ The fundamental building blocks of RobotLab:
 |-------|-------------|
 | [Robot](core/robot.md) | LLM-powered agent with personality and tools |
 | [Network](core/network.md) | Orchestrates multiple robots |
-| [State](core/state.md) | Manages conversation and workflow data |
+| [Memory](core/memory.md) | Reactive key-value store for sharing data |
 | [Tool](core/tool.md) | Custom function robots can call |
-| [Memory](core/memory.md) | Shared key-value store |
 
 ## Messages
 
@@ -21,20 +20,10 @@ Message types for LLM communication:
 | Class | Description |
 |-------|-------------|
 | [UserMessage](messages/user-message.md) | User input with metadata |
-| [TextMessage](messages/text-message.md) | Assistant text response |
+| [TextMessage](messages/text-message.md) | Text message with role |
 | [ToolCallMessage](messages/tool-call-message.md) | Tool execution request |
 | [ToolResultMessage](messages/tool-result-message.md) | Tool execution result |
 
-## Adapters
-
-Provider-specific message conversion:
-
-| Class | Description |
-|-------|-------------|
-| [Anthropic](adapters/anthropic.md) | Claude models adapter |
-| [OpenAI](adapters/openai.md) | GPT models adapter |
-| [Gemini](adapters/gemini.md) | Google Gemini adapter |
-
 ## MCP (Model Context Protocol)
 
 Connect to external tool servers:
@@ -54,29 +43,19 @@ Real-time response streaming:
 | [Context](streaming/context.md) | Streaming context |
 | [Events](streaming/events.md) | Event utilities |
 
-## History
-
-Conversation persistence:
-
-| Class | Description |
-|-------|-------------|
-| [Config](history/config.md) | History configuration |
-| [ThreadManager](history/thread-manager.md) | Thread lifecycle |
-| [ActiveRecordAdapter](history/active-record-adapter.md) | Rails adapter |
-
 ## Module Methods
 
 ### RobotLab
 
 ```ruby
 # Configuration
-RobotLab.configuration
-RobotLab.configure { |config| ... }
+RobotLab.config              # => Config instance
+RobotLab.reload_config!      # => reload from all sources
 
 # Building
-RobotLab.build { ... }
-RobotLab.create_network { ... }
-RobotLab.create_state(...)
+RobotLab.build(name:, template:, system_prompt:, context:, **options)
+RobotLab.create_network(name:, concurrency:) { ... }
+RobotLab.create_memory(data:, enable_cache:, **options)
 ```
 
 See individual class documentation for detailed method references.