aia 0.9.8 → 0.9.10

data/examples/tools/incomplete/devops_toolkit.rb

@@ -0,0 +1,112 @@
+# devops_toolkit.rb - System administration tools
+require 'ruby_llm/tool'
+require 'securerandom'
+
+module Tools
+  class DevOpsToolkit < RubyLLM::Tool
+    def self.name = "devops_toolkit"
+
+    description <<~DESCRIPTION
+      Comprehensive DevOps and system administration toolkit for managing application deployments,
+      monitoring system health, and performing operational tasks across different environments.
+      This tool provides secure, audited access to common DevOps operations including deployments,
+      rollbacks, health checks, log analysis, and metrics collection. It includes built-in safety
+      mechanisms for production environments, comprehensive logging for compliance, and support
+      for multiple deployment environments. All operations are logged and require appropriate
+      permissions and confirmations for sensitive environments.
+    DESCRIPTION
+
+    param :operation,
+          desc: <<~DESC,
+            Specific DevOps operation to perform:
+            - 'deploy': Deploy application code to the specified environment
+            - 'rollback': Revert to the previous stable deployment version
+            - 'health_check': Perform comprehensive health and status checks
+            - 'log_analysis': Analyze application and system logs for issues
+            - 'metric_collection': Gather and report system and application metrics
+            Each operation has specific requirements and safety checks.
+          DESC
+          type: :string,
+          required: true,
+          enum: ["deploy", "rollback", "health_check", "log_analysis", "metric_collection"]
+
+    param :environment,
+          desc: <<~DESC,
+            Target environment for the DevOps operation:
+            - 'development': Local or shared development environment (minimal restrictions)
+            - 'staging': Pre-production environment for testing (moderate restrictions)
+            - 'production': Live production environment (maximum restrictions and confirmations)
+            Production operations require explicit confirmation via the 'production_confirmed' option.
+          DESC
+          type: :string,
+          default: "staging",
+          enum: ["development", "staging", "production"]
+
+    param :options,
+          desc: <<~DESC,
+            Hash of operation-specific options and parameters:
+            - For deploy: version, branch, rollback_on_failure, notification_channels
+            - For rollback: target_version, confirmation_required
+            - For health_check: services_to_check, timeout_seconds
+            - For log_analysis: time_range, log_level, search_patterns
+            - For metric_collection: metric_types, time_window, output_format
+            Production operations require 'production_confirmed: true' for safety.
+          DESC
+          type: :hash,
+          default: {}
+
+    def execute(operation:, environment: "staging", options: {})
+      # Security: Require explicit production confirmation
+      if environment == "production" && !options[:production_confirmed]
+        return {
+          success:         false,
+          error:           "Production operations require explicit confirmation",
+          required_option: "production_confirmed: true"
+        }
+      end
+
+      case operation
+      when "deploy"
+        perform_deployment(environment, options)
+      when "rollback"
+        perform_rollback(environment, options)
+      when "health_check"
+        perform_health_check(environment, options)
+      when "log_analysis"
+        analyze_logs(environment, options)
+      when "metric_collection"
+        collect_metrics(environment, options)
+      end
+    end
+
+    private
+
+    def perform_deployment(environment, options)
+      # Implementation for deployment logic
+      {
+        success:       true,
+        operation:     "deploy",
+        environment:   environment,
+        deployed_at:   Time.now.iso8601,
+        deployment_id: SecureRandom.uuid,
+        details:       "Deployment completed successfully"
+      }
+    end
+
+    def perform_rollback(environment, options)
+      # TODO: Implementation for rollback logic
+    end
+
+    def perform_health_check(environment, options)
+      # TODO: Implementation for health check logic
+    end
+
+    def analyze_logs(environment, options)
+      # TODO: Implementation for log analysis logic
+    end
+
+    def collect_metrics(environment, options)
+      # TODO: Implementation for metric collection logic
+    end
+  end
+end

data/examples/tools/incomplete/error_handling_tool.rb

