shared_tools 0.2.3 → 0.3.0

data/lib/shared_tools/ruby_llm/incomplete/composite_analysis_tool.rb

@@ -1,89 +0,0 @@
-# composite_analysis_tool.rb - Tool that uses other tools
-require 'ruby_llm/tool'
-
-module Tools
-  class CompositeAnalysis < RubyLLM::Tool
-    def self.name = "composite_analysis"
-
-    description <<~DESCRIPTION
-      Perform comprehensive multi-stage data analysis by orchestrating multiple specialized tools
-      to provide complete insights from various data sources. This composite tool automatically
-      determines the appropriate data fetching method (web scraping for URLs, file reading for
-      local paths), analyzes data structure and content, generates statistical insights,
-      and suggests appropriate visualizations based on the data characteristics.
-      Ideal for exploratory data analysis workflows where you need a complete picture
-      from initial data loading through final insights.
-    DESCRIPTION
-
-    param :data_source,
-          desc: <<~DESC,
-            Primary data source to analyze. Can be either a local file path or a web URL.
-            For files: Use relative or absolute paths to CSV, JSON, XML, or text files.
-            For URLs: Use complete HTTP/HTTPS URLs to accessible data endpoints or web pages.
-            The tool automatically detects the source type and uses appropriate fetching methods.
-            Examples: './data/sales.csv', '/home/user/data.json', 'https://api.example.com/data'
-          DESC
-          type: :string,
-          required: true
-
-    def execute(data_source:)
-      results = {}
-
-      begin
-        # Step 1: Fetch data using appropriate tool
-        if data_source.start_with?('http')
-          results[:data] = fetch_web_data(data_source)
-        else
-          results[:data] = read_file_data(data_source)
-        end
-
-        # Step 2: Analyze data structure
-        results[:structure] = analyze_data_structure(results[:data])
-
-        # Step 3: Generate insights
-        results[:insights] = generate_insights(results[:data], results[:structure])
-
-        # Step 4: Create visualizations if applicable
-        if results[:structure][:numeric_columns]&.any?
-          results[:visualizations] = suggest_visualizations(results[:structure])
-        end
-
-        {
-          success:     true,
-          analysis:    results,
-          data_source: data_source,
-          analyzed_at: Time.now.iso8601
-        }
-      rescue => e
-        {
-          success:        false,
-          error:          e.message,
-          data_source:    data_source,
-          partial_results: results
-        }
-      end
-    end
-
-    private
-
-    def fetch_web_data(url)
-      # Use shared web tools or custom HTTP client
-    end
-
-    def read_file_data(file_path)
-      # Use shared file tools
-    end
-
-    def analyze_data_structure(data)
-      # Implementation for data structure analysis
-    end
-
-    def generate_insights(data, structure)
-      # Implementation for insight generation
-    end
-
-    def suggest_visualizations(structure)
-      # Implementation for visualization suggestions
-    end
-  end
-end

data/lib/shared_tools/ruby_llm/incomplete/data_science_kit.rb

