legate 0.1.0

data/examples/13_authentication.rb

@@ -0,0 +1,220 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example of using HTTP Bearer authentication with Legate
+#
+# This example demonstrates how to use HTTP Bearer authentication to make authenticated requests
+# to an API that requires a bearer token in the Authorization header.
+#
+# Usage:
+#   ruby examples/13_authentication.rb [token]
+
+require 'bundler/setup'
+require 'legate'
+
+# Load .env and map GEMINI_API_KEY -> GOOGLE_API_KEY (as the `legate` CLI does).
+# The library never reads .env on its own; an application must opt in.
+Legate.load_environment
+require 'legate/auth'
+require 'legate/auth/schemes/http_bearer'
+require 'json'
+
+# Check if a bearer token was provided
+bearer_token = ARGV[0] || ENV['BEARER_TOKEN']
+unless bearer_token
+  puts 'Error: Please provide a bearer token as an argument'
+  puts 'Usage: ruby examples/13_authentication.rb [token]'
+  puts 'Alternatively, set the BEARER_TOKEN environment variable'
+  exit 1
+end
+
+puts "Using Bearer Token: #{bearer_token[0..5]}..." + ('*' * 10)
+
+# Create the Auth::Credential with the bearer token
+credential = Legate::Auth::Credential.new(
+  auth_type: :http_bearer,
+  bearer_token: bearer_token
+)
+
+# Create a session service to manage authentication state
+session_service = Legate::SessionService::InMemory.new
+
+# Create a token store (optional but recommended for consistency)
+token_store = Legate::Auth::TokenStore.new(session_service: session_service)
+
+puts "\n=== Example 1: Basic HTTP Bearer Authentication ==="
+# Create an HTTP Bearer scheme
+bearer_scheme = Legate::Auth::Schemes::HTTPBearer.new
+
+# For simple non-interactive schemes like HTTP Bearer, we can use the token directly
+exchanged_token = bearer_scheme.exchange_token(credential)
+puts 'Generated token for HTTP Bearer authentication'
+
+# Example of making a request with the bearer token
+require 'excon'
+conn = Excon.new('https://httpbin.org')
+
+# Prepare request with authentication
+request = {
+  path: '/headers',
+  headers: {
+    'Accept' => 'application/json'
+  }
+}
+
+# Apply authentication
+request = bearer_scheme.apply_to_request(request, exchanged_token)
+
+begin
+  response = conn.get(request)
+
+  if response.status == 200
+    puts "Request succeeded with status: #{response.status}"
+    puts 'Headers received by server:'
+    JSON.parse(response.body)['headers'].each do |name, value|
+      puts "  #{name}: #{value}"
+    end
+  else
+    puts "Request failed with status: #{response.status}"
+    puts "Error: #{response.body}"
+  end
+rescue StandardError => e
+  puts "Request failed: #{e.message}"
+end
+
+puts "\n=== Example 2: HTTP Bearer with Expiry Simulation ==="
+# In real-world scenarios, bearer tokens often expire
+# This example simulates a token with expiry information
+
+# Create a token with expiry information
+expiring_token = Legate::Auth::ExchangedCredential.new(
+  auth_type: :http_bearer,
+  access_token: bearer_token,
+  bearer_token: bearer_token,
+  expires_in: 3600, # Token expires in 1 hour
+  token_type: 'Bearer'
+)
+
+puts "Token expires in: #{expiring_token[:expires_in]} seconds"
+
+# Example of checking token expiry
+if expiring_token.expired?
+  puts 'Token has expired and needs to be refreshed'
+else
+  remaining = expiring_token.expires_at - Time.now
+  puts "Token is still valid for #{remaining.to_i} seconds"
+end
+
+puts "\n=== Example 3: Using with the Legate Excon Middleware ==="
+
+# Create the Excon middleware for HTTP Bearer authentication
+middleware = Legate::Auth.create_middleware(
+  scheme: bearer_scheme,
+  credential: credential
+)
+
+# Create an Excon connection with the middleware
+connection = Legate::Auth.create_connection(
+  'https://httpbin.org',
+  scheme: bearer_scheme,
+  credential: credential
+)
+
+begin
+  response = connection.get(
+    path: '/headers',
+    headers: { 'Accept' => 'application/json' }
+  )
+
+  if response.status == 200
+    puts "Excon request succeeded with status: #{response.status}"
+    headers = JSON.parse(response.body)['headers']
+    puts 'Headers received by server:'
+    headers.each do |name, value|
+      puts "  #{name}: #{value}"
+    end
+  else
+    puts "Excon request failed with status: #{response.status}"
+    puts "Error: #{response.body}"
+  end
+rescue StandardError => e
+  puts "Excon request failed: #{e.message}"
+end
+
+puts "\n=== Example 4: Using with the Legate Tooling System ==="
+# Example of a tool using bearer authentication
+class BearerAuthExampleTool < Legate::Tool
+  include Legate::Tools::Base::HttpClient
+
+  tool_description 'Example tool demonstrating HTTP Bearer authentication'
+
+  parameter :endpoint,
+            type: :string,
+            description: 'API endpoint to call',
+            required: true
+
+  def initialize(options = {})
+    super()
+    @auth_scheme = options[:auth_scheme]
+    @auth_credential = options[:auth_credential]
+    setup_http_client(
+      base_url: 'https://httpbin.org',
+      options: {
+        connect_timeout: 3,
+        read_timeout: 3,
+        write_timeout: 3
+      }
+    )
+  end
+
+  private
+
+  def perform_execution(params, _context)
+    # Prepare request with authentication
+    request = {
+      method: :get,
+      path: "/#{params[:endpoint]}",
+      headers: {
+        'Accept' => 'application/json'
+      }
+    }
+
+    # Apply authentication if configured
+    request = @auth_scheme.apply_to_request(request, @auth_credential) if @auth_scheme && @auth_credential
+
+    # Make the request
+    response = http_get(
+      request[:path],
+      headers: request[:headers]
+    )
+
+    # Parse and return the response
+    data = JSON.parse(response.body)
+    {
+      status: :success,
+      endpoint: params[:endpoint],
+      headers: data['headers'],
+      data: data
+    }
+  end
+end
+
+# Create and use the example tool
+example_tool = BearerAuthExampleTool.new(
+  auth_scheme: bearer_scheme,
+  auth_credential: credential
+)
+
+puts "\nTesting bearer auth tool with endpoint: headers"
+begin
+  result = example_tool.execute(endpoint: 'headers')
+  puts 'Tool execution succeeded!'
+  puts 'Response headers:'
+  result[:headers].each do |name, value|
+    puts "  #{name}: #{value}"
+  end
+rescue StandardError => e
+  puts "Tool execution failed: #{e.message}"
+end
+
+puts "\nHTTP Bearer authentication example completed successfully!"

