aia 0.9.7 → 0.9.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 21134c8c9fa3664309baf0c3d1bce2857dffd3dd1ad8c554c7cb15ac48b57634
-  data.tar.gz: 46f64bdbefe73eede9add530bad3a4957f6b7033706a1d1daf5aa6bef1fb6084
+  metadata.gz: e7e11bfdcf25a6688acbb7f283673964f7b24cd982fef2af374396b166eb3ede
+  data.tar.gz: b826a553b444d212949a4b6ef24fcdbd5d0674328e5e294a5981caccfa5aa239
 SHA512:
-  metadata.gz: dc1273757619b1962986e1dfac94b8d10b2c493ff0cf0d01d0938c65a902700d96484d42e661770328a4f6f904a1265f6a136964fb8c31218ed22135fed806dc
-  data.tar.gz: edc7124424b74f7d167a78635abd7302eb05cd4208058947dd8700e5e05c1200eba47346d1f0beea0ed9ea37a5875ca7cb585d40752dbcf88c64063dc278e398
+  metadata.gz: f775c09be01764332b7551830f5a9ff801d957c3965a0ae4ba4d83b640533503a10b0f4c991482c8ee768a516be8f8f29db9ed73e3ccd08998121be3aecc68a3
+  data.tar.gz: 8cbd963323424416b75cdb0e33e2c1ad71c26b956a8ee2c5621f5b654552cb88eb0bcd3962b6af34078ce52b760315c7737818c0cbe5fee8c30a89855358d020

data/.config/tocer/configuration.yml

@@ -1,5 +1,6 @@
 label: "## Table of Contents"
 patterns:
   - "README.md"
