aia 0.9.8 → 0.9.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3411bc073c7fadee9f625917b13b06fb11aee61c234f61c57958be1000f261c6
-  data.tar.gz: 1228b68648536d5c8a4caeb2e6cf6eb91400647c96163b1ab7b6f499b1001d99
+  metadata.gz: 0c3bcf7e4888283a1ce66733f83d4d3ec1dc95420a7898462cc571ff6ccb134c
+  data.tar.gz: 07733fe911886e651569e1310a078474abf61f7f9cdeb16cfd9154758d936af5
 SHA512:
-  metadata.gz: cbd94570f820e5007a7a9ba94b908a0f36407ec9b9f11074283e67374b24261db18309f32c2e079521c93322ce6fe4c2223181d61f3dce99c4a0d39bc5a26e48
-  data.tar.gz: fdd5647498501805e598c5e7d319193928954e1e2e639e473440c323e49abee46c09aa665130679e790db15c49d81f0ab5bf09deb5ac0f4b6b67eba6a9da625c
+  metadata.gz: 94beb5af35dfcd044c7932eca574ab3c5c7a8451c303a99786e84096458927090a1886aefc83e02bf530e5bf6bcee0cba7ea7cbb5177efca1f3042670b8df8ff
+  data.tar.gz: 99e1f1ea2a751176d828f9c0cc18224875866977a21b91a8adceff6d8b339ac09632b55b8858ff3b4231e4d0e83180f9adfc340d3e0d76144f284288831317f3

data/.version

@@ -1 +1 @@
-0.9.8
+0.9.10

data/CHANGELOG.md

@@ -3,10 +3,25 @@
 
 ## Released
 
+### [0.9.10] 2025-07-18
+- updated ruby_llm-mcp to version 0.6.1 which solves problems with MCP tools not being installed
+
+### [0.9.9] 2025-07-10
+- 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
+
+
 ### [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
 

data/README.md

@@ -6,9 +6,15 @@
 
 AIA is a command-line utility that facilitates interaction with AI models through dynamic prompt management. It automates the management of pre-compositional prompts and executes generative AI commands with enhanced features including embedded directives, shell integration, embedded Ruby, history management, interactive chat, and prompt workflows.
 
-AIA leverages the [prompt_manager gem](https://github.com/madbomber/prompt_manager) to manage prompts, utilizes the [CLI tool fzf](https://github.com/junegunn/fzf) for prompt selection, and can use the [shared_tools gem](https://github.com/madbomber/shared_tools) which provides a collection of common ready-to-use functions for use with LLMs that support tools.
+AIA leverages the following Ruby gems:
 
-**Wiki**: [Checkout the AIA Wiki](https://github.com/MadBomber/aia/wiki)
+- **[prompt_manager](https://github.com/madbomber/prompt_manager)** to manage prompts,
+- **[ruby_llm](https://rubyllm.com)** to access LLM providers,
+- **[ruby_llm-mcp](https://www.rubyllm-mcp.com)** for Model Context Protocol (MCP) support,
+- and can use the **[shared_tools gem](https://github.com/madbomber/shared_tools)** which provides a collection of common ready-to-use MCP clients and functions for use with LLMs that support tools.
+
+**Wiki**: [Checkout the AIA Wiki](https://github.com/MadBomber/aia/wiki)<br />
+**BLOG**: [Series on AIA](https://madbomber.github.io/blog/engineering/AIA-Philosophy/)
 
 ## Quick Start
 
@@ -74,6 +80,7 @@ AIA leverages the [prompt_manager gem](https://github.com/madbomber/prompt_manag
     - [Prompt Directives](#prompt-directives)
       - [Configuration Directive Examples](#configuration-directive-examples)
       - [Dynamic Content Examples](#dynamic-content-examples)
+      - [Custom Directive Examples](#custom-directive-examples)
     - [Shell Integration](#shell-integration)
     - [Embedded Ruby (ERB)](#embedded-ruby-erb)
     - [Prompt Sequences](#prompt-sequences)
@@ -112,6 +119,7 @@ AIA leverages the [prompt_manager gem](https://github.com/madbomber/prompt_manag
     - [Areas for Improvement](#areas-for-improvement)
   - [Roadmap](#roadmap)
   - [License](#license)
+  - [Articles on AIA](#articles-on-aia)
 
 <!-- Tocer[finish]: Auto-generated, don't remove. -->
 
@@ -358,6 +366,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 +534,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.
 
@@ -806,11 +857,17 @@ rake test
 ## Roadmap
 
 - **Enhanced Search**: Restore full-text search within prompt files
-- **Model Context Protocol**: Continue integration with ruby_llm gem
 - **UI Improvements**: Better configuration management for fzf and rg tools
-- **Performance**: Optimize prompt loading and processing
-- **Security**: Enhanced sandboxing for shell command execution
+- **Logging**: Enhanced logging using Ruby Logger class; integration with RubyLLM and RubyLLM::MCP logging
 
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Articles on AIA
+
+1. [The Philosophy of Prompt-Driven Development with AIA](https://madbomber.github.io/blog/engineering/AIA-Philosophy/)
+2. [Mastering AIA's Batch Mode: From Simple Questions to Complex Workflows](https://madbomber.github.io/blog/engineering/AIA-Batch-Mode/)
+3. [Building AI Workflows: AIA's Prompt Sequencing and Pipelines](https://madbomber.github.io/blog/engineering/AIA-Workflows/)
+4. [Interactive AI Sessions: Mastering AIA's Chat Mode](https://madbomber.github.io/blog/engineering/AIA-Chat-Mode/)
+5. [From Dynamic Prompts to Advanced Tool Integration](https://madbomber.github.io/blog/engineering/AIA-Advanced-Tool-Integration/)

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