data/examples/14_mcp_client.rb

@@ -0,0 +1,154 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example: Using an Legate Agent as an MCP Client
+#
+# This example demonstrates how to configure an Legate::Agent to connect to an
+# external MCP server (like the @modelcontextprotocol/server-filesystem) and use its tools.
+#
+# Key Concepts:
+#   - MCP Server Configuration: Defining how to connect to the external server (e.g., via stdio).
+#   - Selected Tool Names: Explicitly telling the agent which tools from the MCP server it is allowed to use.
+#     The names provided in `selected_tool_names` MUST exactly match the tool names exposed by the specific
+#     MCP server you are connecting to (check server logs or capabilities if unsure).
+#   - Runtime Start/Stop: Managing the connection lifecycle to the MCP server.
+#   - Using External Tools: Making requests that the agent's planner can map to the available MCP tools.
+#
+# Requires:
+#   - legate gem with MCP support installed
+#   - An external MCP server running. For testing, you can use:
+#     `npx @modelcontextprotocol/server-filesystem --stdio path/to/a/directory`
+#     (Replace `path/to/a/directory` with a real directory the server can access)
+#
+# To Run:
+#   1. Start the external MCP server in one terminal (e.g., the filesystem server command above).
+#   2. Ensure the directory specified in `mcp_server_config[:args]` exists and is accessible.
+#   3. Run this script in another terminal: `bundle exec ruby examples/14_mcp_client.rb`
+#   4. Observe the logs: The agent should initialize, connect to the MCP server, and list available tools
+#      (including the ones explicitly selected via `selected_tool_names`, like `:read_file` in this example).
+#   5. The script will then attempt to run a task using the `read_file` tool from the MCP server.
+
+$LOAD_PATH.unshift File.expand_path('../lib', __dir__)
+require 'legate'
+Legate.load_environment # Handle Bundler, Dotenv, etc.
+
+require 'legate/mcp' # Ensure MCP modules are loaded
+
+# Configure Legate logger
+ENV['LEGATE_LOG_LEVEL'] = 'DEBUG'
+dirname = File.expand_path(File.dirname(File.dirname(__FILE__)))
+
+# --- 1. Define a Native Legate Tool (Optional) ---
+class NativeEchoTool < Legate::Tool
+  define_metadata(
+    name: :native_echo,
+    description: 'Echoes back the provided message (native Legate tool).',
+    parameters: {
+      message: { type: :string, required: true, description: 'Message to echo' }
+    }
+  )
+  def perform_execution(params, _context)
+    Legate.logger.info("[NativeEchoTool] Echoing: #{params[:message]}")
+    { status: :success, result: "Native echo: #{params[:message]}" }
+  end
+end
+
+# Register the native tool globally so it can be found by its name.
+Legate::GlobalToolManager.register_tool(NativeEchoTool)
+
+# --- 2. Configure the External MCP Server Connection ---
+# NOTE: Adjust the command and args based on how you run *your* external server.
+# This example assumes the filesystem server.
+# Make sure the directory path exists and is accessible!
+mcp_server_config = {
+  type: 'stdio',
+  command: 'npx', # Command to start the server
+  args: [         # Arguments for the command
+    '--',
+    '@modelcontextprotocol/server-filesystem',
+    # '--stdio',
+    dirname # <<< IMPORTANT: Change this to a real, accessible directory!
+    # Create this directory before running: mkdir /tmp/mcp_fs_test_dir
+  ]
+}
+# Check if args include a placeholder path and warn if so
+if mcp_server_config[:args].any? { |arg| arg.include?('path/to/') || arg.include?('tmp/mcp_fs_test_dir') }
+  Legate.logger.warn('MCP server config in example still uses a placeholder directory.')
+  Legate.logger.warn('Please edit examples/14_mcp_client.rb and set a real directory path in `mcp_server_config[:args]`.')
+  # Optionally exit if you want to enforce configuration
+  # exit(1)
+end
+
+# --- 3. Initialize the Legate Agent ---
+Legate.logger.info('Initializing agent...')
+
+mcp_client_agent_definition = Legate::AgentDefinition.new.define do |a|
+  a.name :mcp_client_agent
+  a.description 'An agent using native and external MCP tools.'
+  a.instruction 'You can echo messages natively and use filesystem tools from an MCP server, such as reading files.'
+  a.use_tool :native_echo # Native tool defined above
+  a.use_tool :read_file   # Tool expected from the MCP server (e.g., from server-filesystem)
+  # Add MCP server configuration
+  a.mcp_servers mcp_server_config
+  # model_name: 'gemini-pro-1.5' # Optional: Specify model via a.model_name 'gemini-pro-1.5'
+end
+
+my_agent = Legate::Agent.new(definition: mcp_client_agent_definition)
+
+# --- 4. Start the Agent Runtime ---
+# This connects to the MCP server and registers its tools.
+Legate.logger.info('Starting agent runtime...')
+my_agent.start
+Legate.logger.info("Agent started. Available tool names: #{my_agent.tool_registry.tools.keys}")
+Legate.logger.info("Full metadata: #{my_agent.available_tools_metadata.inspect}")
+
+# --- 5. Run a Task (Optional Example) ---
+# Uncomment this section to try running a task.
+# Requires setting up a session service and ensuring the external server
+# provides the tool mentioned in the user_input (e.g., `filesystem/readFile`).
+
+puts "\n--- Running Task Example ---"
+begin
+  session_service = Legate::SessionService::InMemory.new
+  session = session_service.create_session(app_name: 'mcp_client_test', user_id: 'test_user')
+  puts "Created session: #{session.id}"
+
+  # Create a dummy file for the filesystem tool to read
+  # Ensure the directory matches the one in mcp_server_config[:args]
+  dummy_file_path = "#{dirname}/hello.txt"
+  begin
+    File.write(dummy_file_path, 'Hello from Legate client example!')
+    puts "Created dummy file: #{dummy_file_path}"
+  rescue StandardError => e
+    puts "Warning: Could not create dummy file '#{dummy_file_path}': #{e.message}"
+    puts 'Filesystem tool example might fail.'
+  end
+
+  # Input asking to use a tool likely provided by the filesystem server
+  # user_input = "What files are in the #{dirname}? What are the contents of hello.txt in #{dirname}?"
+  user_input = "Read the content of the file named 'hello.txt' in #{dirname} using the filesystem tool." # <<< MODIFIED: More specific input
+  puts "User Input: #{user_input}"
+
+  final_event = my_agent.run_task(
+    session_id: session.id,
+    user_input: user_input,
+    session_service: session_service
+  )
+
+  puts 'Final Agent Event:'
+  require 'pp' # Pretty print
+  pp final_event
+rescue StandardError => e
+  puts "Error running task: #{e.message}"
+  puts e.backtrace
+end
+puts "--------------------------\n"
+
+# Delete the dummy file after the task is complete
+File.delete(dummy_file_path) if File.exist?(dummy_file_path)
+
+#--- 6. Stop the Agent Runtime ---
+# This disconnects from the MCP server.
+Legate.logger.info('Stopping agent runtime...')
+my_agent.stop
+Legate.logger.info('Agent stopped.')