@@ -1,128 +0,0 @@
-# data_science_kit.rb - Analytics and ML tools
-require 'ruby_llm/tool'
-
-module Tools
-  class DataScienceKit < RubyLLM::Tool
-    def self.name = "data_science_kit"
-
-    description <<~DESCRIPTION
-      Comprehensive data science and analytics toolkit for performing statistical analysis,
-      machine learning tasks, and data exploration on various data sources. This tool provides
-      a unified interface for common data science operations including descriptive statistics,
-      correlation analysis, time series analysis, clustering algorithms, and predictive modeling.
-      It automatically handles data loading, validation, preprocessing, and result formatting.
-      Supports multiple data formats and provides detailed analysis results with visualizations
-      recommendations and statistical significance testing where applicable.
-    DESCRIPTION
-
-    param :analysis_type,
-          desc: <<~DESC,
-            Type of data science analysis to perform:
-            - 'statistical_summary': Descriptive statistics, distributions, outlier detection
-            - 'correlation_analysis': Correlation matrices, feature relationships, dependency analysis
-            - 'time_series': Trend analysis, seasonality detection, forecasting
-            - 'clustering': K-means, hierarchical clustering, cluster analysis
-            - 'prediction': Regression analysis, classification, predictive modeling
-            Each analysis type requires specific data formats and optional parameters.
-          DESC
-          type: :string,
-          required: true,
-          enum: ["statistical_summary", "correlation_analysis", "time_series", "clustering", "prediction"]
-
-    param :data_source,
-          desc: <<~DESC,
-            Data source specification for analysis. Can be:
-            - File path: Relative or absolute path to CSV, JSON, Excel, or Parquet files
-            - Database query: SQL SELECT statement for database-sourced data
-            - API endpoint: HTTP URL for REST API data sources
-            The tool automatically detects the format and applies appropriate parsing.
-            Examples: './sales_data.csv', 'SELECT * FROM transactions', 'https://api.company.com/data'
-          DESC
-          type: :string,
-          required: true
-
-    param :parameters,
-          desc: <<~DESC,
-            Hash of analysis-specific parameters and configuration options:
-            - statistical_summary: confidence_level, include_quartiles, outlier_method
-            - correlation_analysis: method (pearson/spearman), significance_level
-            - time_series: date_column, value_column, frequency, forecast_periods
-            - clustering: n_clusters, algorithm (kmeans/hierarchical), distance_metric
-            - prediction: target_column, feature_columns, model_type, validation_split
-            Default empty hash uses standard parameters for each analysis type.
-          DESC
-          type: :hash,
-          default: {}
-
-    def execute(analysis_type:, data_source:, parameters: {})
-      begin
-        # Load and validate data
-        data = load_data(data_source)
-        validate_data_for_analysis(data, analysis_type)
-
-        # Perform analysis
-        result = case analysis_type
-        when "statistical_summary"
-          generate_statistical_summary(data, parameters)
-        when "correlation_analysis"
-          perform_correlation_analysis(data, parameters)
-        when "time_series"
-          analyze_time_series(data, parameters)
-        when "clustering"
-          perform_clustering(data, parameters)
-        when "prediction"
-          generate_predictions(data, parameters)
-        end
-
-        {
-          success:      true,
-          analysis_type: analysis_type,
-          result:       result,
-          data_summary: summarize_data(data),
-          analyzed_at:  Time.now.iso8601
-        }
-      rescue => e
-        {
-          success:     false,
-          error:       e.message,
-          analysis_type: analysis_type,
-          data_source: data_source
-        }
-      end
-    end
-
-    private
-
-    def load_data(source)
-      # Implementation for data loading from various sources
-    end
-
-    def validate_data_for_analysis(data, analysis_type)
-      # Implementation for data validation
-    end
-
-    def generate_statistical_summary(data, parameters)
-      # Implementation for statistical summary
-    end
-
-    def perform_correlation_analysis(data, parameters)
-      # Implementation for correlation analysis
-    end
-
-    def analyze_time_series(data, parameters)
-      # Implementation for time series analysis
-    end
-
-    def perform_clustering(data, parameters)
-      # Implementation for clustering
-    end
-
-    def generate_predictions(data, parameters)
-      # Implementation for prediction
-    end
-
-    def summarize_data(data)
-      # Implementation for data summary
-    end
-  end
-end

data/lib/shared_tools/ruby_llm/incomplete/database_query_tool.rb

