aia 1.1.0 → 2.0.0.0.pre.alpha

data/lib/aia/session_tracker.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+# lib/aia/session_tracker.rb
+#
+# Tracks session metrics and outcomes for the learning loop.
+# Records per-turn data: model, tokens, cost, latency, decisions.
+
+module AIA
+  class SessionTracker
+    attr_reader :turn_count, :total_cost, :total_tokens, :turns
+
+    def initialize
+      @turn_count = 0
+      @total_cost = 0.0
+      @total_tokens = 0
+      @turns = []
+    end
+
+    # Record a completed turn.
+    #
+    # For network results (SimpleFlow::Result), records one entry per
+    # robot so the /cost directive can show per-model breakdowns.
+    #
+    # @param model [String] model used (ignored for network results)
+    # @param input [String] user input
+    # @param result the LLM response
+    # @param decisions [Hash, nil] routing decisions for this turn
+    # @param elapsed [Float, nil] seconds the model took to respond
+    def record_turn(model:, input:, result:, decisions: nil, elapsed: nil)
+      if defined?(SimpleFlow::Result) && result.is_a?(SimpleFlow::Result)
+        record_network_turn(input: input, flow_result: result, decisions: decisions, elapsed: elapsed)
+        return
+      end
+
+      @turn_count += 1
+
+      metrics = extract_metrics(result)
+      @total_cost += metrics[:cost]
+      @total_tokens += metrics[:tokens]
+
+      @turns << {
+        model: model,
+        input_length: input.to_s.length,
+        input_tokens: metrics[:input_tokens],
+        output_tokens: metrics[:output_tokens],
+        tokens: metrics[:tokens],
+        cost: metrics[:cost],
+        elapsed: elapsed || 0,
+        decisions: decisions&.to_h,
+        timestamp: Time.now
+      }
+    end
+
+    # Record a model switch event.
+    #
+    # @param from [String] previous model
+    # @param to [String] new model
+    # @param reason [String] reason for the switch
+    def record_model_switch(from:, to:, reason: "user_request")
+      @turns << {
+        type: :model_switch,
+        from: from,
+        to: to,
+        reason: reason,
+        timestamp: Time.now
+      }
+    end
+
+    # Record user feedback on the last response.
+    #
+    # @param satisfied [Boolean] whether the user was satisfied
+    def record_user_feedback(satisfied:)
+      return if @turns.empty?
+      @turns.last[:user_satisfied] = satisfied
+    end
+
+    # Export session stats as a hash for KBS fact assertion.
+    #
+    # @return [Hash] session statistics
+    def to_facts
+      {
+        turn_count: @turn_count,
+        total_cost: @total_cost,
+        total_tokens: @total_tokens
+      }
+    end
+
+    # Reset all tracked data.
+    def reset!
+      @turn_count = 0
+      @total_cost = 0.0
+      @total_tokens = 0
+      @turns.clear
+    end
+
+    private
+
+    # Expand a network SimpleFlow::Result into one turn entry per robot.
+    # Computes TF-IDF similarity of each response against the first.
+    # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+    def record_network_turn(input:, flow_result:, decisions: nil, elapsed: nil)
+      @turn_count += 1
+      now = Time.now
+
+      # Collect robot data in order for similarity scoring
+      robot_entries = []
+      response_texts = []
+
+      # rubocop:disable Metrics/BlockLength
+      flow_result.context.each do |task_name, robot_result|
+        next if task_name == :run_params
+        next unless robot_result.respond_to?(:raw)
+
+        raw = robot_result.raw
+        input_tokens  = (raw.respond_to?(:input_tokens) && raw.input_tokens) || 0
+        output_tokens = (raw.respond_to?(:output_tokens) && raw.output_tokens) || 0
+        tokens = input_tokens + output_tokens
+
+        model_id = extract_model_id_from_raw(raw)
+        model_id ||= robot_result.respond_to?(:robot_name) ? robot_result.robot_name : task_name.to_s
+
+        cost = tokens.positive? ? compute_cost_for_model(model_id, input_tokens, output_tokens) : 0.0
+        robot_elapsed = robot_result.respond_to?(:duration) ? (robot_result.duration || 0) : 0
+
+        text = if robot_result.respond_to?(:reply)
+                 robot_result.reply.to_s
+               elsif robot_result.respond_to?(:content)
+                 robot_result.content.to_s
+               else
+                 ""
+               end
+        # rubocop:enable Metrics/BlockLength
+        response_texts << text
+
+        robot_entries << {
+          model: model_id,
+          input_length: input.to_s.length,
+          input_tokens: input_tokens,
+          output_tokens: output_tokens,
+          tokens: tokens,
+          cost: cost,
+          elapsed: robot_elapsed,
+          decisions: decisions&.to_h,
+          timestamp: now
+        }
+      end
+      # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+
+      # Compute similarity scores (first model is reference)
+      scores = if robot_entries.size > 1
+                 SimilarityScorer.score(response_texts)
+               else
+                 Array.new(robot_entries.size)
+               end
+
+      robot_entries.each_with_index do |entry, i|
+        entry[:similarity] = scores[i]
+        @total_cost += entry[:cost]
+        @total_tokens += entry[:tokens]
+        @turns << entry
+      end
+    end
+
+    def extract_model_id_from_raw(raw)
+      return nil unless raw
+      return raw.model_id if raw.respond_to?(:model_id) && raw.model_id
+      return raw.model    if raw.respond_to?(:model)    && raw.model
+      nil
+    end
+
+    def compute_cost_for_model(model_id, input_tokens, output_tokens)
+      result = CostCalculator.calculate(model_id: model_id, input_tokens: input_tokens, output_tokens: output_tokens)
+      result[:available] ? result[:total_cost] : 0.0
+    end
+
+    def extract_metrics(result)
+      input_tokens = 0
+      output_tokens = 0
+
+      # Prefer raw RubyLLM::Message (has token data); fall back to output messages
+      source = if result.respond_to?(:raw) && result.raw.respond_to?(:input_tokens)
+                 result.raw
+               elsif result.respond_to?(:output) && result.output.respond_to?(:last)
+                 result.output.last
+               end
+
+      if source.respond_to?(:input_tokens) && source.input_tokens
+        input_tokens = source.input_tokens || 0
+        output_tokens = source.output_tokens || 0
+      end
+
+      tokens = input_tokens + output_tokens
+      cost = tokens.positive? ? compute_cost(result, input_tokens, output_tokens) : 0.0
+
+      { input_tokens: input_tokens, output_tokens: output_tokens, tokens: tokens, cost: cost }
+    end
+
+    # Compute cost from token counts and model pricing.
+    # Falls back to 0.0 if pricing info is unavailable.
+    def compute_cost(result, input_tokens, output_tokens)
+      model_id = if result.respond_to?(:robot_name)
+                   result.robot_name
+                 elsif result.respond_to?(:model_id)
+                   result.model_id
+                 end
+      compute_cost_for_model(model_id, input_tokens, output_tokens)
+    end
+  end
+end