data/examples/15_mcp_server.rb

@@ -0,0 +1,79 @@
+# File: examples/15_mcp_server.rb
+# frozen_string_literal: true
+
+# --- Example: Exposing an Legate::Tool via MCP using fast-mcp ---
+#
+# This script demonstrates how to wrap an existing Legate::Tool
+# (in this case, the built-in Calculator tool) and expose it
+# on an MCP server run over STDIO using the fast-mcp gem.
+#
+# Prerequisites:
+#   - Run `bundle install` in the legate directory.
+#   - Ensure the `fast-mcp` gem is available (e.g., via Gemfile path).
+#
+# Usage:
+#   1. Run this script from the legate root directory:
+#      `bundle exec ruby examples/15_mcp_server.rb`
+#   2. The script will start and wait for MCP JSON-RPC messages on STDIN.
+#   3. Use an MCP client (like `mcp-client`, `mcp-inspector`, or another script
+#      using Legate::Mcp::Client) connected to this script's STDIO to interact.
+#
+# Example Interaction (using a generic client):
+#   -> {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"capabilities":{}}}
+#   <- {"jsonrpc":"2.0","id":1,"result":{"capabilities":{},"serverInfo":{"name":"Legate Tool Server","version":"1.0"}}}
+#   -> {"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}
+#   <- {"jsonrpc":"2.0","id":2,"result":{"tools":[{"name":"calculator","description":"Performs basic arithmetic operations.","inputSchema":{"type":"object","properties":{"a":{"type":"number","description":"First operand"},"b":{"type":"number","description":"Second operand"},"op":{"type":"string","description":"Operator (+, -, *, /)"}},"required":["a","b","op"]}}]}}
+#   -> {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"calculator","arguments":{"a":10,"b":5,"op":"*"}}}
+#   <- {"jsonrpc":"2.0","id":3,"result":50.0}
+#
+# -------------------------------------------------------------
+
+$LOAD_PATH.unshift File.expand_path('../lib', __dir__)
+require 'legate'
+Legate.load_environment # Handle Bundler, Dotenv, etc.
+
+require 'legate/mcp' # Load Legate MCP modules
+require 'legate/mcp/server/legate_tool_adapter' # Load the Tool adapter
+require 'legate/tools/calculator' # Load the specific Legate tool we want to expose
+require 'fast_mcp' # Load the fast-mcp library
+
+Legate.configure do |config|
+  # Configure Legate logger level if desired (e.g., :debug for more verbose MCP logs)
+  # config.log_level = :debug
+end
+
+# --- 1. Wrap the Legate::Tool ---
+# Use the LegateToolAdapter to create a fast-mcp compatible class
+begin
+  AdaptedCalculator = Legate::Mcp::Server::LegateToolAdapter.wrap(Legate::Tools::Calculator)
+  Legate.logger.info('Successfully wrapped Legate::Tools::Calculator for MCP.')
+rescue StandardError => e
+  Legate.logger.fatal("Failed to wrap Legate Tool: #{e.message}")
+  exit(1)
+end
+
+# --- 2. Create fast-mcp Server Instance ---
+# FastMcp::Server uses STDIO transport by default when calling #start
+mcp_server = FastMcp::Server.new(
+  name: 'Legate Tool Server',
+  version: Legate::VERSION # Use Legate version
+)
+Legate.logger.info('Initialized FastMcp::Server.')
+
+# --- 3. Register the Wrapped Tool ---
+mcp_server.register_tool(AdaptedCalculator)
+Legate.logger.info("Registered adapted '#{AdaptedCalculator.tool_name}' tool with fast-mcp server.")
+
+# --- 4. Start the Server ---
+Legate.logger.info('Starting MCP server on STDIO. Waiting for requests...')
+puts '--- Legate MCP Tool Server (STDIO) Ready --- ' # Signal readiness besides logs
+begin
+  mcp_server.start # This method typically blocks, listening on STDIN
+rescue Interrupt
+  Legate.logger.info('Received interrupt, shutting down server.')
+rescue StandardError => e
+  Legate.logger.fatal("MCP server crashed: #{e.class} - #{e.message}")
+  Legate.logger.fatal(e.backtrace.join("\n"))
+ensure
+  Legate.logger.info('MCP server stopped.')
+end

