legate 0.1.0

data/public/docs/multi_agent_systems/workflow_agents.md

@@ -0,0 +1,72 @@
+# Workflow Agents
+
+Workflow Agents are specialized agents designed to orchestrate other agents in specific patterns. They extend the base `Legate::Agent` class.
+
+## Sequential Agent
+
+Executes a list of sub-agents in a strict order. The output of one agent can be used as context for the next.
+
+**Configuration:**
+```ruby
+Legate::Agent.define do |agent|
+  agent.name :content_pipeline
+  agent.agent_type :sequential
+  agent.instruction "Process content."
+  
+  # Define execution order
+  agent.sequential_sub_agents :researcher, :drafter, :editor
+end
+```
+
+**Behavior:**
+1.  Executes `:researcher`.
+2.  Passes result to `:drafter`.
+3.  Passes result to `:editor`.
+4.  Returns the final result from `:editor`.
+
+## Parallel Agent
+
+Executes multiple sub-agents concurrently. Useful for independent tasks.
+
+**Configuration:**
+```ruby
+Legate::Agent.define do |agent|
+  agent.name :market_analysis
+  agent.agent_type :parallel
+  agent.instruction "Analyze market sectors."
+  
+  # Define agents to run in parallel
+  agent.parallel_sub_agents :tech_analyst, :finance_analyst, :healthcare_analyst
+end
+```
+
+**Behavior:**
+1.  Starts all sub-agents simultaneously.
+2.  Waits for all to complete.
+3.  Returns a combined result containing outputs from all agents.
+
+## Loop Agent
+
+Executes a sub-agent (or a sequence of sub-agents) repeatedly until a condition is met or a maximum iteration count is reached.
+
+**Configuration:**
+```ruby
+Legate::Agent.define do |agent|
+  agent.name :refiner
+  agent.agent_type :loop
+  agent.instruction "Refine the text until it meets quality standards."
+  
+  agent.loop_sub_agents :editor
+  
+  # Stop after 5 iterations
+  agent.loop_max_iterations 5
+  
+  # OR stop when state key :quality_approved is true
+  agent.loop_condition :quality_approved, true
+end
+```
+
+**Behavior:**
+1.  Executes the sub-agents.
+2.  Checks the loop condition (state key).
+3.  Repeats if condition not met and max iterations not reached.

data/public/docs/tools/legate_built_in_tools.md

