aia 1.1.1 → 2.0.0.0.pre.beta2

data/lib/aia/streaming_runner.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+# lib/aia/streaming_runner.rb
+#
+# Encapsulates the streaming execution pattern used across ChatLoop,
+# MentionRouter, and expert routing. Manages spinner lifecycle and
+# streaming callback for any robot.
+
+require "tty-spinner"
+
+module AIA
+  class StreamingRunner
+    # Hard ceiling on tools sent to the provider. OpenAI and Anthropic both
+    # reject tool arrays longer than 128. Overridable via config.max_tools.
+    DEFAULT_MAX_TOOLS = 128
+
+    def initialize
+      @spinner = TTY::Spinner.new("[:spinner] Processing...", format: :bouncing_ball)
+    end
+
+    # Run a robot with streaming output.
+    # Spinner shows until the first chunk arrives, then stops and
+    # chunks are printed directly to stdout.
+    #
+    # @param robot [RobotLab::Robot, RobotLab::Network] the robot to run
+    # @param prompt [String] the prompt to send
+    # @param header [String] text printed before the first streamed chunk
+    # @param spinner_message [String] spinner label
+    # @param tools [Array<String>, nil] tool names to allow for this turn (nil = all)
+    # @return [Array(Object, String, Float)] [result, streamed_content_or_nil, elapsed_seconds]
+    # :reek:TooManyStatements -- one streaming turn: spinner lifecycle, chunk-filter closure, robot run with cleanup, timing
+    # :reek:DuplicateMethodCall -- @spinner.stop guards three distinct control paths (first chunk, exception, completion)
+    def run(robot, prompt, header: "\nAI:\n   ", spinner_message: "Processing...", tools: nil)
+      @spinner.reset
+      @spinner.update(title: spinner_message)
+      @spinner.auto_spin
+      streamed = []
+      header_printed = false
+      in_think_block = false  # tracks position inside a <think>...</think> span across chunks
+      start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+      streaming_block = proc do |chunk|
+        text = chunk.respond_to?(:content) ? chunk.content.to_s : chunk.to_s
+        next if text.empty?
+
+        # qwen3 and similar local reasoning models embed thinking inline in the
+        # content stream wrapped in <think>...</think> tags. Filter them out
+        # unless --thinking is on. Tag boundaries may split across chunks, so
+        # in_think_block persists across calls via the closure.
+        unless show_thinking?
+          text, in_think_block = filter_thinking(text, in_think_block)
+          next if text.empty?
+        end
+
+        unless header_printed
+          @spinner.stop
+          print header
+          header_printed = true
+        end
+
+        streamed << text
+        $stdout.print(text)
+      end
+
+      tools_param = resolve_tools_param(tools, robot)
+
+      begin
+        result = robot.run(prompt, mcp: :inherit, tools: tools_param, &streaming_block)
+      rescue Exception # rubocop:disable Lint/RescueException
+        @spinner.stop unless header_printed
+        raise
+      end
+
+      @spinner.stop unless header_printed
+      elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
+      content = streamed.empty? ? nil : streamed.join
+      [result, content, elapsed]
+    end
+
+    private
+
+    # Translate the resolved tool list into robot_lab's ToolConfig vocabulary,
+    # then clamp it to the provider's limit:
+    #   nil   -> :inherit  (no filter active / filter errored — use the full set)
+    #   []    -> :none     (filter ran and found nothing relevant — send no tools)
+    #   names -> names     (filtered subset; ToolConfig.filter_tools applies them)
+    # Distinguishing [] from nil is what lets a "nothing relevant" turn send zero
+    # tools instead of the whole build-time set.
+    def resolve_tools_param(tools, robot)
+      param =
+        if tools.nil?
+          :inherit
+        elsif tools.empty?
+          :none
+        else
+          tools
+        end
+
+      enforce_tool_cap(param, robot)
+    end
+
+    # Clamp the effective tool list to the provider's maximum. Returns the
+    # value unchanged when it's already within budget (including :none, and
+    # :inherit when the robot's own tool count is under the cap). When over,
+    # expands :inherit to the robot's tool names, trims to the cap, and warns —
+    # a reduced tool set beats a failed turn.
+    def enforce_tool_cap(tools_param, robot)
+      return tools_param if tools_param == :none
+
+      max   = max_tools
+      names = tools_param == :inherit ? robot_tool_names(robot) : tools_param
+      size  = names.size
+      return tools_param if size <= max
+
+      dropped = size - max
+      $stderr.puts(
+        "⚠ Tool list (#{size}) exceeds the provider limit of #{max}; " \
+        "sending #{max}, dropping #{dropped}. Enable --auto-tool-filter or reduce " \
+        "the available tools to control which ones are sent."
+      )
+      names.first(max)
+    end
+
+    # The provider tool cap, from config.max_tools when set, else the default.
+    def max_tools
+      configured = AIA.respond_to?(:config) && AIA.config.respond_to?(:max_tools) ? AIA.config.max_tools : nil
+      configured&.positive? ? configured : DEFAULT_MAX_TOOLS
+    end
+
+    # The robot's full set of tool names (local + MCP). Used only to size and
+    # trim an over-limit :inherit set.
+    def robot_tool_names(robot)
+      local = robot.respond_to?(:local_tools) ? Array(robot.local_tools) : []
+      mcp   = robot.respond_to?(:mcp_tools)   ? Array(robot.mcp_tools)   : []
+      (local + mcp).map { |t| t.respond_to?(:name) ? t.name : t.class.name }
+    end
+
+    def show_thinking?
+      AIA.config&.flags&.thinking
+    end
+
+    # Strip <think>...</think> spans from a streaming chunk, handling the case
+    # where tag boundaries fall between chunk deliveries.
+    #
+    # @param text [String] raw chunk text
+    # @param in_think_block [Boolean] whether a <think> tag is currently open
+    # @return [Array(String, Boolean)] [filtered_text, updated_in_think_block]
+    def filter_thinking(text, in_think_block)
+      output = +''
+
+      until text.empty?
+        if in_think_block
+          if (idx = text.index('</think>'))
+            in_think_block = false
+            text = text[(idx + '</think>'.length)..]
+          else
+            break  # entire remaining chunk is thinking — discard
+          end
+        elsif (idx = text.index('<think>'))
+          output << text[0...idx]
+          in_think_block = true
+          text = text[(idx + '<think>'.length)..]
+        else
+          output << text
+          break
+        end
+      end
+
+      [output, in_think_block]
+    end
+  end
+end