@@ -0,0 +1,109 @@
+# error_handling_tool.rb - Comprehensive error handling
+require 'ruby_llm/tool'
+require 'securerandom'
+
+module Tools
+  class RobustTool < RubyLLM::Tool
+    def self.name = 'robust_tool'
+
+    description <<~DESCRIPTION
+      Reference tool demonstrating comprehensive error handling patterns and resilience strategies
+      for robust tool development. This tool showcases best practices for handling different
+      types of errors including validation errors, network failures, authorization issues,
+      and general exceptions. It implements retry mechanisms with exponential backoff,
+      proper resource cleanup, detailed error categorization, and user-friendly error messages.
+      Perfect as a template for building production-ready tools that need to handle
+      various failure scenarios gracefully.
+    DESCRIPTION
+
+    def execute(**params)
+      begin
+        validate_preconditions(params)
+        result = perform_operation(params)
+        validate_postconditions(result)
+
+        {
+          success:  true,
+          result:   result,
+          metadata: operation_metadata
+        }
+      rescue ValidationError => e
+        handle_validation_error(e, params)
+      rescue NetworkError => e
+        handle_network_error(e, params)
+      rescue AuthorizationError => e
+        handle_authorization_error(e, params)
+      rescue StandardError => e
+        handle_general_error(e, params)
+      ensure
+        cleanup_resources
+      end
+    end
+
+    private
+
+    def validate_preconditions(params)
+      # TODO: Check all preconditions before execution
+    end
+
+    def perform_operation(params)
+      # TODO: Main operation logic with retry mechanism
+      retry_count = 0
+      max_retries = 3
+
+      begin
+        # TODO: Operation implementation
+      rescue RetryableError => e
+        retry_count += 1
+        if retry_count <= max_retries
+          sleep(2 ** retry_count) # Exponential backoff
+          retry
+        else
+          raise e
+        end
+      end
+    end
+
+    def handle_validation_error(error, params)
+      {
+        success:         false,
+        error_type:      "validation",
+        error:           error.message,
+        suggestions:     error.suggestions,
+        provided_params: params.keys
+      }
+    end
+
+    def handle_network_error(error, params)
+      {
+        success:         false,
+        error_type:      "network",
+        error:           "Network operation failed",
+        retry_suggested: true,
+        retry_after:     30
+      }
+    end
+
+    def handle_authorization_error(error, params)
+      {
+        success:          false,
+        error_type:       "authorization",
+        error:            "Access denied",
+        documentation_url: "https://docs.example.com/auth"
+      }
+    end
+
+    def handle_general_error(error, params)
+      {
+        success:           false,
+        error_type:        "general",
+        error:             error.message,
+        support_reference: SecureRandom.uuid
+      }
+    end
+
+    def cleanup_resources
+      # TODO: Clean up any allocated resources
+    end
+  end
+end

data/examples/tools/{pdf_page_reader.rb → incomplete/pdf_page_reader.rb}

@@ -6,6 +6,8 @@ require 'pdf-reader'
 
 
 class PdfPageReader < RubyLLM::Tool
+  def self.name = 'pdf_page_reader'
+
   # TODO: make the path to the pdf document a parameter
   DOC = PDF::Reader.new('docs/big-doc.pdf')
 

data/examples/tools/incomplete/secure_tool_template.rb

@@ -0,0 +1,117 @@
+# secure_tool_template.rb - Security best practices
+require 'ruby_llm/tool'
+require 'timeout'
+
+module Tools
+  class SecureTool < RubyLLM::Tool
+    def self.name = 'secure_tool'
+
+    description <<~DESCRIPTION
+      Template tool demonstrating comprehensive security best practices for safe tool development.
+      This tool serves as a reference implementation for secure tool design, including input
+      validation, output sanitization, permission checks, rate limiting, audit logging,
+      timeout mechanisms, and proper error handling. It provides a complete security framework
+      that can be adapted for other tools that handle sensitive data or perform privileged
+      operations. All security violations are logged for monitoring and compliance purposes.
+    DESCRIPTION
+
+    # Input validation
+    param :user_input,
+          desc: <<~DESC,
+            User-provided input string that will be processed with comprehensive security validation.
+            Input is automatically sanitized and validated against multiple security criteria:
+            - Maximum length of 1000 characters to prevent buffer overflow attacks
+            - Character whitelist allowing only alphanumeric, spaces, hyphens, underscores, and dots
+            - Automatic removal of potentially dangerous characters and sequences
+            - Rate limiting to prevent abuse and denial-of-service attacks
+            All input validation failures are logged for security monitoring.
+          DESC
+          type: :string,
+          required: true,
+          validator: ->(value) {
+            # Custom validation logic
+            raise "Input too long" if value.length > 1000
+            raise "Invalid characters" unless value.match?(/\A[a-zA-Z0-9\s\-_\.]+\z/)
+            true
+          }
+
+    def execute(user_input:)
+      begin
+        # 1. Sanitize inputs
+        sanitized_input = sanitize_input(user_input)
+
+        # 2. Validate permissions
+        validate_permissions
+
+        # 3. Rate limiting
+        check_rate_limits
+
+        # 4. Audit logging
+        log_tool_usage(sanitized_input)
+
+        # 5. Execute with timeout
+        result = execute_with_timeout(sanitized_input)
+
+        # 6. Sanitize outputs
+        sanitized_result = sanitize_output(result)
+
+        {
+          success: true,
+          result:  sanitized_result,
+          executed_at: Time.now.iso8601
+        }
+      rescue SecurityError => e
+        log_security_violation(e, user_input)
+        {
+          success: false,
+          error:   "Security violation: Access denied",
+          violation_logged: true
+        }
+      rescue => e
+        {
+          success: false,
+          error:   "Tool execution failed: #{e.message}"
+        }
+      end
+    end
+
+    private
+
+    def sanitize_input(input)
+      # Remove potentially dangerous characters
+      # Validate against whitelist
+      input.gsub(/[^\w\s\-\.]/, '')
+    end
+
+    def validate_permissions
+      # TODO: Check user permissions
+      #       Validate environment access
+      #       Verify resource limits
+    end
+
+    def check_rate_limits
+      # TODO: Implement rate limiting logic
+    end
+
+    def log_tool_usage(input)
+      # TODO: Audit logging for compliance
+    end
+
+    def execute_with_timeout(input, timeout: 30)
+      # TODO: Implement timeout mechanism
+      Timeout::timeout(timeout) do
+        # TODO: Actual tool logic here
+      end
+    end
+
+    def sanitize_output(output)
+      # TODO: Remove sensitive information from output
+      #       Validate output format
+      output
+    end
+
+    def log_security_violation(error, input)
+      # TODO: Log security violations for monitoring
+    end
+  end
+end