data/lib/aia/similarity_scorer.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+# lib/aia/similarity_scorer.rb
+#
+# Computes TF-IDF cosine similarity between LLM responses.
+# Uses the classifier gem's TF-IDF vectorizer with Porter stemming
+# so that paraphrased responses ("focused" / "focuses") score high.
+
+require 'classifier'
+require_relative 'tfidf_math'
+
+module AIA
+  class SimilarityScorer
+    # Compute pairwise similarity of each response against the first.
+    #
+    # @param responses [Array<String>] ordered response texts (first is reference)
+    # @return [Array<Float, nil>] similarity scores (nil for first, 0.0..1.0 for rest)
+    def self.score(responses)
+      return Array.new(responses.size) if responses.size < 2
+
+      texts = responses.map { |r| r.to_s.strip }
+      return Array.new(responses.size) if texts.first.empty?
+
+      tfidf = Classifier::TFIDF.new
+      tfidf.fit(texts)
+      vectors = texts.map { |t| tfidf.transform(t) }
+
+      vectors.each_with_index.map do |_vec, i|
+        if i.zero?
+          nil # reference model -- no comparison
+        else
+          AIA::TFIDFMath.cosine_similarity(vectors[0], vectors[i])
+        end
+      end
+    rescue StandardError
+      Array.new(responses.size)
+    end
+  end
+end