@@ -1,100 +0,0 @@
-# database_query_tool.rb - Database interaction example
-require 'ruby_llm/tool'
-require 'sequel'
-
-module Tools
-  class DatabaseQuery < RubyLLM::Tool
-    def self.name = "database_query"
-
-    description <<~DESCRIPTION
-      Execute safe, read-only database queries with automatic connection management and security controls.
-      This tool is designed for secure data retrieval operations only, restricting access to SELECT statements
-      to prevent any data modification. It includes automatic connection pooling, query result limiting,
-      and comprehensive error handling. The tool supports multiple database configurations through
-      environment variables and ensures all connections are properly closed after use.
-      Perfect for AI-assisted data analysis and reporting workflows where read-only access is required.
-    DESCRIPTION
-
-    param :query,
-          desc: <<~DESC,
-            SQL SELECT query to execute against the database. Only SELECT statements are permitted
-            for security reasons - INSERT, UPDATE, DELETE, and DDL statements will be rejected.
-            The query should be well-formed SQL appropriate for the target database system.
-            Examples: 'SELECT * FROM users WHERE active = true', 'SELECT COUNT(*) FROM orders'.
-            Table and column names should match the database schema exactly.
-          DESC
-          type: :string,
-          required: true
-
-    param :database,
-          desc: <<~DESC,
-            Database configuration name to use for the connection. This corresponds to environment
-            variables like DATABASE_URL, STAGING_DATABASE_URL, etc. The tool will look for
-            an environment variable named {DATABASE_NAME}_DATABASE_URL (uppercase).
-            Default is 'default' which looks for DEFAULT_DATABASE_URL environment variable.
-            Common values: 'default', 'staging', 'analytics', 'reporting'.
-          DESC
-          type: :string,
-          default: "default"
-
-    param :limit,
-          desc: <<~DESC,
-            Maximum number of rows to return from the query to prevent excessive memory usage
-            and long response times. The tool automatically adds a LIMIT clause if one is not
-            present in the original query. Set to a reasonable value based on expected data size.
-            Minimum: 1, Maximum: 10000, Default: 100. For large datasets, consider using
-            pagination or more specific WHERE clauses.
-          DESC
-          type: :integer,
-          default: 100
-
-    def execute(query:, database: "default", limit: 100)
-      begin
-        # Security: Only allow SELECT queries
-        normalized_query = query.strip.downcase
-        unless normalized_query.start_with?('select')
-          raise "Only SELECT queries are allowed for security"
-        end
-
-        db = connect_to_database(database)
-        limited_query = add_limit_to_query(query, limit)
-
-        results = db[limited_query].all
-
-        {
-          success:     true,
-          query:       limited_query,
-          row_count:   results.length,
-          data:        results,
-          database:    database,
-          executed_at: Time.now.iso8601
-        }
-      rescue => e
-        {
-          success:  false,
-          error:    e.message,
-          query:    query,
-          database: database
-        }
-      ensure
-        db&.disconnect
-      end
-    end
-
-    private
-
-    def connect_to_database(database_name)
-      # Implementation depends on your database setup
-      connection_string = ENV["#{database_name.upcase}_DATABASE_URL"]
-      raise "Database connection not configured for #{database_name}" unless connection_string
-
-      Sequel.connect(connection_string)
-    end
-
-    def add_limit_to_query(query, limit)
-      # Add LIMIT clause if not present
-      query += " LIMIT #{limit}" unless query.downcase.include?('limit')
-      query
-    end
-  end
-end

data/lib/shared_tools/ruby_llm/incomplete/devops_toolkit.rb

@@ -1,112 +0,0 @@
-# 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)
-      # Implementation for rollback logic
-    end
-
-    def perform_health_check(environment, options)
-      # Implementation for health check logic
-    end
-
-    def analyze_logs(environment, options)
-      # Implementation for log analysis logic
-    end
-
-    def collect_metrics(environment, options)
-      # Implementation for metric collection logic
-    end
-  end
-end

data/lib/shared_tools/ruby_llm/incomplete/error_handling_tool.rb

@@ -1,109 +0,0 @@
-# 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)
-      # Check all preconditions before execution
-    end
-
-    def perform_operation(params)
-      # Main operation logic with retry mechanism
-      retry_count = 0
-      max_retries = 3
-
-      begin
-        # 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
-      # Clean up any allocated resources
-    end
-  end
-end

data/lib/shared_tools/ruby_llm/incomplete/secure_tool_template.rb

@@ -1,117 +0,0 @@
-# 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
-      # Check user permissions
-      # Validate environment access
-      # Verify resource limits
-    end
-
-    def check_rate_limits
-      # Implement rate limiting logic
-    end
-
-    def log_tool_usage(input)
-      # Audit logging for compliance
-    end
-
-    def execute_with_timeout(input, timeout: 30)
-      # Implement timeout mechanism
-      Timeout::timeout(timeout) do
-        # Actual tool logic here
-      end
-    end
-
-    def sanitize_output(output)
-      # Remove sensitive information from output
-      # Validate output format
-      output
-    end
-
-    def log_security_violation(error, input)
-      # Log security violations for monitoring
-    end
-  end
-end