data/examples/16_webhooks.rb

@@ -0,0 +1,91 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example: Sending Webhooks with HMAC Signing
+#
+# This example demonstrates how to use the built-in WebhookTool to send
+# an HMAC-signed webhook payload to an external URL.
+#
+# Setup:
+#   1. Go to https://webhook.site and copy your unique URL
+#   2. Run: WEBHOOK_URL=https://webhook.site/your-uuid WEBHOOK_SECRET=my-secret \
+#           bundle exec ruby examples/16_webhooks.rb
+#   3. Check webhook.site to see the received payload and signature header
+#
+# Run with: bundle exec ruby examples/16_webhooks.rb
+
+$LOAD_PATH.unshift(File.expand_path('../lib', __dir__))
+
+require 'legate'
+
+# Load .env and map GEMINI_API_KEY -> GOOGLE_API_KEY (as the `legate` CLI does).
+# The library never reads .env on its own; an application must opt in.
+Legate.load_environment
+require 'legate/tools/webhook_tool'
+require 'openssl'
+require 'json'
+
+puts '--- Webhook Example ---'
+
+# 1. Configuration
+webhook_url = ENV['WEBHOOK_URL']
+secret_key = ENV.fetch('WEBHOOK_SECRET', 'example-secret-key')
+
+unless webhook_url
+  puts "\nUsage: WEBHOOK_URL=https://webhook.site/your-uuid bundle exec ruby examples/16_webhooks.rb"
+  puts "\nGet a free URL at https://webhook.site — then check the site to see your payload arrive."
+  puts "You can also set WEBHOOK_SECRET (defaults to 'example-secret-key')."
+  exit(1)
+end
+
+puts "Target URL: #{webhook_url}"
+
+# 2. Build the payload
+payload_data = {
+  message: 'Hello from Legate!',
+  timestamp: Time.now.iso8601,
+  source: 'legate-webhook-example'
+}
+payload_json = payload_data.to_json
+
+# 3. Calculate HMAC signature (SHA-256)
+# The receiver can verify the payload integrity using the same secret
+calculated_signature = OpenSSL::HMAC.hexdigest('sha256', secret_key, payload_json)
+signature_header_value = "sha256=#{calculated_signature}"
+
+puts "Payload: #{payload_json}"
+puts "HMAC Signature: #{signature_header_value}"
+
+# 4. Build headers
+custom_headers = {
+  'Content-Type' => 'application/json',
+  'X-Hub-Signature-256' => signature_header_value
+}
+
+# 5. Send the webhook using the built-in WebhookTool
+webhook_tool = Legate::Tools::WebhookTool.new
+
+begin
+  puts "\nSending webhook..."
+  result = webhook_tool.execute(
+    url: webhook_url,
+    payload: payload_json,
+    headers: custom_headers
+  )
+
+  if result[:status] == :success
+    response_status = result.dig(:result, :response_status)
+    response_body = result.dig(:result, :response_body)
+    puts 'Webhook sent successfully!'
+    puts "  Response status: #{response_status}"
+    puts "  Response body: #{response_body}"
+  else
+    puts "Webhook failed: #{result[:error_message]}"
+  end
+rescue Legate::ToolError => e
+  puts "Tool error: #{e.message}"
+rescue StandardError => e
+  puts "Unexpected error: #{e.message}"
+end
+
+puts "\n--- Example Complete ---"