data/examples/tools/incomplete/weather_tool.rb

@@ -0,0 +1,110 @@
+# weather_tool.rb - API integration example
+require 'ruby_llm/tool'
+require 'net/http'
+require 'json'
+
+module Tools
+  class WeatherTool < RubyLLM::Tool
+    def self.name = 'weather_tool'
+
+    description <<~DESCRIPTION
+      Retrieve comprehensive current weather information for any city worldwide using the OpenWeatherMap API.
+      This tool provides real-time weather data including temperature, atmospheric conditions, humidity,
+      and wind information. It supports multiple temperature units and can optionally include extended
+      forecast data. The tool requires a valid OpenWeatherMap API key to be configured in the
+      OPENWEATHER_API_KEY environment variable. All weather data is fetched in real-time and includes
+      timestamps for accuracy verification.
+    DESCRIPTION
+
+    param :city,
+          desc: <<~DESC,
+            Name of the city for weather lookup. Can include city name only (e.g., 'London')
+            or city with country code for better accuracy (e.g., 'London,UK' or 'Paris,FR').
+            For cities with common names in multiple countries, including the country code
+            is recommended to ensure accurate results. The API will attempt to find the
+            closest match if an exact match is not found.
+          DESC
+          type: :string,
+          required: true
+
+    param :units,
+          desc: <<~DESC,
+            Temperature unit system for the weather data. Options are:
+            - 'metric': Temperature in Celsius, wind speed in m/s, pressure in hPa
+            - 'imperial': Temperature in Fahrenheit, wind speed in mph, pressure in hPa
+            - 'kelvin': Temperature in Kelvin (scientific standard), wind speed in m/s
+            Default is 'metric' which is most commonly used internationally.
+          DESC
+          type: :string,
+          default: "metric",
+          enum: ["metric", "imperial", "kelvin"]
+
+    param :include_forecast,
+          desc: <<~DESC,
+            Boolean flag to include a 3-day weather forecast in addition to current conditions.
+            When set to true, the response will include forecast data with daily high/low temperatures,
+            precipitation probability, and general weather conditions for the next three days.
+            This requires additional API calls and may increase response time slightly.
+          DESC
+          type: :boolean,
+          default: false
+
+    def execute(city:, units: "metric", include_forecast: false)
+      begin
+        api_key = ENV['OPENWEATHER_API_KEY']
+        raise "OpenWeather API key not configured" unless api_key
+
+        current_weather = fetch_current_weather(city, units, api_key)
+        result = {
+          success:   true,
+          city:      city,
+          current:   current_weather,
+          units:     units,
+          timestamp: Time.now.iso8601
+        }
+
+        if include_forecast
+          forecast_data = fetch_forecast(city, units, api_key)
+          result[:forecast] = forecast_data
+        end
+
+        result
+      rescue => e
+        {
+          success:    false,
+          error:      e.message,
+          city:       city,
+          suggestion: "Verify city name and API key configuration"
+        }
+      end
+    end
+
+    private
+
+    def fetch_current_weather(city, units, api_key)
+      uri = URI("https://api.openweathermap.org/data/2.5/weather")
+      params = {
+        q:     city,
+        appid: api_key,
+        units: units
+      }
+      uri.query = URI.encode_www_form(params)
+
+      response = Net::HTTP.get_response(uri)
+      raise "Weather API error: #{response.code}" unless response.code == '200'
+
+      data = JSON.parse(response.body)
+      {
+        temperature: data['main']['temp'],
+        description: data['weather'][0]['description'],
+        humidity:    data['main']['humidity'],
+        wind_speed:  data['wind']['speed']
+      }
+    end
+
+    def fetch_forecast(city, units, api_key)
+      # TODO: Implementation for forecast data
+      #       Similar pattern to current weather
+    end
+  end
+end