-  - doc/*.md
+  - docs/*.md
+  - docs/draft_articles/*.md
 root_dir: "."

data/.version

@@ -1 +1 @@
-0.9.7
+0.9.9

data/CHANGELOG.md

@@ -1,10 +1,24 @@
 # Changelog
 ## [Unreleased]
 
-### [0.9.8] WIP
+### [0.9.9] WIP
+- refactored the Session and Config classes into more testable method_missing
+- updated the test suire for both the Session and Config classes
+- added support for MCP servers coming into AIA via the shared_tools gem
+- added +RubyLLM::MCP.support_complex_parameters! to patch ruby_llm gem until such time as it supports the more complex optional parameters in tool calls
+- added an examples/tools/mcp directory with 2 MCP client definitions
+- updated to ruby_llm-mcp gem version 0.5.1
+- //model directive now dumps full model details
+- //available_models now has context window size and capabilities for each model returned
 
 ## Released
 
+### [0.9.8] 2025-06-25
+- fixing an issue with pipelined prompts
+- now showing the complete modality of the model on the processing line.
+- changed -p option from prompts_dir to pipeline
+- found problem with simple cov and deep cov w/r/t their reported test coverage; they have problems with heredoc and complex conditionals.
+
 ### [0.9.7] 2025-06-20
 
 - **NEW FEATURE**: Added `--available_models` CLI option to list all available AI models

data/README.md

@@ -358,6 +358,33 @@ Your prompt content here...
 Analyze the above information and provide insights.
 ```
 
+#### Custom Directive Examples
+
+You can extend AIA with custom directives by creating Ruby files that define new directive methods:
+
+```ruby
+# examples/directives/ask.rb
+module AIA
+  class DirectiveProcessor
+    private
+    desc "A meta-prompt to LLM making its response available as part of the primary prompt"
+    def ask(args, context_manager=nil)
+      meta_prompt = args.empty? ? "What is meta-prompting?" : args.join(' ')
+      AIA.config.client.chat(meta_prompt)
+    end
+  end
+end
+```
+
+**Usage:** Use the --tools option to specific a specific directive file or a directory full of files
+```bash
+# Load custom directive
+aia --tools examples/directives/ask.rb --chat
+
+# Use the results of the custom directive as input to a prompt
+//ask gather the latest closing data for the DOW, NASDAQ, and S&P 500
+```
+
 ### Shell Integration
 
 AIA automatically processes shell patterns in prompts:
@@ -499,6 +526,22 @@ aia --tools ~/tools/ --rejected_tools deprecated
 - API integrations
 - Data processing utilities
 
+**MCP Client Examples** (see `examples/tools/mcp/` directory):
+
+AIA supports Model Context Protocol (MCP) clients for extended functionality:
+
+```bash
+# GitHub MCP Server (requires: brew install github-mcp-server)
+# Set GITHUB_PERSONAL_ACCESS_TOKEN environment variable
+aia --tools examples/tools/mcp/github_mcp_server.rb --chat
+
+# iMCP for macOS (requires: brew install --cask loopwork/tap/iMCP)
+# Provides access to Notes, Calendar, Contacts, etc.
+aia --tools examples/tools/mcp/imcp.rb --chat
+```
+
+These MCP clients require the `ruby_llm-mcp` gem and provide access to external services and data sources through the Model Context Protocol.
+
 **Shared Tools Collection:**
 AIA can use the [shared_tools gem](https://github.com/madbomber/shared_tools) which provides a curated collection of commonly-used  tools (aka functions) via the --require option.
 

data/Rakefile

@@ -2,23 +2,31 @@
 
 begin
   require "tocer/rake/register"
-rescue LoadError => error
-  puts error.message
+  Tocer::Rake::Register.call
+rescue LoadError, StandardError => e
+  warn "Skipping tocer tasks: #{e.message}"
 end
 
-Tocer::Rake::Register.call
-
-require 'kramdown/man/task'
-Kramdown::Man::Task.new
+begin
+  require 'kramdown/man/task'
+  Kramdown::Man::Task.new
+rescue LoadError, StandardError => e
+  warn "Skipping kramdown man task: #{e.message}"
+end
 
-require "bundler/gem_tasks"
+begin
+  require "bundler/gem_tasks"
+rescue LoadError, StandardError => e
+  warn "Skipping bundler/gem_tasks: #{e.message}"
+end
 require "minitest/test_task"
 
 Minitest::TestTask.create(:test) do |t|
   t.libs        << "test"
   t.libs        << "lib"
   t.warning     = false
-  t.test_globs  = ["test/aia/*_test.rb", "test/aia_test.rb", "!test/integration/**/*_test.rb"]
+  # Include all unit tests under test/, excluding integration tests
+  t.test_globs  = ["test/**/*_test.rb", "!test/integration/**/*_test.rb"]
 end
 
 Minitest::TestTask.create(:integration) do |t|

data/examples/directives/ask.rb

@@ -0,0 +1,21 @@
+# ~/examples/directives/ask.rb
+# Desc: An example of how to extend the AIA directives
+# Usage: aia <options> --require path/to/ask.rb
+#
+# A directive is just a private method of the AIA::DirectiveProcessor class.  its
+# definition is preceeded by the `desc` method which has a single String parameter
+# that is a description of the directive.  This discription is shown with the
+# directive's name in the --chat mode with the //help directive is used.
+
+module AIA
+  class DirectiveProcessor
+    private
+    desc "A meta-prompt to LLM making its response available as part of the primary prompt"
+    # args is an Array of Strings
+    # context_manager is an optional parameter TBD
+    def ask(args, context_manager=nil)
+      meta_prompt = args.empty? ? "What is meta-prompting?" : args.join(' ')
+      AIA.config.client.chat(meta_prompt)
+    end
+  end
+end

data/examples/tools/edit_file.rb

@@ -4,6 +4,8 @@ require "ruby_llm/tool"
 
 module Tools
   class EditFile < RubyLLM::Tool
+    def self.name = "edit_file"
+
     description <<~DESCRIPTION
       Make edits to a text file.
 

data/examples/tools/incomplete/calculator_tool.rb

