legate 0.1.0

data/public/docs/guides/auto_loading.md

@@ -0,0 +1,326 @@
+# Auto-Loading Custom Tools and Agents
+
+This guide explains how Legate automatically discovers and loads your custom tools and agent definitions when starting the web server.
+
+## Overview
+
+When you run `legate web start`, Legate automatically scans conventional directories for Ruby files containing custom tools and agents. This means you can:
+
+- Drop a tool file in `lib/tools/` and it's automatically available
+- Drop an agent file in `lib/agents/` and it appears in the Web UI
+- No manual configuration required
+
+> The Web UI [AI builders](ai_code_generators) write to `tools/` and `agents/` for
+> you (when installing a tool live, or via an agent's **Save to `agents/`** action),
+> so those generated files are picked up here on the next start too.
+
+## Directory Structure
+
+Legate scans the following directories relative to where you run `legate web start`:
+
+### For Tools
+
+```
+./lib/tools/           # Primary location
+./agents/lib/tools/    # Alternative (nested project)
+./tools/               # Simple projects
+```
+
+### For Agents
+
+```
+./lib/agents/          # Primary location
+./agents/lib/agents/   # Alternative (nested project)
+./agents/              # Simple projects (excludes /tools/ subdirs)
+```
+
+### Recommended Structure
+
+```
+your_project/
+├── Gemfile
+├── .env                    # Environment variables (GOOGLE_API_KEY, etc.)
+├── lib/
+│   ├── tools/
+│   │   ├── weather_tool.rb
+│   │   ├── email_validator_tool.rb
+│   │   └── custom_api_tool.rb
+│   └── agents/
+│       ├── customer_support_agent.rb
+│       ├── data_processor_agent.rb
+│       └── notification_agent.rb
+└── legate_init.rb            # Optional: custom initialization
+```
+
+## Creating Auto-Loadable Tools
+
+Your tool file should:
+
+1. Define the tool class
+2. Register it with `GlobalToolManager`
+
+**Example: `lib/tools/greeting_tool.rb`**
+
+```ruby
+# frozen_string_literal: true
+
+require 'legate/tool'
+
+class GreetingTool < Legate::Tool
+  tool_description 'Generates a personalized greeting'
+  
+  parameter :name,
+    type: :string,
+    description: 'Name of the person to greet',
+    required: true
+    
+  parameter :style,
+    type: :string,
+    description: 'Greeting style: formal, casual, or enthusiastic',
+    required: false
+  
+  private
+  
+  def perform_execution(params, context)
+    name = params[:name]
+    style = params[:style] || 'casual'
+    
+    greeting = case style
+    when 'formal'
+      "Good day, #{name}. How may I assist you?"
+    when 'enthusiastic'
+      "Hey #{name}! Great to see you! 🎉"
+    else
+      "Hello, #{name}!"
+    end
+    
+    { status: :success, result: greeting }
+  end
+end
+
+# This line makes the tool available to agents
+Legate::GlobalToolManager.register_tool(GreetingTool)
+```
+
+## Creating Auto-Loadable Agents
+
+Your agent file should:
+
+1. Define the agent using `AgentDefinition`
+2. Register it with `GlobalDefinitionRegistry`
+
+**Example: `lib/agents/greeter_agent.rb`**
+
+```ruby
+# frozen_string_literal: true
+
+require 'legate'
+
+definition = Legate::AgentDefinition.new.define do |a|
+  a.name :greeter
+  a.description 'A friendly agent that greets users'
+  
+  a.instruction <<~INSTRUCTION
+    You are a friendly greeter agent.
+    
+    When a user introduces themselves or asks for a greeting,
+    use the greeting_tool to generate an appropriate response.
+    
+    Match the greeting style to the user's tone:
+    - Formal requests get formal greetings
+    - Casual messages get casual greetings
+    - Excited users get enthusiastic greetings
+  INSTRUCTION
+  
+  a.use_tool :greeting_tool
+  a.model_name 'gemini-2.0-flash'
+  a.temperature 0.7
+end
+
+# This line makes the agent appear in the Web UI
+Legate::GlobalDefinitionRegistry.register(definition)
+```
+
+## Load Order
+
+Legate loads files in this order:
+
+1. **Initializer** (if present) - `legate_init.rb`, `config/legate_init.rb`, or `agents/legate_init.rb`
+2. **Tools** - All `.rb` files in tool directories
+3. **Agents** - All `.rb` files in agent directories
+4. **Register Definitions** - Agents are registered in the `GlobalDefinitionRegistry` for the Web UI
+
+This order ensures tools are available before agents that reference them.
+
+## Custom Initializer
+
+For advanced setup, create a `legate_init.rb` file in your project root:
+
+```ruby
+# legate_init.rb
+
+# Set up environment
+ENV['MY_CUSTOM_VAR'] ||= 'default_value'
+
+# Configure Legate
+Legate.configure do |config|
+  config.default_model_name = 'gemini-2.0-flash'
+  config.default_temperature = 0.5
+end
+
+# Pre-load specific dependencies
+require 'some_custom_gem'
+
+# Log that initialization completed
+Legate.logger.info "Custom initialization complete"
+```
+
+The initializer runs before auto-loading, so you can set up anything your tools/agents need.
+
+## Startup Logs
+
+When auto-loading works correctly, you'll see log messages like:
+
+```
+INFO: Auto-loaded 3 custom tool file(s). Registered tools: [:echo, :calculator, ..., :greeting_tool, :weather_tool, :email_validator_tool]
+INFO: Auto-loaded 2 custom agent file(s). Registered agents: [:greeter, :data_processor]
+INFO: Synced agent 'greeter' to definition store for Web UI
+INFO: Synced agent 'data_processor' to definition store for Web UI
+```
+
+## Disabling Auto-Loading
+
+If you need to disable auto-loading (e.g., for testing):
+
+```bash
+bundle exec legate web start --no-autoload
+```
+
+## Excluding Files
+
+The auto-loader automatically skips:
+
+- Test files (`*_spec.rb`, `*_test.rb`)
+- Files in `/tools/` subdirectories when loading agents (to avoid double-loading)
+
+## Common Issues
+
+### Tool Not Appearing
+
+1. **Check the file location** - Must be in one of the scanned directories
+2. **Check registration** - File must call `Legate::GlobalToolManager.register_tool(YourTool)`
+3. **Check for errors** - Look at startup logs for load failures
+
+### Agent Not Appearing in Web UI
+
+1. **Check registration** - File must call `Legate::GlobalDefinitionRegistry.register(definition)`
+2. **Don't run the agent** - The file should only define and register, not execute
+3. **Check registration** - Agents must be registered in `GlobalDefinitionRegistry`
+
+### Load Errors
+
+If a file fails to load, you'll see:
+
+```
+WARN: Failed to load tool file /path/to/file.rb: SomeError - error message
+```
+
+Check the file for syntax errors or missing dependencies.
+
+### Wrong require_relative Paths
+
+**Don't use `require_relative` for other auto-loaded files.** Since tools load before agents, your agent can reference tools by symbol name without requiring them:
+
+```ruby
+# DON'T do this:
+require_relative '../tools/my_tool'  # Wrong!
+
+# DO this:
+a.use_tool :my_tool  # The tool is already loaded
+```
+
+## Running from Different Directories
+
+The auto-loader scans relative to the current working directory. Always run `legate web start` from your project root:
+
+```bash
+cd /path/to/your/project
+bundle exec legate web start
+```
+
+## Example Project
+
+Here's a complete example project structure:
+
+```
+my_legate_project/
+├── Gemfile
+│   # source 'https://rubygems.org'
+│   # gem 'legate'
+│
+├── .env
+│   # GOOGLE_API_KEY=your_api_key_here
+│
+├── lib/
+│   ├── tools/
+│   │   └── math_helper_tool.rb
+│   └── agents/
+│       └── math_tutor_agent.rb
+│
+└── README.md
+```
+
+**`lib/tools/math_helper_tool.rb`:**
+```ruby
+require 'legate/tool'
+
+class MathHelperTool < Legate::Tool
+  tool_description 'Explains math concepts step by step'
+  
+  parameter :problem, type: :string, required: true,
+    description: 'The math problem or concept to explain'
+  
+  private
+  
+  def perform_execution(params, context)
+    { status: :success, result: "Let me explain: #{params[:problem]}" }
+  end
+end
+
+Legate::GlobalToolManager.register_tool(MathHelperTool)
+```
+
+**`lib/agents/math_tutor_agent.rb`:**
+```ruby
+require 'legate'
+
+definition = Legate::AgentDefinition.new.define do |a|
+  a.name :math_tutor
+  a.description 'A patient math tutor that explains concepts'
+  a.instruction 'You are a patient math tutor. Use the math_helper_tool to explain concepts.'
+  a.use_tool :math_helper_tool
+  a.use_tool :calculator
+  a.model_name 'gemini-2.0-flash'
+end
+
+Legate::GlobalDefinitionRegistry.register(definition)
+```
+
+**Start the server:**
+```bash
+cd my_legate_project
+bundle install
+bundle exec legate web start
+```
+
+Your math tutor agent will automatically appear in the Web UI!
+
+## Related Documentation
+
+- [AI Code Generators](ai_code_generators) - Generate tools and agents with AI
+- [Built-in Tools](../tools/legate_built_in_tools) - Available built-in tools
+- [Agent Lifecycle](../core_concepts/legate_agent_lifecycle) - How agents work
+
+
+
+

data/public/docs/guides/configuring_agent_webhooks.md

@@ -0,0 +1,219 @@
+# Configuring an Agent for Inbound Webhooks
+
+This guide details how to configure a specific Legate Agent Definition to be triggered by external systems using the Legate's inbound webhook feature.
+
+**Prerequisite:** Ensure the Legate Webhook Listener and the Dynamic Agent Handler are enabled in your global Legate configuration. See the main [`webhooks`](./webhooks) documentation for details on setting up `Legate.configure`:
+
+```ruby
+# config/initializers/legate.rb (or similar)
+Legate.configure do |config|
+  config.webhooks.listener_enabled = true
+  config.webhooks.enable_dynamic_agent_handler = true
+  # ... other listener settings (port, base_path) ...
+end
+```
+
+With the dynamic handler enabled (defaulting to the route `/agents/:agent_name/trigger` under the configured `base_path`), you can configure individual agents to respond to requests matching this pattern.
+
+## Agent Definition Webhook Metadata
+
+To make an agent triggerable via the dynamic route, you must define specific metadata within its definition block (`Legate::Agent.define do |a| ... end`).
+
+### 1. Enable Webhook Triggering (`webhook_enabled`)
+
+This is the master switch for exposing the agent via the dynamic webhook route.
+
+*   **Required:** Yes, if you want the agent triggerable by webhook.
+*   **Type:** Boolean
+*   **Default:** `false`
+
+```ruby
+Legate::Agent.define do |a|
+  a.name :my_webhook_enabled_agent
+  # ... other config ...
+
+  a.webhook_enabled true # MUST be true
+end
+```
+
+If `webhook_enabled` is not explicitly set to `true`, requests targeting this agent via the dynamic route will result in a `404 Not Found` response.
+
+### 2. Define Payload Transformation (`webhook_transformer`)
+
+This Proc defines how the incoming webhook request payload is converted into the `user_input` expected by your agent's `run_task` method.
+
+*   **Required:** Yes, if `webhook_enabled` is `true`.
+*   **Type:** `Proc` (or Lambda)
+*   **Signature:** `lambda { |request_body| }`
+    *   `request_body`: The parsed request body (typically a Hash if the request Content-Type was `application/json`, otherwise the raw String body).
+*   **Return Value:** The `String` or `Hash` that will be passed as the `user_input` parameter to `agent.run_task` by the background worker.
+*   **Error Handling:** If the payload is invalid or missing expected data, the Proc should raise an `Legate::WebhookConfigurationError` with a descriptive message. This will cause the listener to return a `400 Bad Request`.
+
+```ruby
+Legate::Agent.define do |a|
+  # ... name, webhook_enabled true ...
+
+  a.webhook_transformer ->(request_body) do
+    # Example: Expecting JSON: { "event_type": "...", "data": { ... } }
+    event_type = request_body['event_type']
+    event_data = request_body['data']
+
+    unless event_type && event_data
+      raise Legate::WebhookConfigurationError, "Payload missing 'event_type' or 'data'."
+    end
+
+    # Construct the input for the agent task
+    "Process event '#{event_type}' with data: #{event_data.to_json}"
+  end
+end
+```
+
+### 3. Define Session ID Extraction (`webhook_session_extractor`)
+
+This Proc determines the `session_id` to use for the agent task triggered by the webhook. This allows grouping related events into the same agent conversation history.
+
+*   **Required:** Yes, if `webhook_enabled` is `true`.
+*   **Type:** `Proc` (or Lambda)
+*   **Signature:** `lambda { |request_body| }`
+    *   `request_body`: The parsed request body (Hash or String).
+*   **Return Value:** A non-empty `String` representing the `session_id`.
+*   **Error Handling:** If a suitable ID cannot be extracted, raise `Legate::WebhookConfigurationError`. This results in a `400 Bad Request`.
+
+```ruby
+Legate::Agent.define do |a|
+  # ... name, webhook_enabled true, transformer ...
+
+  a.webhook_session_extractor ->(request_body) do
+    # Example: Use a resource ID from the payload
+    resource_id = request_body.dig('resource', 'id')
+    unless resource_id.is_a?(String) && !resource_id.empty?
+      raise Legate::WebhookConfigurationError, "Missing or invalid 'resource.id' in payload."
+    end
+    "resource_session_#{resource_id}" # e.g., "resource_session_proj-abc-123"
+  end
+end
+```
+
+### 4. Configure Validation (`webhook_validator`)
+
+Specify how incoming requests should be validated for authenticity. This is highly recommended.
+
+*   **Required:** No (but strongly recommended).
+*   **Type:** `Symbol` (referencing a globally registered validator) or `Proc` (for custom logic).
+*   **Default:** `nil` (no validation applied unless a global validator is configured).
+
+**Option A: Using a Named Global Validator**
+
+First, register a validator globally (see `webhooks.md`):
+
+```ruby
+# config/initializers/legate.rb
+Legate.configure do |config|
+  # ...
+  config.webhooks.register_validator(:hmac_sha256) do |request, secret|
+    # ... HMAC validation logic using request and secret ...
+  end
+end
+```
+
+Then, reference it in the agent definition:
+
+```ruby
+Legate::Agent.define do |a|
+  # ... name, webhook_enabled true, transformer, extractor ...
+
+  a.webhook_validator :hmac_sha256 # Use the named validator
+  a.webhook_secret ENV['MY_AGENT_WEBHOOK_SECRET'] # Provide the secret for this agent
+end
+```
+
+**Option B: Providing a Custom Proc**
+
+Define the validation logic directly within the agent definition.
+
+```ruby
+Legate::Agent.define do |a|
+  # ... name, webhook_enabled true, transformer, extractor ...
+
+  a.webhook_validator ->(request, secret) do
+    # Example: Check for a specific token in headers or params
+    # 'secret' here is the value from a.webhook_secret below
+    request.params['auth_token'] == secret || request.env['HTTP_X_AUTH_TOKEN'] == secret
+  end
+  a.webhook_secret ENV['MY_AGENT_AUTH_TOKEN']
+end
+```
+
+*   **Validator Proc Signature:** `lambda { |request, secret| }`
+    *   `request`: The full Rack request object.
+    *   `secret`: The value defined by `a.webhook_secret` (or `nil`).
+*   **Return Value:** `true` if valid, `false` otherwise.
+*   **Error Handling:** If validation fails (returns `false`), the listener returns a `401 Unauthorized` response. If the validator Proc itself raises an error, a `500 Internal Server Error` is returned.
+
+### 5. Provide Validation Secret (`webhook_secret`)
+
+Provides the secret key or token needed by the configured `webhook_validator`.
+
+*   **Required:** Only if the chosen validator logic requires a secret.
+*   **Type:** `String`
+*   **Default:** `nil`
+
+```ruby
+Legate::Agent.define do |a|
+  # ... name, webhook_enabled true, transformer, extractor, validator ...
+
+  # Use environment variables for secrets!
+  a.webhook_secret ENV['MY_AGENT_WEBHOOK_SECRET']
+end
+```
+
+## Example: Fully Configured Agent
+
+```ruby
+# app/agents/github_issue_agent.rb
+require 'legate'
+require 'json'
+require 'openssl' # Needed if validator uses it
+
+Legate::Agent.define do |a|
+  a.name :github_issue_agent
+  a.description "Processes updates for GitHub issues via webhooks."
+  a.instruction "Analyze the GitHub issue event and associated data."
+  # ... add tools, model ...
+
+  # -- Webhook Settings --
+  a.webhook_enabled true
+  a.webhook_validator :hmac_sha256 # Assumes :hmac_sha256 is registered globally
+  a.webhook_secret ENV['GITHUB_ISSUE_WEBHOOK_SECRET']
+
+  a.webhook_session_extractor ->(payload) do
+    issue_id = payload.dig('issue', 'id')
+    repo_id = payload.dig('repository', 'id')
+    unless issue_id && repo_id
+      raise Legate::WebhookConfigurationError, "Missing issue or repository ID in payload."
+    end
+    "github_issue_#{repo_id}_#{issue_id}"
+  end
+
+  a.webhook_transformer ->(payload) do
+    action = payload['action']
+    issue_title = payload.dig('issue', 'title')
+    issue_body = payload.dig('issue', 'body')
+    sender = payload.dig('sender', 'login')
+
+    unless action && issue_title && sender
+      raise Legate::WebhookConfigurationError, "Missing required fields (action, issue.title, sender.login)."
+    end
+
+    # Return a hash as input for the agent task
+    {
+      event_type: "github_issue_#{action}",
+      title: issue_title,
+      body: issue_body,
+      triggered_by: sender
+    }
+  end
+end
+```
+
+By defining this metadata, your agent can securely and reliably be triggered by external webhook events, leveraging the Legate's asynchronous processing capabilities.