data/examples/tools/incomplete/workflow_manager_tool.rb

@@ -0,0 +1,145 @@
+# workflow_manager_tool.rb - Managing state across tool invocations
+require 'ruby_llm/tool'
+require 'securerandom'
+require 'json'
+
+module Tools
+  class WorkflowManager < RubyLLM::Tool
+    def self.name = 'workflow_manager'
+
+    description <<~DESCRIPTION
+      Manage complex multi-step workflows with persistent state tracking across tool invocations.
+      This tool enables the creation and management of stateful workflows that can span multiple
+      AI interactions and tool calls. It provides workflow initialization, step-by-step execution,
+      status monitoring, and completion tracking. Each workflow maintains its state in persistent
+      storage, allowing for resumption of long-running processes and coordination between
+      multiple tools and AI interactions. Perfect for complex automation tasks that require
+      multiple stages and decision points.
+    DESCRIPTION
+
+    param :action,
+          desc: <<~DESC,
+            Workflow management action to perform:
+            - 'start': Initialize a new workflow with initial data and return workflow ID
+            - 'step': Execute the next step in an existing workflow using provided step data
+            - 'status': Check the current status and progress of an existing workflow
+            - 'complete': Mark a workflow as finished and clean up associated resources
+            Each action requires different combinations of the other parameters.
+          DESC
+          type: :string,
+          required: true,
+          enum: ["start", "step", "status", "complete"]
+
+    param :workflow_id,
+          desc: <<~DESC,
+            Unique identifier for an existing workflow. Required for 'step', 'status', and 'complete'
+            actions. This ID is returned when starting a new workflow and should be used for all
+            subsequent operations on that workflow. The ID is a UUID string that ensures
+            uniqueness across all workflow instances.
+          DESC
+          type: :string
+
+    param :step_data,
+          desc: <<~DESC,
+            Hash containing data and parameters specific to the current workflow step.
+            For 'start' action: Initial configuration and parameters for the workflow.
+            For 'step' action: Input data, parameters, and context needed for the next step.
+            The structure depends on the specific workflow type and current step requirements.
+            Can include nested hashes, arrays, and any JSON-serializable data types.
+          DESC
+          type: :hash,
+          default: {}
+
+    def execute(action:, workflow_id: nil, step_data: {})
+      case action
+      when "start"
+        start_workflow(step_data)
+      when "step"
+        process_workflow_step(workflow_id, step_data)
+      when "status"
+        get_workflow_status(workflow_id)
+      when "complete"
+        complete_workflow(workflow_id)
+      else
+        { success: false, error: "Unknown action: #{action}" }
+      end
+    end
+
+    private
+
+    def start_workflow(initial_data)
+      workflow_id = SecureRandom.uuid
+      workflow_state = {
+        id:         workflow_id,
+        status:     "active",
+        steps:      [],
+        created_at: Time.now.iso8601,
+        data:       initial_data
+      }
+
+      save_workflow_state(workflow_id, workflow_state)
+
+      {
+        success:      true,
+        workflow_id:  workflow_id,
+        status:       "started",
+        next_actions: suggested_next_actions(initial_data)
+      }
+    end
+
+    def process_workflow_step(workflow_id, step_data)
+      workflow_state = load_workflow_state(workflow_id)
+      return { success: false, error: "Workflow not found" } unless workflow_state
+
+      step = {
+        step_number:  workflow_state[:steps].length + 1,
+        data:         step_data,
+        processed_at: Time.now.iso8601,
+        result:       process_step_logic(step_data, workflow_state)
+      }
+
+      workflow_state[:steps] << step
+      workflow_state[:updated_at] = Time.now.iso8601
+
+      save_workflow_state(workflow_id, workflow_state)
+
+      {
+        success:         true,
+        workflow_id:     workflow_id,
+        step_completed:  step,
+        workflow_status: workflow_state[:status],
+        next_actions:    suggested_next_actions(workflow_state)
+      }
+    end
+
+    def save_workflow_state(workflow_id, state)
+      # TODO: Implementation for state persistence
+      #       Could use files, database, or memory store
+      File.write(".workflow_#{workflow_id}.json", state.to_json)
+    end
+
+    def load_workflow_state(workflow_id)
+      # TODO: Implementation for state loading
+      file_path = ".workflow_#{workflow_id}.json"
+      return nil unless File.exist?(file_path)
+
+      JSON.parse(File.read(file_path), symbolize_names: true)
+    end
+
+    def get_workflow_status(workflow_id)
+      # TODO: Implementation for status retrieval
+    end
+
+    def complete_workflow(workflow_id)
+      # TODO: Implementation for workflow completion
+    end
+
+    def suggested_next_actions(workflow_state)
+      # TODO: Implementation for suggesting next actions
+    end
+
+    def process_step_logic(step_data, workflow_state)
+      # TODO: Implementation for processing step logic
+    end
+  end
+end