@@ -0,0 +1,332 @@
+# Legate Built-in Tools
+
+This document serves as a reference guide for the common tools included with the Legate. These tools are available for agents to use once registered.
+
+## General Usage Notes
+
+*   **Tool Naming**: When adding tools to an agent definition, you typically use their inferred snake_case name (e.g., `:calculator`, `:echo_tool`) unless an `explicit_tool_name` is specified in the tool's class.
+*   **Parameters**: Each tool defines its expected parameters, including their type and whether they are required.
+*   **Return Value**: Successful tool executions generally return a hash with `status: :success` and a `result` field. Errors usually result in an `Legate::ToolError` or return a hash with `status: :error` and an `error_message`.
+
+---
+
+## Calculator
+
+*   **Tool Name**: `:calculator` (inferred)
+*   **Purpose**: Calculates the result of an arithmetic operation.
+*   **Parameters**:
+    *   `operand1` (numeric, required): The first number for the calculation.
+    *   `operand2` (numeric, required): The second number for the calculation.
+    *   `operation` (string, required): The operation to perform (e.g., "add", "subtract", "multiply", "divide", or symbols `+`, `-`, `*`, `/`).
+*   **Example Invocation (Conceptual)**:
+    ```json
+    {
+      "tool_name": "calculator",
+      "parameters": {
+        "operand1": 10,
+        "operand2": 5,
+        "operation": "multiply"
+      }
+    }
+    ```
+*   **Example Success Response**:
+    ```json
+    {
+      "status": "success",
+      "result": 50
+    }
+    ```
+
+---
+
+## Echo
+
+*   **Tool Name**: `:echo` (inferred from class `Echo` -> `Legate::Tools::Echo`)
+*   **Purpose**: Echoes back the provided message.
+*   **Parameters**:
+    *   `message` (string, required): The message to echo.
+*   **Example Invocation (Conceptual)**:
+    ```json
+    {
+      "tool_name": "echo",
+      "parameters": {
+        "message": "Hello, world!"
+      }
+    }
+    ```
+*   **Example Success Response**:
+    ```json
+    {
+      "status": "success",
+      "result": "Hello, world!"
+    }
+    ```
+
+---
+
+## CatFacts
+
+*   **Tool Name**: `:cat_facts` (inferred)
+*   **Purpose**: Fetches a random cat fact from an online API (`https://catfact.ninja`).
+*   **Parameters**: None.
+*   **Example Invocation (Conceptual)**:
+    ```json
+    {
+      "tool_name": "cat_facts",
+      "parameters": {}
+    }
+    ```
+*   **Example Success Response**:
+    ```json
+    {
+      "status": "success",
+      "result": "Cats have over 20 muscles that control their ears."
+    }
+    ```
+
+---
+
+## WebhookTool
+
+*   **Tool Name**: `:webhook_tool` (explicitly set)
+*   **Purpose**: Sends an HTTP POST request with a JSON payload to a specified webhook URL. Can optionally sign the request using HMAC-SHA256.
+*   **Parameters**:
+    *   `url` (string, required): The target webhook URL.
+    *   `payload` (hash or string, required): The data payload to send. Hash payloads are automatically JSON-encoded with `Content-Type: application/json`.
+    *   `secret` (string, optional): Optional secret key for calculating HMAC-SHA256 signature (sent in `X-Hub-Signature-256` header).
+    *   `headers` (hash, optional): Optional custom headers to include (e.g., `Content-Type` for string payloads).
+*   **Example Invocation (Conceptual)**:
+    ```json
+    {
+      "tool_name": "webhook_tool",
+      "parameters": {
+        "url": "https://example.com/my-hook",
+        "payload": {"data": "some_value", "event": "item_created"},
+        "secret": "mysecretkey"
+      }
+    }
+    ```
+*   **Example Success Response**:
+    ```json
+    {
+      "status": "success",
+      "result": {
+        "response_status": 200,
+        "response_body": "Webhook received successfully"
+      }
+    }
+    ```
+
+---
+
+## HttpRequest
+
+*   **Tool Name**: `:http_request` (inferred)
+*   **Purpose**: Makes an HTTP request to a URL and returns the status code, headers, and body. Supports `GET` (default), `POST`, `PUT`, `PATCH`, `DELETE`, and `HEAD`.
+*   **Security**: SSRF-safe — requests to loopback, link-local, private, CGNAT, and `0.0.0.0/8` addresses (e.g. cloud metadata at `169.254.169.254`) are blocked, and the connection is pinned to the validated IP to prevent DNS rebinding. Set `LEGATE_ALLOW_PRIVATE_TOOL_URLS=1` to reach private hosts in development.
+*   **Auth-aware**: Configured authentication (URL → scheme/credential mappings) is applied automatically for matching URLs. Pass `headers` for manual auth.
+*   **Parameters**:
+    *   `url` (string, required): The full URL to request (must be `http` or `https`).
+    *   `method` (string, optional): HTTP method. Defaults to `GET`.
+    *   `headers` (hash, optional): Request headers.
+    *   `body` (hash or string, optional): Request body. A Hash is JSON-encoded with `Content-Type: application/json`.
+    *   `query` (hash, optional): Query-string parameters.
+*   **Notes**: A non-2xx response is returned as a normal result (with its `status_code`) so an agent can inspect it; only network/SSRF/timeout failures are errors. Bodies are capped at 1 MB (`truncated: true` when cut).
+*   **Example Success Response**:
+    ```json
+    {
+      "status": "success",
+      "result": {
+        "url": "https://api.example.com/v1/items",
+        "status_code": 200,
+        "headers": { "content-type": "application/json" },
+        "body": "{\"items\": []}",
+        "truncated": false
+      }
+    }
+    ```
+
+---
+
+## ReadWebpage
+
+*   **Tool Name**: `:read_webpage` (inferred)
+*   **Purpose**: Fetches a web page and returns its title and readable text content with HTML markup removed (script/style stripped, entities decoded, whitespace collapsed). The backbone of research/RAG agents.
+*   **Security**: SSRF-safe, identical guards to `http_request`.
+*   **Parameters**:
+    *   `url` (string, required): The URL of the page to read (`http` or `https`).
+    *   `max_chars` (integer, optional): Maximum characters of text to return (default 20,000, hard cap 200,000).
+*   **Example Success Response**:
+    ```json
+    {
+      "status": "success",
+      "result": {
+        "url": "https://example.com",
+        "title": "Example Domain",
+        "text": "Example Domain  This domain is for use in illustrative examples...",
+        "truncated": false
+      }
+    }
+    ```
+
+---
+
+## CurrentTime
+
+*   **Tool Name**: `:current_time` (inferred)
+*   **Purpose**: Returns the current date and time. Language models don't know the current time, so this is a common building block for scheduling, freshness checks, and "how long ago" reasoning.
+*   **Parameters**:
+    *   `timezone` (string, optional): `"UTC"` (default), `"local"`, or a fixed UTC offset such as `"+05:30"` or `"-0800"`. Named IANA zones (e.g. `America/New_York`) are intentionally not supported (no timezone-database dependency).
+    *   `format` (string, optional): A strftime format (e.g. `"%A, %B %-d, %Y"`). Defaults to ISO 8601.
+*   **Example Success Response**:
+    ```json
+    {
+      "status": "success",
+      "result": {
+        "iso8601": "2026-06-14T14:05:09Z",
+        "formatted": "2026-06-14T14:05:09Z",
+        "epoch": 1781445909,
+        "timezone": "UTC"
+      }
+    }
+    ```
+
+---
+
+## AgentTool (Delegate Task)
+
+*   **Tool Name**: `:delegate_task` (explicitly set, class `AgentTool`)
+*   **Purpose**: Delegates a specified task to another agent identified by its unique name. This is useful when a specific, pre-defined agent is better suited for a sub-task.
+*   **Parameters**:
+    *   `target_agent_name` (string, required): The unique name of the agent definition (must be findable by `Legate::GlobalDefinitionRegistry`) to delegate the task to.
+    *   `task` (string, required): The specific task description to be executed by the target agent.
+*   **Example Invocation (Conceptual)**:
+    ```json
+    {
+      "tool_name": "delegate_task",
+      "parameters": {
+        "target_agent_name": "customer_service_agent",
+        "task": "The user is asking for a refund for order 12345. Please process this."
+      }
+    }
+    ```
+*   **Example Success Response** (depends on the target agent's response):
+    ```json
+    {
+      "status": "success",
+      "result": "The refund for order 12345 has been processed successfully."
+    }
+    ```
+
+---
+
+## Asynchronous Operations Tools
+
+Legate provides a mechanism for tools to initiate long-running tasks as background threads using `Concurrent::Promises.future`. This typically involves two tools: one to start the job and one to check its status.
+
+### BaseAsyncJobTool (Developer Note)
+This is an abstract base class (`Legate::Tools::BaseAsyncJobTool`) and not directly invoked by an agent. Developers creating new asynchronous tools would inherit from it. It handles the common logic of running tasks in background threads and storing job results in an in-memory `Concurrent::Map`.
+
+### SleepyTool (Example Async Tool)
+
+*   **Tool Name**: `:start_sleepy_job` (explicitly set, class `SleepyTool`)
+*   **Purpose**: Starts a background task that simply sleeps for a specified duration and then records a message. This tool is primarily an example of an asynchronous tool.
+*   **Parameters**:
+    *   `duration` (integer, required): How many seconds the task should sleep.
+    *   `message` (string, required): A message to include in the final result upon task completion.
+*   **Invocation Result**: When this tool is called, it starts a background thread via `Concurrent::Promises.future`.
+    *   **Example Success Response (Job Enqueued)**:
+        ```json
+        {
+          "status": "pending",
+          "job_id": "abcdef1234567890"
+        }
+        ```
+*   **Getting the Actual Result**: Use the `check_job_status` tool with the returned `job_id`.
+
+### CheckJobStatusTool
+
+*   **Tool Name**: `:check_job_status` (explicitly set, class `CheckJobStatusTool`)
+*   **Purpose**: Checks the status and retrieves the result of a previously started background task using its `job_id`.
+*   **Parameters**:
+    *   `job_id` (string, required): The ID of the job to check (obtained from a tool like `start_sleepy_job`).
+*   **Response Scenarios**:
+    *   **Job Pending**:
+        ```json
+        {
+          "status": "pending",
+          "job_id": "abcdef1234567890",
+          "message": "Job is queued or currently running."
+        }
+        ```
+    *   **Job Succeeded** (result from in-memory store):
+        ```json
+        {
+          "status": "success",
+          "job_id": "abcdef1234567890",
+          "result": "Slept for 10 seconds. Your message: Hello from async job."
+        }
+        ```
+    *   **Job Errored** (error from in-memory store):
+        ```json
+        {
+          "status": "error",
+          "job_id": "abcdef1234567890",
+          "error_message": "Something went wrong during the job.",
+          "error_details": "Optional details about the error, like exception class."
+        }
+        ```
+    *   **Job Failed**: The tool call itself might raise an `Legate::ToolError` or return a generic error status.
+    *   **Job Not Found/Expired**: The tool call might raise an `Legate::ToolError` or return an error status indicating the result is unavailable.
+
+```mermaid
+graph LR
+    subgraph "Async Tool Flow"
+        A[Agent] -- Calls --> B(Start Async Job Tool <br> e.g., :start_sleepy_job)
+        B -- Starts Thread --> C[Concurrent::Promises.future]
+        B -- Returns job_id --> A
+        C -- Executes --> D(Background Thread)
+        D -- Writes Result/Error --> E[Concurrent::Map]
+        A -- Calls with job_id --> F(Check Job Status Tool <br> :check_job_status)
+        F -- Reads from --> E
+        F -- Returns Status/Result --> A
+    end
+
+    style A fill:#cde,stroke:#333
+    style B fill:#fdc,stroke:#333
+    style C fill:#def,stroke:#333
+    style D fill:#fdd,stroke:#333
+    style E fill:#fcf,stroke:#333
+    style F fill:#dfd,stroke:#333
+```
+
+---
+
+## RandomNumberTool (demo tool — not registered by default)
+
+> `random_number` ships with Legate but is **not registered as a default tool**.
+> It's a demo. Opt in with `Legate::GlobalToolManager.register_tool(Legate::Tools::RandomNumberTool)`
+> before an agent can `use_tool :random_number`.
+
+*   **Tool Name**: `:random_number` (explicitly set, class `RandomNumberTool`)
+*   **Purpose**: Generates a random integer between a minimum and maximum value (inclusive). Defaults to generating a number between 1 and 100 if no parameters are provided.
+*   **Parameters**:
+    *   `min` (integer, optional): The minimum value for the random number (inclusive). Defaults to 1.
+    *   `max` (integer, optional): The maximum value for the random number (inclusive). Defaults to 100.
+*   **Example Invocation (Conceptual)**:
+    ```json
+    {
+      "tool_name": "random_number",
+      "parameters": {
+        "min": 10,
+        "max": 20
+      }
+    }
+    ```
+*   **Example Success Response**:
+    ```json
+    {
+      "status": "success",
+      "result": 15
+    }
+    ```

data/public/docs/tools/legate_tools_and_registry.md

@@ -0,0 +1,263 @@
+# Legate Tools and Registry
+
+This document describes the tool system in Legate, including how tools are defined, registered, and made available to agents.
+
+## Overview
+
+Legate provides a robust tool system that allows agents to perform actions beyond simple text generation. Tools are Ruby classes that encapsulate specific functionality like performing calculations, making HTTP requests, or delegating tasks to other agents.
+
+```mermaid
+graph TB
+    subgraph Registration
+        ToolClass[Tool Class Definition] --> GTM[GlobalToolManager]
+    end
+    
+    subgraph AgentSetup
+        AgentDef[AgentDefinition] -->|use_tool :name| Agent
+        Agent -->|creates| TR[ToolRegistry]
+        GTM -->|populates| TR
+    end
+    
+    subgraph Execution
+        Agent -->|execute| Tool[Tool Instance]
+        Tool -->|with| TC[ToolContext]
+    end
+    
+    style GTM fill:#cfc,stroke:#333
+    style TR fill:#cfc,stroke:#333
+    style Tool fill:#ccf,stroke:#333
+```
+
+## Core Components
+
+### 1. GlobalToolManager
+
+The `Legate::GlobalToolManager` is a global registry where all tool classes are registered. It provides a central place to discover available tools.
+
+**Key Methods:**
+
+| Method | Description |
+|--------|-------------|
+| `register_tool(tool_class)` | Register a tool class globally |
+| `find_class(name_symbol)` | Find a tool class by its symbolic name |
+| `list_all_tools` | Get metadata for all registered tools |
+| `registered_tool_names` | Get an array of all registered tool name symbols |
+| `create_instance(name_symbol)` | Create a new instance of a tool by name |
+
+**Example:**
+```ruby
+# Registration (typically automatic via inheritance)
+Legate::GlobalToolManager.register_tool(MyCustomTool)
+
+# Discovery
+available_tools = Legate::GlobalToolManager.list_all_tools
+# => [{name: :my_custom_tool, description: "...", parameters: [...]}]
+
+# Instantiation
+tool = Legate::GlobalToolManager.create_instance(:calculator)
+```
+
+### 2. ToolRegistry
+
+The `Legate::ToolRegistry` is an instance-specific collection of tools available to a particular agent. Each agent has its own ToolRegistry, populated from the GlobalToolManager based on the agent's definition.
+
+**Key Methods:**
+
+| Method | Description |
+|--------|-------------|
+| `register(name, klass)` | Register a tool class with this registry |
+| `find_class(name_symbol)` | Find a tool class by name in this registry |
+| `create_instance(name_symbol)` | Create a tool instance |
+| `list_tools` | Get metadata for tools in this registry |
+
+**Relationship to Agent:**
+```ruby
+# When an agent is initialized, its ToolRegistry is populated
+definition.tool_names.each do |tool_name|
+  klass = Legate::GlobalToolManager.find_class(tool_name)
+  agent.tool_registry.register(tool_name, klass)
+end
+```
+
+## Defining Tools
+
+Tools are defined by creating a class that inherits from `Legate::Tool` and uses the metadata DSL.
+
+```ruby
+class WeatherTool < Legate::Tool
+  # Description shown to the LLM planner
+  tool_description 'Get current weather for a location'
+  
+  # Define parameters the tool accepts
+  parameter :location,
+    type: :string,
+    description: 'City name or coordinates',
+    required: true
+  
+  parameter :units,
+    type: :string,
+    description: 'Temperature units: celsius or fahrenheit',
+    required: false
+  
+  private
+  
+  def perform_execution(params, context)
+    location = params[:location]
+    units = params[:units] || 'celsius'
+
+    # Tool logic here...
+
+    Legate::ToolResult.success("Weather for #{location}: 72°")
+  end
+end
+
+# Register the tool (automatic if file is auto-loaded)
+Legate::GlobalToolManager.register_tool(WeatherTool)
+```
+
+### Return values
+
+`perform_execution` returns either a typed `Legate::ToolResult` or the
+equivalent canonical hash — both work:
+
+```ruby
+Legate::ToolResult.success(value)            # { status: :success, result: value }
+Legate::ToolResult.error('not found')        # { status: :error,   error_message: 'not found' }
+Legate::ToolResult.pending(job_id: id)        # { status: :pending, job_id: id }
+
+# Equivalent hashes (unchanged, still supported):
+{ status: :success, result: value }
+```
+
+`Tool#execute` normalizes a `ToolResult` to the hash, so the rest of the
+pipeline is unchanged. The typed form avoids hand-built hashes and mirrors the
+`Event#answer` / `#success?` accessors you read results with.
+
+### Tool Metadata DSL
+
+The `Legate::Tool::MetadataDsl` module provides class-level methods for defining tool metadata:
+
+| DSL Method | Purpose |
+|------------|---------|
+| `tool_name` | Explicitly set the tool's symbolic name |
+| `tool_description` | Provide a description for the LLM |
+| `parameter(name, options)` | Define an input parameter |
+
+**Parameter Options:**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `type` | Symbol | `:string`, `:integer`, `:float`/`:numeric`, `:boolean`, `:array`, `:hash` |
+| `description` | String | Description for the LLM |
+| `required` | Boolean | Whether the parameter is required |
+| `enum` | Array | Allowed values (optional) |
+
+### Tool Name Inference
+
+If `tool_name` is not explicitly set, Legate infers it from the class name:
+
+- `MyCustomTool` → `:my_custom_tool`
+- `Calculator` → `:calculator`
+- `Legate::Tools::CatFacts` → `:cat_facts`
+
+## Using Tools in Agents
+
+Tools are associated with agents via the `use_tool` method in the agent definition:
+
+```ruby
+Legate::AgentDefinition.new.define do |a|
+  a.name :my_agent
+  # instruction is optional — defaults from the name/description if omitted
+
+  # Reference a registered tool by name (Symbol or String)…
+  a.use_tool :calculator
+  a.use_tool 'echo'
+
+  # …or pass the class directly: this registers AND selects it in one step,
+  # so you don't need a separate GlobalToolManager.register_tool call.
+  a.use_tool WeatherTool
+end
+```
+
+`use_tool` accepts a Symbol, a String (both coerced to a Symbol), or a
+`Legate::Tool` subclass. A name that matches no registered tool produces a
+warning with a "did you mean?" suggestion and the list of available tools (it
+stays non-fatal — MCP tools register when the agent connects).
+
+You can list what's registered with `Legate.tools` (or `legate tool list` /
+`legate tool info NAME` from the CLI).
+
+## Tool Execution Flow
+
+When an agent executes a tool:
+
+```mermaid
+sequenceDiagram
+    participant Agent
+    participant TR as ToolRegistry
+    participant Tool
+    participant TC as ToolContext
+    
+    Agent->>TR: find_class(:tool_name)
+    TR-->>Agent: ToolClass
+    Agent->>Tool: new()
+    Agent->>TC: new(session_info)
+    Agent->>Tool: execute(params, context)
+    Tool->>Tool: validate_parameters
+    Tool->>Tool: perform_execution
+    Tool-->>Agent: {status: :success, result: ...}
+```
+
+1. The agent looks up the tool class in its ToolRegistry
+2. It creates an instance of the tool
+3. It creates a ToolContext with session information
+4. It calls `execute(params, context)` on the tool
+5. The tool validates parameters and runs `perform_execution`
+6. The tool returns a result hash
+
+## ToolContext
+
+The `Legate::ToolContext` object provides tools with access to:
+
+- Session state (`state_get`, `state_set`)
+- Session ID, user ID, app name
+- Invocation ID for tracking
+- Authentication helpers (for tools using the auth module)
+
+```ruby
+def perform_execution(params, context)
+  # Access session state
+  previous_value = context.state_get(:some_key)
+  
+  # Set state (applied after tool completes)
+  context.state_set(:result_key, 'new value')
+  
+  { status: :success, result: 'Done' }
+end
+```
+
+## Built-in Tools
+
+Legate provides several built-in tools:
+
+| Tool Name | Description |
+|-----------|-------------|
+| `:http_request` | SSRF-safe, auth-aware HTTP client |
+| `:read_webpage` | Fetches a page as readable text |
+| `:current_time` | Current date/time (ISO 8601 / epoch / strftime) |
+| `:calculator` | Performs arithmetic operations |
+| `:echo` | Echoes back the input message |
+| `:cat_facts` | Fetches random cat facts |
+| `:webhook_tool` | Sends outbound webhooks |
+| `:delegate_task` | Delegates to another agent |
+| `:check_job_status` | Checks async job status |
+| `:start_sleepy_job` | Demo async/background job |
+
+See [Built-in Tools Reference](./legate_built_in_tools) for detailed documentation.
+
+## Further Reading
+
+*   [`legate_architecture_overview`](../core_concepts/legate_architecture_overview)
+*   [`legate_built_in_tools`](./legate_built_in_tools)
+*   [`auto_loading`](../guides/auto_loading)
+*   [`ai_code_generators`](../guides/ai_code_generators)