aia 1.1.0 → 2.0.0.0.pre.alpha

data/lib/aia/system_prompt_assembler.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+# lib/aia/system_prompt_assembler.rb
+#
+# System prompt resolution, identity prompts, and role loading.
+# Extracted from RobotFactory to isolate the prompt assembly concern.
+# Completely stateless — no module ivars.
+
+require_relative 'skill_utils'
+
+module AIA
+  module SystemPromptAssembler
+    module_function
+
+    # Resolve system prompt from config (including role).
+    #
+    # @param config [AIA::Config] the AIA configuration
+    # @param model_spec [ModelSpec, nil] optional model spec with role override
+    # @return [String, nil] the assembled system prompt
+    def resolve_system_prompt(config, model_spec = nil)
+      system_prompt = config.prompts.system_prompt
+
+      role_id = model_spec&.role || config.prompts.role
+      if role_id && !role_id.empty?
+        role_content = load_role_content(config, role_id)
+        if role_content
+          system_prompt = [system_prompt, role_content].compact.join("\n\n")
+        end
+      end
+
+      # In chat mode inject --skill content here so it persists across all turns.
+      # Pipeline mode appends skills to each prompt text instead (pipeline_orchestrator).
+      if config.flags&.chat == true
+        skill_content = AIA::SkillUtils.load_skills_content(
+          Array(config.prompts&.skills),
+          AIA::SkillUtils.skills_base_dir(config)
+        )
+        system_prompt = [system_prompt, skill_content].compact.join("\n\n") if skill_content
+      end
+
+      system_prompt
+    end
+
+    # Build a system prompt fragment that tells a robot its name, its
+    # model, and the other robots in the network.
+    #
+    # @param robot_name [String] this robot's creative name
+    # @param spec [ModelSpec] this robot's model spec
+    # @param roster [Array<Hash>] all robots: [{ name:, spec: }, ...]
+    # @return [String]
+    def build_identity_prompt(robot_name, spec, roster)
+      provider_label = spec.provider ? " (#{spec.provider})" : ""
+      lines = ["You are #{robot_name}, powered by #{spec.name}#{provider_label}."]
+
+      if roster.size > 1
+        lines << "You are part of a team of AI robots:"
+        roster.each do |entry|
+          p = entry[:spec].provider ? " (#{entry[:spec].provider})" : ""
+          marker = entry[:name] == robot_name ? " ← you" : ""
+          lines << "  - #{entry[:name]}: #{entry[:spec].name}#{p}#{marker}"
+        end
+        lines << "Users can address a specific robot with @name mentions."
+      end
+
+      lines.join("\n")
+    end
+
+    # Load role file content.
+    #
+    # @param config [AIA::Config] the AIA configuration
+    # @param role_id [String] the role identifier
+    # @return [String, nil] the role file content or nil
+    def load_role_content(config, role_id)
+      roles_prefix = config.prompts.roles_prefix
+      unless role_id.start_with?(roles_prefix)
+        role_id = "#{roles_prefix}/#{role_id}"
+      end
+
+      role_file = File.join(config.prompts.dir, "#{role_id}#{config.prompts.extname}")
+      return nil unless File.exist?(role_file)
+
+      File.read(role_file)
+    rescue => e
+      $stderr.puts "Warning: Could not load role '#{role_id}': #{e.message}"
+      nil
+    end
+  end
+end