data/lib/aia/skill_utils.rb

@@ -51,9 +51,113 @@ module AIA
       content[(end_marker + 4)..].lstrip
     end
 
+    # Resolve the effective skills base directory from config.
+    # Skills live in config.skills.dir (set via --skills-dir, the -c config file,
+    # or the ~/.prompts/skills default). This is the single resolver used by both
+    # skill loading and `--list-skills`, so what is listed is always loadable.
+    #
+    # @param config [AIA::Config] the AIA configuration
+    # @return [String, nil] resolved base directory, or nil if not configured
+    def skills_base_dir(config)
+      config.skills&.dir
+    end
+
+    # Render the available skills as a markdown report — the body of --list-skills.
+    # Resolves the directory via skills_base_dir (same as loading) and respects a
+    # -c config file because it runs after config is built.
+    #
+    # @param config [AIA::Config]
+    # @return [String] markdown listing, or a "no skills" message
+    def list_skills_markdown(config)
+      dir = skills_base_dir(config)
+
+      unless dir && Dir.exist?(dir)
+        return "No skills directory found at #{dir}\n" \
+               "Create this directory and add skill subdirectories to use skills."
+      end
+
+      skill_ids = Dir.glob("*/SKILL.md", base: dir).map { |f| File.dirname(f) }.sort
+      if skill_ids.empty?
+        return "No skills found in #{dir}\n" \
+               "Create subdirectories with a SKILL.md file to define skills."
+      end
+
+      skill_ids.flat_map { |id| skill_markdown_entry(dir, id) }.join("\n")
+    end
+
+    # Markdown lines for a single skill entry (heading + front-matter table).
+    # Escapes pipe characters so values can't break the table.
+    #
+    # @return [Array<String>]
+    def skill_markdown_entry(dir, skill_id)
+      front_matter = parse_front_matter(File.join(dir, skill_id, 'SKILL.md'))
+      lines = ["## #{skill_id}", ""]
+
+      if front_matter.empty?
+        lines << "_No front matter found in SKILL.md_"
+      else
+        lines << "| Key | Value |" << "|-----|-------|"
+        front_matter.each do |key, value|
+          lines << "| #{key} | #{value.to_s.gsub('|', '\\|')} |"
+        end
+      end
+
+      lines << ""
+      lines
+    end
+
+    # Load and concatenate content from multiple skills.
+    # Used by both pipeline mode (prompt text injection) and chat mode
+    # (system prompt injection) to honour the --skill CLI option.
+    #
+    # @param skill_ids [Array<String>] skill names or path-based IDs
+    # @param skills_base_dir [String] base directory for named skills
+    # @return [String, nil] joined skill bodies, or nil if none loaded
+    def load_skills_content(skill_ids, skills_base_dir)
+      ids = Array(skill_ids).reject { |s| s.nil? || s.strip.empty? }
+      return nil if ids.empty?
+      return nil unless skills_base_dir && Dir.exist?(skills_base_dir)
+
+      contents = ids.filter_map { |id| load_single_skill_content(id, skills_base_dir) }
+      contents.empty? ? nil : contents.join("\n\n")
+    end
+
+    # Load the body of a single skill (front matter stripped).
+    # Handles both name-based (looks in skills_base_dir) and path-based IDs.
+    #
+    # @param skill_id [String] skill name or path
+    # @param skills_base_dir [String] base directory for named skills
+    # @return [String, nil] skill body text, or nil on error
+    def load_single_skill_content(skill_id, skills_base_dir)
+      skill_dir = find_skill_dir(skill_id, skills_base_dir)
+      unless skill_dir
+        $stderr.puts "Warning: Skill '#{skill_id}' not found in #{skills_base_dir}"
+        return nil
+      end
+
+      raw = if File.file?(skill_dir)
+              File.read(skill_dir)
+            else
+              skill_path = File.join(skill_dir, 'SKILL.md')
+              unless File.exist?(skill_path)
+                $stderr.puts "Warning: SKILL.md not found in #{skill_dir}"
+                return nil
+              end
+              File.read(skill_path)
+            end
+
+      skill_body(raw)
+    rescue StandardError => e
+      $stderr.puts "Warning: Could not load skill '#{skill_id}': #{e.message}"
+      nil
+    end
+
     def safe_skill_path(path, dir)
       resolved = File.realpath(path)
