aia 1.1.1 → 2.0.0.0.pre.beta2

data/lib/aia/tool_filter/tfidf.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+# lib/aia/tool_filter/tfidf.rb
+#
+# TF-IDF based tool filtering (Option A).
+# Built once at session start from all tool descriptions (local + MCP).
+# Per-turn: scores user prompt against each tool's description via cosine
+# similarity and returns tool names above threshold, capped at max_tools.
+#
+# Text is normalized before indexing and querying:
+#   - Lowercased and tokenized on word boundaries
+#   - Each token is Porter-stemmed (via fast-stemmer, a classifier dependency)
+#   - Parameter names are appended to each tool's description text
+
+require 'classifier'
+require 'fast-stemmer'
+require_relative '../tfidf_math'
+
+module AIA
+  class ToolFilter
+    class TFIDF < ToolFilter
+      DEFAULT_THRESHOLD = 0.05
+      DEFAULT_MAX_TOOLS = 30
+
+      # @param tools [Array] tool classes/objects with .name and .description
+      # @param fact_asserter [FactAsserter] used for tool_name/tool_description extraction
+      # @param threshold [Float] minimum cosine similarity to include a tool (default 0.05)
+      # @param max_tools [Integer] maximum tools to return per turn (default 30)
+      def initialize(tools:, fact_asserter:, threshold: DEFAULT_THRESHOLD, max_tools: DEFAULT_MAX_TOOLS)
+        super(label: "TF-IDF")
+        @fact_asserter = fact_asserter
+        @threshold     = threshold
+        @max_tools     = max_tools
+        @tools         = tools
+        @tool_entries  = []
+        @tfidf         = nil
+        @tool_vectors  = []
+      end
+
+      protected
+
+      def do_prep
+        build_index(@tools)
+        return if @tool_entries.empty?
+
+        tool_texts = @tool_entries.map { |e| e[:description] }
+        @tfidf = Classifier::TFIDF.new
+        @tfidf.fit(tool_texts)
+        @tool_vectors = tool_texts.map { |t| @tfidf.transform(t) }
+      end
+
+      def do_filter_with_scores(prompt)
+        return [] if @tool_entries.empty? || @tfidf.nil? || prompt.nil? || prompt.strip.empty?
+
+        query_vector = @tfidf.transform(normalize(prompt))
+
+        scored = @tool_entries.each_with_index.map do |entry, i|
+          score = AIA::TFIDFMath.cosine_similarity(query_vector, @tool_vectors[i])
+          { name: entry[:name], score: score }
+        end
+
+        scored
+          .select { |e| e[:score] >= @threshold }
+          .sort_by { |e| -e[:score] }
+          .first(@max_tools)
+      rescue StandardError => e
+        $stderr.puts "ToolFilter::TFIDF error: #{e.message}"
+        []
+      end
+
+      private
+
+      def build_index(tools)
+        Array(tools).each do |tool|
+          name   = @fact_asserter.tool_name(tool)
+          desc   = @fact_asserter.tool_description(tool)
+          params = extract_param_names(tool)
+          next if name.empty?
+
+          raw_text = [name, desc, params].reject(&:empty?).join(" ")
+          expanded = AIA::ToolFilter::WordNetExpander.expand(raw_text)
+          @tool_entries << { name: name, description: normalize(expanded) }
+        end
+
+        @tool_count = @tool_entries.size
+      end
+
+      # Collect parameter names from a tool object.
+      # RubyLLM::Tool exposes .parameters as {sym => Parameter}.
+      # Parameter names are discriminative (e.g. "sql_query", "xpath", "url").
+      def extract_param_names(tool)
+        return "" unless tool.respond_to?(:parameters)
+
+        params = tool.parameters
+        return "" unless params.respond_to?(:values)
+
+        names = params.values.map do |p|
+          p.respond_to?(:name) ? p.name.to_s : p.to_s
+        end
+        names.reject(&:empty?).join(" ")
+      rescue StandardError
+        ""
+      end
+
+      # Normalize text for TF-IDF: tokenize, stem each word, rejoin.
+      # Applied symmetrically to both tool text (at index time) and
+      # the user prompt (at query time) so the vocabulary matches.
+      def normalize(text)
+        text.downcase
+            .scan(/[a-z]+/)
+            .map(&:stem)
+            .join(" ")
+      end
+    end
+  end
+end