data/lib/aia/task_coordinator.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+# lib/aia/task_coordinator.rb
+#
+# Bridges robots and TrakFlow task management.
+# Robots use this to create tasks for each other, claim work,
+# and report completion. Wraps TrakFlow's database API in a
+# robot-friendly interface.
+
+module AIA
+  class TaskCoordinator
+    def initialize(bridge: TrakFlowBridge.new)
+      @bridge = bridge
+      @db     = bridge.db
+    end
+
+    def available?
+      @bridge.available?
+    end
+
+    # Clear all tasks from the board for a fresh session.
+    def clear!
+      return unless available?
+      @db.clear!
+    end
+
+    # A robot creates a task for another robot (or any robot) to handle.
+    #
+    # @param title [String] task description
+    # @param assignee [String, nil] target robot name, nil = any robot
+    # @param parent_id [String, nil] parent task for hierarchy
+    # @param blocked_by [Array<String>] task IDs that must complete first
+    # @param labels [Array<String>] labels like "robot:alice", "domain:code"
+    # @param creator [String] name of the creating robot
+    # @return [TrakFlow::Models::Task, nil]
+    def create_task(title, assignee: nil, parent_id: nil,
+                    blocked_by: [], labels: [], creator: "aia")
+      return nil unless available?
+
+      task = TrakFlow::Models::Task.new(
+        title: title, assignee: assignee, type: "task"
+      )
+      task = @db.create_task(task)
+
+      @db.add_label(TrakFlow::Models::Label.new(
+                      task_id: task.id, name: "creator:#{creator}"
+                    ))
+
+      labels.each do |label|
+        @db.add_label(TrakFlow::Models::Label.new(
+                        task_id: task.id, name: label
+                      ))
+      end
+
+      blocked_by.each do |blocker_id|
+        @db.add_dependency(TrakFlow::Models::Dependency.new(
+                             source_id: blocker_id, target_id: task.id, type: "blocks"
+                           ))
+      end
+
+      if parent_id
+        @db.add_dependency(TrakFlow::Models::Dependency.new(
+                             source_id: parent_id, target_id: task.id, type: "parent-child"
+                           ))
+      end
+
+      task
+    end
+
+    # A robot creates a full plan (blueprint) with ordered steps.
+    #
+    # @param title [String] plan title
+    # @param steps [Array<Hash>] each: { title:, assignee:, labels: [] }
+    # @param creator [String] creating robot name
+    # @param ephemeral [Boolean] true for single-session plans (auto-gc)
+    # @return [Hash, nil] { plan:, steps: }
+    def create_plan(title, steps:, creator: "aia", ephemeral: false)
+      return nil unless available?
+
+      plan = TrakFlow::Models::Task.new(
+        title: title, plan: true, type: "task"
+      )
+      plan = @db.create_task(plan)
+
+      @db.add_label(TrakFlow::Models::Label.new(
+                      task_id: plan.id, name: "creator:#{creator}"
+                    ))
+
+      prev_step = nil
+      step_tasks = steps.map.with_index do |step_def, _i|
+        step = @db.create_child_task(plan.id, {
+          title:    step_def[:title],
+          assignee: step_def[:assignee],
+          type:     "task"
+        })
+
+        Array(step_def[:labels]).each do |label|
+          @db.add_label(TrakFlow::Models::Label.new(
+                          task_id: step.id, name: label
+                        ))
+        end
+
+        if prev_step
+          @db.add_dependency(TrakFlow::Models::Dependency.new(
+                               source_id: prev_step.id, target_id: step.id, type: "blocks"
+                             ))
+        end
+
+        prev_step = step
+        step
+      end
+
+      { plan: plan, steps: step_tasks }
+    end
+
+    # Get ready tasks, optionally filtered by assignee.
+    #
+    # @param robot_name [String, nil] filter by assignee
+    # @return [Array<TrakFlow::Models::Task>]
+    def ready_tasks(robot_name: nil)
+      return [] unless available?
+
+      tasks = @db.ready_tasks
+      robot_name ? tasks.select { |t| t.assignee == robot_name } : tasks
+    end
+
+    # A robot claims a task (sets in_progress with its name).
+    #
+    # @param task_id [String]
+    # @param robot_name [String]
+    def claim_task(task_id, robot_name)
+      return unless available?
+
+      task = @db.find_task(task_id)
+      return unless task
+
+      task.status   = "in_progress"
+      task.assignee = robot_name
+      task.append_trace("claimed", "Claimed by #{robot_name}")
+      @db.update_task(task)
+    end
+
+    # A robot completes a task with a result summary.
+    #
+    # @param task_id [String]
+    # @param result [String] summary of what was done
+    # @param robot_name [String]
+    def complete_task(task_id, result:, robot_name:)
+      return unless available?
+
+      task = @db.find_task(task_id)
+      return unless task
+
+      task.close!(reason: result)
+      @db.add_comment(TrakFlow::Models::Comment.new(
+                        task_id: task_id, author: robot_name, body: result
+                      ))
+      @db.update_task(task)
+    end
+
+    # A robot marks a task as blocked with a reason.
+    #
+    # @param task_id [String]
+    # @param reason [String]
+    # @param robot_name [String]
+    def block_task(task_id, reason:, robot_name:)
+      return unless available?
+
+      task = @db.find_task(task_id)
+      return unless task
+
+      task.status = "blocked"
+      task.append_trace("blocked", "#{robot_name}: #{reason}")
+      @db.update_task(task)
+    end
+
+    # Summary of the current task board state.
+    #
+    # @return [String, nil]
+    def status_summary
+      return nil unless available?
+
+      all     = @db.list_tasks({})
+      ready   = @db.ready_tasks
+      blocked = @db.blocked_tasks
+
+      by_assignee = all.select(&:assignee).group_by(&:assignee)
+
+      lines = ["Task Board (#{all.size} total, #{ready.size} ready, #{blocked.size} blocked):"]
+      by_assignee.sort.each do |assignee, tasks|
+        open_count   = tasks.count { |t| t.open? || t.in_progress? }
+        closed_count = tasks.count(&:closed?)
+        lines << "  #{assignee}: #{open_count} open, #{closed_count} done"
+      end
+
+      unassigned = all.reject(&:assignee)
+      lines << "  unassigned: #{unassigned.size}" unless unassigned.empty?
+
+      lines.join("\n")
+    end
+  end
+end