data/examples/tools/list_files.rb

@@ -5,6 +5,8 @@ require "ruby_llm/tool"
 
 module Tools
   class ListFiles < RubyLLM::Tool
+    def self.name = "list_files"
+
     description "List files and directories at a given path. If no path is provided, lists files in the current directory."
     param :path, desc: "Optional relative path to list files from. Defaults to current directory if not provided."
 

data/examples/tools/mcp/README.md

@@ -0,0 +1 @@
+These tools require the ruby_llm-mcp version 0.5.0+ gem

data/examples/tools/mcp/github_mcp_server.rb

@@ -0,0 +1,41 @@
+# shared_tools/ruby_llm/mcp/github_mcp_server.rb
+# brew install github_mcp_server
+
+require "ruby_llm/mcp"
+
+RubyLLM::MCP.add_client(
+  name: "github-mcp-server",
+  transport_type: :stdio,
+  config: {
+    command: "/opt/homebrew/bin/github-mcp-server", # brew install github-mcp-server
+    args: %w[stdio],
+    env: { "GITHUB_PERSONAL_ACCESS_TOKEN" => ENV.fetch("GITHUB_PERSONAL_ACCESS_TOKEN") },
+  },
+)
+
+
+__END__
+
+
+A GitHub MCP server that handles various tools and resources.
+
+Usage:
+  server [command]
+
+Available Commands:
+  completion  Generate the autocompletion script for the specified shell
+  help        Help about any command
+  stdio       Start stdio server
+
+Flags:
+      --dynamic-toolsets         Enable dynamic toolsets
+      --enable-command-logging   When enabled, the server will log all command requests and responses to the log file
+      --export-translations      Save translations to a JSON file
+      --gh-host string           Specify the GitHub hostname (for GitHub Enterprise etc.)
+  -h, --help                     help for server
+      --log-file string          Path to log file
+      --read-only                Restrict the server to read-only operations
+      --toolsets strings         An optional comma separated list of groups of tools to allow, defaults to enabling all (default [all])
+  -v, --version                  version for server
+
+Use "server [command] --help" for more information about a command.

data/examples/tools/mcp/imcp.rb

@@ -0,0 +1,15 @@
+# shared_tools/ruby_llm/mcp/imcp.rb
+# iMCP is a MacOS program that provides access to notes,calendar,contacts, etc.
+# See: https://github.com/loopwork/iMCP
+# brew install --cask loopwork/tap/iMCP
+#
+
+require 'ruby_llm/mcp'
+
+RubyLLM::MCP.add_client(
+  name: "imcp-server",
+  transport_type: :stdio,
+  config: {
+    command: "/Applications/iMCP.app/Contents/MacOS/imcp-server 2> /dev/null"
+  }
+)

data/examples/tools/read_file.rb

@@ -4,6 +4,8 @@
 
 module Tools
   class ReadFile < RubyLLM::Tool
+    def self.name = 'read_file'
+
     description "Read the contents of a given relative file path. Use this when you want to see what's inside a file. Do not use this with directory names."
     param :path, desc: "The relative path of a file in the working directory."
 

data/examples/tools/run_shell_command.rb

@@ -5,6 +5,8 @@ require "ruby_llm/tool"
 
 module Tools
   class RunShellCommand < RubyLLM::Tool
+    def self.name = 'run_shell_command'
+
     description "Execute a linux shell command"
     param :command, desc: "The command to execute"