@@ -0,0 +1,70 @@
+# calculator_tool.rb - Simple custom tool example
+require 'ruby_llm/tool'
+
+module Tools
+  class Calculator < RubyLLM::Tool
+    def self.name = "calculator"
+
+    description <<~DESCRIPTION
+      Perform advanced mathematical calculations with comprehensive error handling and validation.
+      This tool supports basic arithmetic operations, parentheses, and common mathematical functions.
+      It provides safe evaluation of mathematical expressions without executing arbitrary code,
+      making it suitable for use in AI-assisted calculations where security is important.
+      The tool returns formatted results with configurable precision and helpful error messages
+      when invalid expressions are provided.
+    DESCRIPTION
+
+    param :expression,
+          desc: <<~DESC,
+            Mathematical expression to evaluate using standard arithmetic operators and parentheses.
+            Supported operations include: addition (+), subtraction (-), multiplication (*), division (/),
+            and parentheses for grouping. Examples: '2 + 2', '(10 * 5) / 2', '15.5 - 3.2'.
+            Only numeric characters, operators, parentheses, decimal points, and spaces are allowed
+            for security reasons. Complex mathematical functions are not supported in this version.
+          DESC
+          type: :string,
+          required: true
+
+    param :precision,
+          desc: <<~DESC,
+            Number of decimal places to display in the result. Must be a non-negative integer.
+            Set to 0 for whole numbers only, or higher values for more precise decimal results.
+            Default is 2 decimal places, which works well for most financial and general calculations.
+            Maximum precision is limited to 10 decimal places to prevent excessive output.
+          DESC
+          type: :integer,
+          default: 2
+
+    def execute(expression:, precision: 2)
+      begin
+        # Use safe evaluation instead of raw eval
+        result = safe_eval(expression)
+        formatted_result = result.round(precision)
+
+        {
+          success: true,
+          result:  formatted_result,
+          expression: expression,
+          precision: precision
+        }
+      rescue => e
+        {
+          success: false,
+          error:   "Invalid expression: #{e.message}",
+          expression: expression,
+          suggestion: "Try expressions like '2 + 2' or '10 * 5'"
+        }
+      end
+    end
+
+    private
+
+    def safe_eval(expression)
+      # Implement safe mathematical evaluation
+      # This is a simplified example - use a proper math parser in production
+      allowed_chars = /\A[0-9+\-*\/\(\)\.\s]+\z/
+      raise "Invalid characters in expression" unless expression.match?(allowed_chars)
+      eval(expression)
+    end
+  end
+end

data/examples/tools/incomplete/composite_analysis_tool.rb

@@ -0,0 +1,89 @@
+# 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)
+      # TODO: Use shared web tools or custom HTTP client
+    end
+
+    def read_file_data(file_path)
+      # TODO: Use shared file tools
+    end
+
+    def analyze_data_structure(data)
+      # TODO: Implementation for data structure analysis
+    end
+
+    def generate_insights(data, structure)
+      # TODO: Implementation for insight generation
+    end
+
+    def suggest_visualizations(structure)
+      # TODO:Implementation for visualization suggestions
+    end
+  end
+end

data/examples/tools/incomplete/data_science_kit.rb

@@ -0,0 +1,128 @@
+# 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)
+      # TODO: Implementation for data loading from various sources
+    end
+
+    def validate_data_for_analysis(data, analysis_type)
+      # TODO: Implementation for data validation
+    end
+
+    def generate_statistical_summary(data, parameters)
+      # TODO: Implementation for statistical summary
+    end
+
+    def perform_correlation_analysis(data, parameters)
+      # TODO: Implementation for correlation analysis
+    end
+
+    def analyze_time_series(data, parameters)
+      # TODO: Implementation for time series analysis
+    end
+
+    def perform_clustering(data, parameters)
+      # TODO: Implementation for clustering
+    end
+
+    def generate_predictions(data, parameters)
+      # TODO: Implementation for prediction
+    end
+
+    def summarize_data(data)
+      # TODO: Implementation for data summary
+    end
+  end
+end

data/examples/tools/incomplete/database_query_tool.rb

@@ -0,0 +1,100 @@
+# 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/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