-      resolved.start_with?(File.realpath(dir) + File::SEPARATOR) ? resolved : nil
+      root = File.realpath(dir)
+      root_with_separator = File.join(root, '')
+
+      resolved == root || resolved.start_with?(root_with_separator) ? resolved : nil
     rescue Errno::ENOENT
       nil
     end

data/lib/aia/spawn_handler.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+# lib/aia/spawn_handler.rb
+#
+# Dynamically creates specialist robots using robot_lab's spawn().
+# The primary robot determines what kind of specialist is needed,
+# spawns it on the shared bus, and collects the response.
+# Specialists are cached for reuse within the session.
+
+module AIA
+  class SpawnHandler
+    include ContentExtractor
+    include HandlerProtocol
+
+    MAX_CACHE_SIZE = 5
+
+    def initialize(robot:, ui_presenter:, tracker:)
+      @robot        = robot
+      @ui_presenter = ui_presenter
+      @tracker      = tracker
+      @spawned      = {}
+    end
+
+    attr_writer :robot
+
+    # Release all cached specialist robots.
+    def cleanup!
+      @spawned.clear
+    end
+
+    # Spawn a specialist robot to handle a prompt.
+    #
+    # @param context [HandlerContext] — reads context.prompt, context.specialist_type,
+    #   and context.spawn_spec (explicit {name:, model:, provider:, system_prompt:})
+    # @return [String, nil] specialist's response
+    def handle(context)
+      prompt  = context.prompt
+      primary = @robot.chief
+      primary.with_bus unless primary.respond_to?(:bus) && primary.bus
+
+      role, instruction, spawn_opts = resolve_specialist(context, primary, prompt)
+
+      # Spawn or reuse specialist (evict oldest when cache is full)
+      specialist = @spawned[role] ||= begin
+        evict_oldest! if @spawned.size >= MAX_CACHE_SIZE
+        primary.spawn(name: role, system_prompt: instruction, **spawn_opts)
+      end
+
+      @ui_presenter.display_info("Specialist '#{role}' responding...")
+
+      result  = specialist.run(prompt, mcp: :inherit, tools: :inherit)
+      content = extract_content(result)
+
+      # Track in TrakFlow if available
+      if AIA.task_coordinator&.available?
+        AIA.task_coordinator.create_task(
+          "Specialist: #{prompt[0, 60]}",
+          assignee: role,
+          labels:   %w[specialist spawned],
+          creator:  primary.name
+        )
+      end
+
+      @tracker.record_turn(
+        model: AIA.config.models.first.name,
+        input: prompt,
+        result: result
+      )
+
+      content
+    end
+
+    private
+
+    # Decide the specialist's role, system prompt, and any model/provider
+    # override, from (in priority order): an explicit /spawn spec, an explicit
+    # specialist type, or LLM auto-detection.
+    #
+    # @return [Array(String, String, Hash)] [role, instruction, spawn_opts]
+    def resolve_specialist(context, primary, prompt)
+      if (spec = context.spawn_spec)
+        role        = spec[:name]
+        instruction = spec[:system_prompt] || "You are #{role}."
+        [role, instruction, model_opts(spec)]
+      elsif (type = context.specialist_type)
+        [type, "You are a #{type} specialist. Answer precisely within your domain of expertise.", {}]
+      else
+        role, instruction = detect_specialist(primary, prompt)
+        [role, instruction, {}]
+      end
+    end
+
+    # Model/provider override for an explicit spawn. When a model is given we
+    # pass the provider too (even nil) so it overrides the inherited parent
+    # provider — e.g. spawning a cloud model from a local-model parent. With no
+    # model, the spawned robot inherits its parent's model and provider.
+    #
+    # @return [Hash]
+    def model_opts(spec)
+      return {} unless spec[:model]
+
+      { model: spec[:model], provider: spec[:provider] }
+    end
+
+    def evict_oldest!
+      @spawned.delete(@spawned.keys.first)
+    end
+
+    def detect_specialist(primary, prompt)
+      @ui_presenter.display_info("Determining specialist type...")
+
+      result = primary.run(<<~PROMPT, mcp: :none, tools: :none)
+        What type of specialist would best answer this question?
+        Reply with exactly two lines:
+        Line 1: specialist role (e.g., security_expert, data_scientist)
+        Line 2: one-sentence instruction for the specialist
+
+        Question: #{prompt}
+      PROMPT
+
+      reply = extract_content(result)
+      lines = reply.strip.split("\n", 2)
+      role        = lines[0]&.strip&.downcase&.gsub(/\s+/, "_") || "specialist"
+      instruction = lines[1]&.strip || "You are a #{role}."
+
+      [role, instruction]
+    end
+  end
+end