data/lib/aia/task_decomposer.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+# lib/aia/task_decomposer.rb
+#
+# Extracts plan decomposition logic from DelegateHandler.
+# The lead robot analyzes a prompt and breaks it into subtasks
+# with robot assignments.
+
+require "json"
+
+module AIA
+  class TaskDecomposer
+    include ContentExtractor
+
+    def initialize(lead_robot:, ui_presenter:)
+      @lead = lead_robot
+      @ui   = ui_presenter
+    end
+
+    # Decompose a prompt into subtasks assigned to specific robots.
+    #
+    # @param prompt [String] the original user prompt
+    # @param robot_names [Array<String>] available robot names
+    # @return [Array<Hash>] steps with :title and :assignee, or [] on failure
+    def decompose(prompt, robot_names)
+      @ui.display_info("#{@lead.name} analyzing and delegating...")
+
+      plan_result = @lead.run(<<~PROMPT, mcp: :none, tools: :none)
+        Break this request into subtasks. Assign each to the most
+        appropriate team member based on their model capabilities.
+
+        Team: #{robot_names.join(', ')}
+        Request: #{prompt}
+
+        Respond with ONLY a JSON array:
+        [{"title": "subtask description", "assignee": "robot_name"}]
+      PROMPT
+
+      reply = extract_content(plan_result)
+      parse_plan(reply, robot_names)
+    end
+
+    private
+
+    def parse_plan(json_text, valid_names)
+      match = json_text.to_s.match(/\[.*\]/m)
+      return [] unless match
+
+      JSON.parse(match[0], symbolize_names: true).map do |step|
+        assignee = valid_names.include?(step[:assignee]) ? step[:assignee] : valid_names.first
+        { title: step[:title].to_s, assignee: assignee }
+      end
+    rescue JSON::ParserError
+      []
+    end
+  end
+end

data/lib/aia/task_executor.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+# lib/aia/task_executor.rb
+#
+# Extracts step execution logic from DelegateHandler.
+# Runs a single subtask against the assigned robot and records
+# the result in the task coordinator.
+
+module AIA
+  class TaskExecutor
+    include ContentExtractor
+
+    def initialize(task_coordinator:)
+      @coordinator = task_coordinator
+    end
+
+    # Execute a single task step against the assigned robot.
+    #
+    # @param task [Object] TrakFlow task object (responds to #id)
+    # @param robot [RobotLab::Robot] the assigned robot
+    # @param step_def [Hash] step definition with :title
+    # @param prompt [String] the original user prompt
+    # @param prior_results [Array<Hash>] results from previous steps
+    # @return [String] the robot's response content
+    def execute(task, robot, step_def, prompt, prior_results)
+      @coordinator.claim_task(task.id, robot.name)
+
+      context = build_step_context(prompt, step_def[:title], prior_results)
+      result  = robot.run(context, mcp: :inherit, tools: :inherit)
+      content = extract_content(result)
+
+      @coordinator.complete_task(task.id, result: content[0, 200], robot_name: robot.name)
+      content
+    end
+
+    private
+
+    def build_step_context(prompt, task_title, prior_results)
+      context = "Original request: #{prompt}\n\n"
+
+      unless prior_results.empty?
+        prior = prior_results.map do |r|
+          "#{r[:robot]} completed '#{r[:task]}':\n#{r[:content]}"
+        end.join("\n\n")
+        context += "Prior work:\n#{prior}\n\n"
+      end
+
+      context + "Your task: #{task_title}"
+    end
+  end
+end

data/lib/aia/tfidf_math.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# lib/aia/tfidf_math.rb
+#
+# Pure TF-IDF vector math shared by SimilarityScorer and ToolFilter::TFIDF.
+# Kept dependency-free and stateless so both callers (and tests) can use it
+# in isolation.
+
+module AIA
+  module TFIDFMath
+    module_function
+
+    # Cosine similarity between two TF-IDF hash vectors.
+    #
+    # @param a [Hash{Symbol => Float}]
+    # @param b [Hash{Symbol => Float}]
+    # @return [Float] 0.0..1.0
+    def cosine_similarity(a, b)
+      all_keys = a.keys | b.keys
+      dot   = all_keys.sum { |k| (a[k] || 0.0) * (b[k] || 0.0) }
+      mag_a = Math.sqrt(a.values.sum { |v| v**2 })
+      mag_b = Math.sqrt(b.values.sum { |v| v**2 })
+      return 0.0 if mag_a.zero? || mag_b.zero?
+      (dot / (mag_a * mag_b)).clamp(0.0, 1.0)
+    end
+  end
+end

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