data/lib/aia/tool_filter/wordnet_expander.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+# lib/aia/tool_filter/wordnet_expander.rb
+#
+# Expands tool description text with WordNet synonyms at index time.
+# Uses the `wn` CLI from `brew install wordnet`.
+#
+# Expansion is applied once per build_index call (not to user queries).
+# Results are cached in-process so each unique word is only looked up once.
+# If `wn` is not installed, expand() is a no-op that returns the original text.
+#
+# WordNet POS queried: nouns (-synsn) and verbs (-synsv).
+# Multi-word synonyms (containing spaces or underscores) are excluded.
+# Words shorter than MIN_WORD_LENGTH are excluded (filters stop words).
+
+require 'shellwords'
+
+module AIA
+  class ToolFilter
+    module WordNetExpander
+      MIN_WORD_LENGTH = 4
+
+      @cache          = {}
+      @cache_mutex    = Mutex.new
+      @available      = nil
+      @available_mutex = Mutex.new
+
+      class << self
+        # Returns true if the `wn` executable is on PATH.
+        # Result is cached for the process lifetime.
+        def available?
+          @available_mutex.synchronize do
+            return @available unless @available.nil?
+            @available = system("which wn", out: File::NULL, err: File::NULL) ? true : false
+          end
+        end
+
+        # Expand text by appending synonyms for each content word.
+        # Returns the original text unchanged if wn is unavailable.
+        #
+        # @param text [String] raw tool description text
+        # @return [String] original text plus appended synonym terms
+        def expand(text)
+          return text unless available?
+
+          words     = text.downcase.scan(/[a-z]{#{MIN_WORD_LENGTH},}/).uniq
+          new_terms = words.flat_map { |w| synonyms_for(w) }
+                           .uniq
+                           .reject { |w| words.include?(w) }
+
+          new_terms.empty? ? text : "#{text} #{new_terms.join(' ')}"
+        end
+
+        # Return synonyms for a single word from WordNet (nouns + verbs).
+        # Does not include the word itself. Returns [] if not found.
+        # Results are cached per-word for the process lifetime.
+        #
+        # @param word [String] lowercase word to look up
+        # @return [Array<String>] synonym strings, single-word only
+        def synonyms_for(word)
+          # fast path: already cached
+          @cache_mutex.synchronize { return @cache[word] if @cache.key?(word) }
+
+          syns = (query_wn(word, 'n') + query_wn(word, 'v'))
+                 .uniq
+                 .reject { |w| w == word }
+
+          # write path: first writer wins; read-back in same lock so clear_cache!
+          # between write and read cannot cause nil to escape
+          @cache_mutex.synchronize do
+            @cache[word] = syns unless @cache.key?(word)
+            @cache[word]
+          end
+        rescue StandardError
+          []
+        end
+
+        # Wipe the in-process synonym cache. Used between tests.
+        def clear_cache!
+          @cache_mutex.synchronize { @cache.clear }
+        end
+
+        # Reset all cached state. Used in test teardowns.
+        def reset_for_testing!
+          @available_mutex.synchronize { @available = nil }
+          @cache_mutex.synchronize { @cache.clear }
+        end
+
+        private
+
+        # Shell out to `wn word -syns{pos}` and parse the synset lines.
+        #
+        # @param word [String] word to look up
+        # @param pos  [String] part of speech: 'n' (noun) or 'v' (verb)
+        # @return [Array<String>] single-word synonyms
+        def query_wn(word, pos)
+          output = `wn #{Shellwords.escape(word)} -syns#{pos} 2>/dev/null`
+          parse_synsets(output)
+        rescue StandardError
+          []
+        end
+
+        # Parse synset lines from `wn` output.
+        #
+        # Synset lines start with a lowercase letter (no leading whitespace)
+        # and contain comma-separated synonym words. Hypernym/relative lines
+        # start with whitespace or contain '=>' and are skipped.
+        #
+        # @param output [String] raw output from `wn`
+        # @return [Array<String>] unique single-word synonym strings
+        def parse_synsets(output)
+          output.lines.flat_map do |line|
+            next [] unless line.match?(/\A[a-z]/)
+            next [] if line.include?("=>")
+
+            line.chomp.split(/,\s*/).map(&:strip).select do |word|
+              word.length >= MIN_WORD_LENGTH &&
+                !word.include?(' ') &&
+                !word.include?('_') &&
+                word.match?(/\A[a-z]+\z/)
+            end
+          end.uniq
+        end
+      end
+    end
+  end
+end

data/lib/aia/tool_filter.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+# lib/aia/tool_filter.rb
+#
+# Abstract base class for tool filtering strategies.
+# Subclasses implement `do_prep` (one-time index build) and
+# `do_filter_with_scores` (per-turn query). The base class provides
+# timing instrumentation and a uniform public API.
+
+require_relative 'tool_filter/wordnet_expander'
+
+module AIA
+  class ToolFilter
+    attr_reader :tool_count, :prep_ms, :label
+
+    # :reek:BooleanParameter -- load_db:/save_db: toggle embedding-cache persistence per strategy; mode objects would multiply constructors
+    def initialize(label:, db_dir: nil, load_db: false, save_db: false)
+      @label      = label
+      @db_dir     = db_dir
+      @load_db    = load_db
+      @save_db    = save_db
+      @tool_count = 0
+      @prep_ms    = 0.0
+    end
+
+    # One-time initialization. Captures timing in @prep_ms, returns it.
+    def prep
+      start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      do_prep
+      @prep_ms = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000
+    end
+
+    # Per-turn query. Returns [names] or nil (nil = all tools).
+    def filter(prompt)
+      names = filter_with_scores(prompt).map { |e| e[:name] }
+      names.empty? ? nil : names
+    end
+
+    # Per-turn query with scores. Returns [{name:, score:}].
+    def filter_with_scores(prompt)
+      do_filter_with_scores(prompt)
+    end
+
+    # Override in subclasses that need resource cleanup.
+    def cleanup; end
+
+    # True when the filter has indexed at least one tool.
+    def available?
+      @tool_count.positive?
+    end
+
+    # True when this filter supports database persistence (--load / --save).
+    def persistable?
+      false
+    end
+
+    protected
+
+    def do_prep
+      raise NotImplementedError, "#{self.class}#do_prep must be implemented"
+    end
+
+    def do_filter_with_scores(_prompt)
+      raise NotImplementedError, "#{self.class}#do_filter_with_scores must be implemented"
+    end
+
+    private
+
+    # Compute a SHA256 fingerprint of the tool set for staleness detection.
+    # Sorted alphabetically so insertion order doesn't affect the result.
+    #
+    # @param tools [Array] tool objects with .name
+    # @return [String] 64-char hex digest
+    def fingerprint_from_tools(tools)
+      require 'digest'
+      names = Array(tools).filter_map do |tool|
+        n = tool.respond_to?(:name) ? tool.name.to_s.strip : ""
+        n.empty? ? nil : n
+      end.sort
+      Digest::SHA256.hexdigest(names.join(","))
+    end
+  end
+end

data/lib/aia/tool_filter_registry.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+# lib/aia/tool_filter_registry.rb
+#
+# Builds and preps all active ToolFilter instances from the current config.
+# Extracted from Session#start to remove 5 identical if/prep/assign blocks.
+
+module AIA
+  class ToolFilterRegistry
+    # Build and prep all active tool filters according to config flags.
+    #
+    # @param config  [AIA::Config]   the current AIA configuration
+    # @param tools   [Array]         all available tool objects
+    # @return [Hash{Symbol => ToolFilter}] keyed by filter identifier
+    def self.build_from_config(config, tools)
+      filters       = {}
+      fact_asserter = nil
+
+      if config.flags.auto_tool_filter
+        require_relative 'tool_filter/tfidf'
+        fact_asserter ||= AIA::FactAsserter.new
+        tfidf_filter = ToolFilter::TFIDF.new(tools: tools, fact_asserter: fact_asserter)
+        tfidf_filter.prep
+        filters[:tfidf] = tfidf_filter
+      end
+
+      filters
+    end
+  end
+end

data/lib/aia/tool_filter_strategy.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+# lib/aia/tool_filter_strategy.rb
+#
+# Strategy resolver for TF-IDF tool filtering (Option A).
+# Accepts a Hash of ToolFilter subclass instances keyed by symbol.
+#
+# After each resolve(), prints a timing table showing
+# prep and filter times for the active filter.
+
+require 'tty-table'
+
+module AIA
+  class ToolFilterStrategy
+    # Maps filter keys to display info.
+    FILTER_META = {
+      tfidf: { letter: "A", label: "TF-IDF", score_label: "score" }
+    }.freeze
+
+    DEFAULT_TIMEOUT_S = 10
+
+    # @param filters [Hash{Symbol => ToolFilter}] e.g. {tfidf: tfidf_filter}
+    # @param ui_presenter [UIPresenter, nil] for display (unused currently, reserved)
+    # @param timeout_s [Numeric] per-filter wall-clock timeout in seconds
+    def initialize(filters: {}, ui_presenter: nil, timeout_s: DEFAULT_TIMEOUT_S)
+      @filters      = filters
+      @ui_presenter = ui_presenter
+      @timeout_s    = timeout_s
+    end
+
+    # Resolve the tool list for this turn based on the active strategy.
+    #
+    # @param prompt [String] the user's processed prompt
+    # @return [Array<String>, nil] tool names to allow, or nil for all tools
+    def resolve(prompt)
+      active = available_filters
+
+      return resolve_single(prompt, active.first) if active.size >= 1
+
+      # No filters — all tools available
+      nil
+    end
+
+    # @return [String] label for the active strategy (used in debug logging)
+    def active_strategy_label
+      labels = available_filters.map { |key, _| meta_for(key)[:label] }
+      labels = ["none"] if labels.empty?  # fallback
+      labels.first
+    end
+
+    private
+
+    # Filters that are actually available (have indexed tools).
+    def available_filters
+      @filters.select { |_key, filter| filter.available? }
+    end
+
+    # Meta info for a filter key, with fallback for unknown keys.
+    def meta_for(key)
+      FILTER_META[key] || { letter: key.to_s[0].upcase, label: key.to_s, score_label: "score" }
+    end
+
+    # Single filter path: run filter, display results and timing.
+    def resolve_single(prompt, (key, filter))
+      filter_ms = run_filter_timed(key, filter, prompt)
+      scored = filter_ms[:scored]
+
+      if AIA.debug?
+        display_filter_results(key, scored)
+        display_timing_table({ key => filter_ms[:ms] })
+      end
+
+      # Return the matched names. An EMPTY array is meaningful: the filter ran
+      # and judged no tool relevant to this prompt, so the caller should send NO
+      # tools (not the full set). Only a missing filter (see #resolve's no-filter
+      # path) or a filter error (the rescue below) yields nil = "use all tools".
+      scored.map { |e| e[:name] }
+    rescue => e
+      AIA.logger.debug "ToolFilterStrategy: #{meta_for(key)[:label]} filter failed: #{e.message}" if AIA.debug?
+      nil
+    end
+
+    # Run a filter and return {scored:, ms:}.
+    def run_filter_timed(_key, filter, prompt)
+      start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      scored = filter.filter_with_scores(prompt)
+      ms = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000
+      { scored: scored, ms: ms }
+    end
+
+    # Display single-filter results via logger.
+    def display_filter_results(key, scored)
+      meta   = meta_for(key)
+      label  = meta[:label]
+      logger = AIA.logger
+
+      if scored.empty?
+        logger.debug "[#{label}] No tools matched (all tools available)"
+        return
+      end
+
+      names = scored.map { |e| e[:name] }.join(', ')
+      logger.debug "[#{label}] Tools for this turn (#{scored.size}): #{names}"
+
+      scored.each do |entry|
+        logger.debug "[#{label}]   #{entry[:name]}  (#{meta[:score_label]}: #{format('%.4f', entry[:score])})"
+      end
+    end
+
+    # Print the timing table via logger.
+    # :reek:DuplicateMethodCall -- header and each data row map the same columns into different cells
+    def display_timing_table(filter_ms_by_key)
+      columns = build_timing_columns(filter_ms_by_key)
+      return if columns.empty?
+
+      header = ["Process"] + columns.map { |col| "#{col[:header]}\n#{col[:sub]}" }
+      rows   = [
+        ["prep"]   + columns.map { |col| col[:prep] },
+        ["filter"] + columns.map { |col| col[:filter] }
+      ]
+
+      alignments = [:left] + Array.new(columns.size, :right)
+      rendered   = TTY::Table.new(header, rows)
+                             .render(:unicode, multiline: true, alignments: alignments, padding: [0, 1])
+      rendered.each_line { |line| AIA.logger.debug(line.chomp) }
+    end
+
+    # Column data (header, sub-label, prep/filter cells) for each configured filter.
+    def build_timing_columns(filter_ms_by_key)
+      @filters.map do |key, filter|
+        meta   = meta_for(key)
+        active = filter_ms_by_key.key?(key)
+        {
+          header: "Option #{meta[:letter]}",
+          sub:    "(#{meta[:label]})",
+          prep:   active ? fmt_ms(filter.prep_ms) : "--",
+          filter: active ? fmt_ms(filter_ms_by_key[key]) : "--"
+        }
+      end
+    end
+
+    def fmt_ms(ms)
+      "#{ms.round(1)}ms"
+    end
+  end
+end

data/lib/aia/tool_introspection.rb

@@ -0,0 +1,17 @@
+# lib/aia/tool_introspection.rb
+
+module AIA
+  # Shared name/description extraction for tool objects, which may be
+  # RubyLLM tools, RobotLab tools, or bare tool classes.
+  module ToolIntrospection
+    module_function
+
+    def tool_name(tool)
+      tool.respond_to?(:name) ? tool.name : tool.class.name
+    end
+
+    def tool_description(tool)
+      tool.respond_to?(:description) ? tool.description.to_s : ''
+    end
+  end
+end