data/lib/aia/spawn_spec_parser.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require_relative 'config/model_spec'
+
+module AIA
+  # Parses the explicit form of the /spawn and /add_recruit directives into a
+  # spawn spec:
+  #
+  #   <name> <provider/model> <system prompt...>
+  #
+  # The second token is parsed as a model via {ModelSpec}, so
+  # "ollama/qwen3.6:latest" yields model "qwen3.6:latest" + provider "ollama"
+  # (and "lms/..." maps to the openai provider). Use "-" or "inherit" as the
+  # model token to keep the parent robot's model and provider.
+  #
+  # Any token of the form "skill:<id>" (anywhere after the name) is pulled out
+  # as a skill assignment and returned in :skills; "skill:a,b" lists several.
+  # The skills become the robot's role (its system prompt) when recruited.
+  class SpawnSpecParser
+    INHERIT_TOKENS = %w[- inherit].freeze
+    SKILL_TOKEN = /\Askill:(.+)\z/i
+
+    # @param args [Array<String>] directive args (two or more expected)
+    # @return [Hash] {name:, model:, provider:, system_prompt:, skills:}
+    def self.parse(args)
+      name = args[0]
+      skills, rest = extract_skills(args[1..].to_a)
+      model, provider = parse_model(rest[0])
+      system_prompt = rest[1..].to_a.join(' ').strip
+      system_prompt = nil if system_prompt.empty?
+
+      { name: name, model: model, provider: provider, system_prompt: system_prompt, skills: skills }
+    end
+
+    # Split "skill:<id>" tokens out of the token list. Returns the collected
+    # skill ids and the remaining (model + system-prompt) tokens, order intact.
+    #
+    # @param tokens [Array<String>]
+    # @return [Array(Array<String>, Array<String>)] [skills, remaining]
+    def self.extract_skills(tokens)
+      skills = []
+      remaining = tokens.reject do |token|
+        match = token.match(SKILL_TOKEN)
+        next false unless match
+
+        skills.concat(match[1].split(',').map(&:strip).reject(&:empty?))
+        true
+      end
+      [skills, remaining]
+    end
+
+    # Split a "provider/model" token into [model, provider]. Returns [nil, nil]
+    # to signal the spawned robot should inherit its parent's model/provider.
+    #
+    # @param token [String, nil]
+    # @return [Array(String, String)]
+    def self.parse_model(token)
+      return [nil, nil] if token.nil? || INHERIT_TOKENS.include?(token.downcase)
+
+      spec     = ModelSpec.new(name: token)
+      provider = spec.provider == 'lms' ? 'openai' : spec.provider
+      [spec.name, provider]
+    end
+  end
+end