data/lib/aia/system_prompt_assembler.rb

@@ -0,0 +1,92 @@
+# 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)
+      prompts_cfg   = config.prompts
+      system_prompt = prompts_cfg.system_prompt
+
+      role_id = model_spec&.role || prompts_cfg.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(prompts_cfg&.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]
+    # :reek:TooManyStatements -- builds the identity line plus a roster entry per teammate; one cohesive prompt fragment
+    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|
+          entry_spec = entry[:spec]
+          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)
+      prompts_cfg  = config.prompts
+      roles_prefix = prompts_cfg.roles_prefix
+      unless role_id.start_with?(roles_prefix)
+        role_id = "#{roles_prefix}/#{role_id}"
+      end
+
+      role_file = File.join(prompts_cfg.dir, "#{role_id}#{prompts_cfg.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,207 @@
+# 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]
+    # :reek:LongParameterList { max_params: 6 } -- one keyword per optional task attribute; callers set only what they need
+    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)
+      task_id = task.id
+
+      @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: }
+    # :reek:BooleanParameter -- ephemeral: tags a plan for auto-gc at session end; a second method would duplicate the whole build
+    # :reek:TooManyStatements -- plan build: create the plan task, then per step a child task, labels, and ordering dependency
+    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]
+    # :reek:TooManyStatements -- one board report: totals line, per-assignee open/done counts, unassigned tail
+    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/timing.rb

@@ -0,0 +1,15 @@
+# lib/aia/timing.rb
+
+module AIA
+  # Monotonic-clock instrumentation shared by benchmark-reporting code.
+  module Timing
+    module_function
+
+    # Run the block and return [result, elapsed_seconds].
+    def timed
+      t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      result = yield
+      [result, Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0]
+    end
+  end
+end