collavre 0.2.5 → 0.3.1

data/app/services/collavre/orchestration/arbiter.rb

@@ -0,0 +1,257 @@
+# frozen_string_literal: true
+
+module Collavre
+  module Orchestration
+    # Arbiter decides which agents will actually respond from the qualified candidates.
+    # This implements "floor control" - preventing multiple agents from responding simultaneously.
+    #
+    # Strategies:
+    # - all: All candidates respond (original behavior)
+    # - primary_first: Primary agent responds, others only if primary unavailable
+    # - round_robin: Rotate between agents for each message
+    # - bid: Select agent based on relevance score (expertise matching)
+    #
+    class Arbiter
+      # Default confidence threshold for bid strategy
+      DEFAULT_CONFIDENCE_THRESHOLD = 0.3
+      def initialize(context, policy_resolver: nil)
+        @context = context
+        @policy_resolver = policy_resolver || PolicyResolver.new(context)
+      end
+
+      # Select which agents will respond from the candidates
+      # @param candidates [Array<User>] Qualified agents from Matcher
+      # @return [Array<User>] Agents that will actually respond
+      def select(candidates)
+        return [] if candidates.empty?
+
+        strategy = @policy_resolver.arbitration_strategy
+        selected = apply_strategy(strategy, candidates)
+
+        # Apply max_responders limit if set
+        max = @policy_resolver.max_responders
+        selected = selected.take(max) if max.present? && max.positive?
+
+        selected
+      end
+
+      private
+
+      def apply_strategy(strategy, candidates)
+        case strategy
+        when "all"
+          strategy_all(candidates)
+        when "primary_first"
+          strategy_primary_first(candidates)
+        when "round_robin"
+          strategy_round_robin(candidates)
+        when "bid"
+          strategy_bid(candidates)
+        else
+          # Unknown strategy, default to all
+          Rails.logger.warn("[Arbiter] Unknown strategy '#{strategy}', falling back to 'all'")
+          strategy_all(candidates)
+        end
+      end
+
+      # All candidates respond
+      def strategy_all(candidates)
+        candidates
+      end
+
+      # Primary agent responds if available, otherwise first candidate
+      def strategy_primary_first(candidates)
+        primary_id = @policy_resolver.primary_agent_id
+        return candidates.take(1) if primary_id.blank?
+
+        primary = candidates.find { |agent| agent.id == primary_id }
+        primary ? [ primary ] : candidates.take(1)
+      end
+
+      # Rotate between agents using Rails cache for state
+      def strategy_round_robin(candidates)
+        return candidates.take(1) if candidates.size <= 1
+
+        topic_id = @context.dig("topic", "id")
+        return candidates.take(1) if topic_id.blank?
+
+        # Sort candidates by id for consistent ordering
+        sorted_candidates = candidates.sort_by(&:id)
+
+        # Get last responder from cache
+        cache_key = "orchestrator:round_robin:topic:#{topic_id}"
+        last_responder_id = Rails.cache.read(cache_key)
+
+        # Find next agent in rotation
+        selected = if last_responder_id.present?
+                     find_next_in_rotation(sorted_candidates, last_responder_id)
+        else
+                     sorted_candidates.first
+        end
+
+        # Store current responder for next rotation
+        Rails.cache.write(cache_key, selected.id, expires_in: 24.hours)
+
+        [ selected ]
+      end
+
+      def find_next_in_rotation(candidates, last_responder_id)
+        last_index = candidates.find_index { |a| a.id == last_responder_id }
+
+        if last_index.nil?
+          # Last responder not in current candidates, start from beginning
+          candidates.first
+        else
+          # Get next agent, wrapping around to beginning
+          next_index = (last_index + 1) % candidates.size
+          candidates[next_index]
+        end
+      end
+
+      # Select agent based on relevance/expertise scoring
+      # Returns highest scoring agent if above threshold, otherwise empty
+      def strategy_bid(candidates)
+        return [] if candidates.empty?
+
+        threshold = @policy_resolver.confidence_threshold || DEFAULT_CONFIDENCE_THRESHOLD
+        message_text = extract_message_text
+
+        # Score each candidate
+        scored = candidates.map do |agent|
+          score = calculate_relevance_score(agent, message_text)
+          { agent: agent, score: score }
+        end
+
+        # Sort by score descending
+        scored.sort_by! { |s| -s[:score] }
+
+        # Return highest scoring agent if above threshold
+        best = scored.first
+        if best[:score] >= threshold
+          [ best[:agent] ]
+        else
+          # No agent meets threshold - return empty or fallback to first
+          # Based on policy, could return first candidate as fallback
+          @policy_resolver.bid_fallback_enabled? ? [ candidates.first ] : []
+        end
+      end
+
+      # Calculate relevance score for an agent (0.0 - 1.0)
+      def calculate_relevance_score(agent, message_text)
+        return 0.0 if message_text.blank?
+
+        scores = []
+
+        # 1. Keyword matching with agent's expertise/system_prompt
+        keyword_score = calculate_keyword_score(agent, message_text)
+        scores << keyword_score * 0.5  # 50% weight
+
+        # 2. Recent conversation participation
+        participation_score = calculate_participation_score(agent)
+        scores << participation_score * 0.3  # 30% weight
+
+        # 3. Agent specialty tags (if defined in metadata)
+        specialty_score = calculate_specialty_score(agent, message_text)
+        scores << specialty_score * 0.2  # 20% weight
+
+        scores.sum
+      end
+
+      def extract_message_text
+        # Extract text from the triggering comment
+        @context.dig("comment", "content") ||
+          @context.dig("comment", "body") ||
+          @context.dig("message", "content") ||
+          ""
+      end
+
+      # Score based on keyword overlap between message and agent's expertise
+      def calculate_keyword_score(agent, message_text)
+        expertise_text = extract_expertise_text(agent)
+        return 0.0 if expertise_text.blank?
+
+        message_words = tokenize(message_text.downcase)
+        expertise_words = tokenize(expertise_text.downcase)
+
+        return 0.0 if message_words.empty? || expertise_words.empty?
+
+        # Calculate Jaccard-like similarity
+        common_words = message_words & expertise_words
+        union_size = (message_words + expertise_words).uniq.size
+
+        return 0.0 if union_size.zero?
+
+        # Weighted by how many message words appear in expertise
+        # (more relevant if agent knows about what user is asking)
+        message_coverage = common_words.size.to_f / message_words.size
+        expertise_density = common_words.size.to_f / [ expertise_words.size, 50 ].min
+
+        (message_coverage * 0.7 + expertise_density * 0.3).clamp(0.0, 1.0)
+      end
+
+      def extract_expertise_text(agent)
+        texts = []
+
+        # From agent's system_prompt (primary source for AI agents)
+        texts << agent.system_prompt if agent.respond_to?(:system_prompt) && agent.system_prompt.present?
+
+        # From AI agent profile (for nested ai_agent association)
+        if agent.respond_to?(:ai_agent) && agent.ai_agent.present?
+          texts << agent.ai_agent.system_prompt if agent.ai_agent.respond_to?(:system_prompt)
+          texts << agent.ai_agent.description if agent.ai_agent.respond_to?(:description)
+        end
+
+        # From name (can indicate specialty)
+        texts << agent.name if agent.respond_to?(:name)
+
+        texts.compact.join(" ")
+      end
+
+      # Score based on recent participation in this topic
+      def calculate_participation_score(agent)
+        topic_id = @context.dig("topic", "id")
+        return 0.0 if topic_id.blank?
+
+        # Check cache for recent comments by this agent in topic
+        cache_key = "orchestrator:participation:topic:#{topic_id}:agent:#{agent.id}"
+        cached = Rails.cache.read(cache_key)
+        return cached if cached.present?
+
+        # Query recent comments (last 24 hours)
+        recent_count = Comment
+          .where(topic_id: topic_id, user_id: agent.id)
+          .where("created_at > ?", 24.hours.ago)
+          .count
+
+        # Normalize: 0 comments = 0, 5+ comments = 1.0
+        score = [ recent_count / 5.0, 1.0 ].min
+
+        Rails.cache.write(cache_key, score, expires_in: 5.minutes)
+        score
+      end
+
+      # Score based on specialty tags matching message content
+      def calculate_specialty_score(agent, message_text)
+        return 0.0 unless agent.respond_to?(:metadata)
+
+        tags = agent.metadata&.dig("specialty_tags") || []
+        return 0.0 if tags.empty?
+
+        message_lower = message_text.downcase
+        matched = tags.count { |tag| message_lower.include?(tag.to_s.downcase) }
+
+        [ matched.to_f / tags.size, 1.0 ].min
+      end
+
+      # Simple tokenization for keyword matching
+      def tokenize(text)
+        # Remove punctuation, split by whitespace, filter short words
+        text
+          .gsub(/[^\p{L}\p{N}\s]/, " ")
+          .split(/\s+/)
+          .reject { |w| w.length < 3 }
+          .uniq
+      end
+    end
+  end
+end

data/app/services/collavre/orchestration/loop_breaker.rb

@@ -0,0 +1,294 @@
+# frozen_string_literal: true
+
+module Collavre
+  module Orchestration
+    # LoopBreaker detects and prevents infinite loops in agent orchestration.
+    #
+    # Detects:
+    # - Ping-pong: Same two agents messaging back and forth too many times
+    # - Creative retry: Too many tasks created on same creative in time window
+    # - Task timeout: Single task running too long
+    # - Token spike: Abnormal token usage in short time window
+    #
+    # Usage:
+    #   breaker = LoopBreaker.new(context, policy_resolver: resolver)
+    #   result = breaker.check
+    #   if result.should_break?
+    #     # Handle loop detection - escalate to human
+    #   end
+    #
+    class LoopBreaker
+      CACHE_PREFIX = "loop_breaker"
+      CACHE_EXPIRY = 1.hour
+
+      Result = Data.define(:should_break, :reason, :details) do
+        def should_break?
+          should_break
+        end
+
+        def safe?
+          !should_break
+        end
+      end
+
+      def initialize(context, policy_resolver: nil)
+        @context = context
+        @policy_resolver = policy_resolver || PolicyResolver.new(context)
+        @config = @policy_resolver.loop_breaker_config
+      end
+
+      # Main entry point - checks all loop conditions
+      def check
+        return Result.new(should_break: false, reason: nil, details: {}) unless enabled?
+
+        # Check each condition
+        checks = [
+          check_ping_pong,
+          check_creative_retry,
+          check_task_timeout,
+          check_token_spike
+        ]
+
+        # Return first violation found
+        violation = checks.find(&:should_break?)
+        violation || Result.new(should_break: false, reason: nil, details: {})
+      end
+
+      # Record an interaction for ping-pong detection
+      def record_interaction(from_agent_id, to_agent_id, creative_id)
+        key = "#{CACHE_PREFIX}:ping_pong_history:#{creative_id}"
+        interactions = Rails.cache.read(key) || []
+        interactions << { at: Time.current.to_i, from: from_agent_id, to: to_agent_id }
+
+        # Keep only recent interactions (within window)
+        window_start = (Time.current - ping_pong_window).to_i
+        interactions = interactions.select { |i| i[:at] >= window_start }
+
+        Rails.cache.write(key, interactions, expires_in: CACHE_EXPIRY)
+      end
+
+      # Record a task creation for creative retry detection
+      def record_task(creative_id, agent_id)
+        key = creative_tasks_key(creative_id)
+        tasks = Rails.cache.read(key) || []
+        tasks << { at: Time.current.to_i, agent_id: agent_id }
+
+        # Keep only tasks within window
+        window_start = (Time.current - creative_retry_window).to_i
+        tasks = tasks.select { |t| t[:at] >= window_start }
+
+        Rails.cache.write(key, tasks, expires_in: CACHE_EXPIRY)
+      end
+
+      # Record token usage for spike detection
+      def record_tokens(agent_id, tokens_used)
+        key = token_usage_key(agent_id)
+        usage = Rails.cache.read(key) || []
+        usage << { at: Time.current.to_i, tokens: tokens_used }
+
+        # Keep only usage within window
+        window_start = (Time.current - token_spike_window).to_i
+        usage = usage.select { |u| u[:at] >= window_start }
+
+        Rails.cache.write(key, usage, expires_in: CACHE_EXPIRY)
+      end
+
+      # Reset tracking for a creative (after human intervention)
+      def reset_for_creative(creative_id)
+        # Clear all related cache keys
+        Rails.cache.delete_matched("#{CACHE_PREFIX}:creative:#{creative_id}:*")
+        Rails.cache.delete_matched("#{CACHE_PREFIX}:ping_pong:*:#{creative_id}")
+      end
+
+      private
+
+      def enabled?
+        @config["enabled"] == true
+      end
+
+      # Detect ping-pong between agents
+      def check_ping_pong
+        creative_id = @context.dig("creative", "id")
+        return safe_result unless creative_id
+
+        # Check the ping-pong tracking key for this creative
+        key = "#{CACHE_PREFIX}:ping_pong_history:#{creative_id}"
+        interactions = Rails.cache.read(key) || []
+
+        # Count exchanges for each agent pair
+        pair_exchanges = count_pair_exchanges(interactions)
+
+        pair_exchanges.each do |pair, count|
+          if count >= ping_pong_threshold
+            return Result.new(
+              should_break: true,
+              reason: :ping_pong,
+              details: {
+                agents: pair,
+                creative_id: creative_id,
+                exchange_count: count,
+                threshold: ping_pong_threshold
+              }
+            )
+          end
+        end
+
+        safe_result
+      end
+
+      # Detect too many tasks on same creative
+      def check_creative_retry
+        creative_id = @context.dig("creative", "id")
+        return safe_result unless creative_id
+
+        key = creative_tasks_key(creative_id)
+        tasks = Rails.cache.read(key) || []
+
+        # Filter to window
+        window_start = (Time.current - creative_retry_window).to_i
+        recent_tasks = tasks.select { |t| t[:at] >= window_start }
+
+        if recent_tasks.size >= creative_retry_threshold
+          return Result.new(
+            should_break: true,
+            reason: :creative_retry_exceeded,
+            details: {
+              creative_id: creative_id,
+              task_count: recent_tasks.size,
+              threshold: creative_retry_threshold,
+              window_minutes: @config["creative_retry_window_minutes"]
+            }
+          )
+        end
+
+        safe_result
+      end
+
+      # Detect tasks running too long
+      def check_task_timeout
+        # Find running tasks for this context (using topic_id as Task doesn't have creative_id)
+        topic_id = @context.dig("topic", "id")
+
+        return safe_result unless topic_id
+
+        timeout_threshold = task_timeout_minutes.minutes.ago
+
+        timed_out_task = Task.where(status: "running", topic_id: topic_id)
+                              .where("created_at < ?", timeout_threshold)
+                              .first
+
+        if timed_out_task
+          return Result.new(
+            should_break: true,
+            reason: :task_timeout,
+            details: {
+              task_id: timed_out_task.id,
+              agent_id: timed_out_task.agent_id,
+              started_at: timed_out_task.created_at,
+              timeout_minutes: task_timeout_minutes
+            }
+          )
+        end
+
+        safe_result
+      end
+
+      # Detect token usage spikes
+      def check_token_spike
+        # Check for current agent or all agents in creative
+        agent_id = @context.dig("agent", "id") || @context.dig("user", "id")
+        return safe_result unless agent_id
+
+        key = token_usage_key(agent_id)
+        usage = Rails.cache.read(key) || []
+
+        # Sum tokens in window
+        window_start = (Time.current - token_spike_window).to_i
+        recent_usage = usage.select { |u| u[:at] >= window_start }
+        total_tokens = recent_usage.sum { |u| u[:tokens] }
+
+        if total_tokens >= token_spike_threshold
+          return Result.new(
+            should_break: true,
+            reason: :token_spike,
+            details: {
+              agent_id: agent_id,
+              tokens_used: total_tokens,
+              threshold: token_spike_threshold,
+              window_minutes: @config["token_spike_window_minutes"]
+            }
+          )
+        end
+
+        safe_result
+      end
+
+      # Count exchanges for each pair of agents
+      def count_pair_exchanges(interactions)
+        return {} if interactions.size < 2
+
+        pair_counts = Hash.new(0)
+        sorted = interactions.sort_by { |i| i[:at] }
+
+        sorted.each_cons(2) do |prev, curr|
+          # Count as exchange if direction reversed (A→B then B→A)
+          if prev[:from] == curr[:to] && prev[:to] == curr[:from]
+            # Normalize pair key (smaller id first)
+            pair = [ prev[:from], prev[:to] ].sort
+            pair_counts[pair] += 1
+          end
+        end
+
+        pair_counts
+      end
+
+      def safe_result
+        Result.new(should_break: false, reason: nil, details: {})
+      end
+
+      # Cache keys
+      def ping_pong_key(agent1_id, agent2_id, creative_id)
+        # Normalize key so A-B and B-A use same key
+        sorted = [ agent1_id, agent2_id ].sort
+        "#{CACHE_PREFIX}:ping_pong:#{sorted[0]}-#{sorted[1]}:#{creative_id}"
+      end
+
+      def creative_tasks_key(creative_id)
+        "#{CACHE_PREFIX}:creative:#{creative_id}:tasks"
+      end
+
+      def token_usage_key(agent_id)
+        "#{CACHE_PREFIX}:agent:#{agent_id}:tokens:#{Date.current}"
+      end
+
+      # Config accessors
+      def ping_pong_threshold
+        @config["ping_pong_threshold"] || 5
+      end
+
+      def ping_pong_window
+        30.minutes # Fixed window for ping-pong detection
+      end
+
+      def creative_retry_threshold
+        @config["creative_retry_threshold"] || 10
+      end
+
+      def creative_retry_window
+        (@config["creative_retry_window_minutes"] || 30).minutes
+      end
+
+      def task_timeout_minutes
+        @config["task_timeout_minutes"] || 60
+      end
+
+      def token_spike_threshold
+        @config["token_spike_threshold"] || 50_000
+      end
+
+      def token_spike_window
+        (@config["token_spike_window_minutes"] || 10).minutes
+      end
+    end
+  end
+end

data/app/services/collavre/orchestration/matcher.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Collavre
+  module Orchestration
+    # Matcher determines which AI agents are qualified to respond to an event.
+    #
+    # Matching strategies (in priority order):
+    # 1. Mention-based: If a user is @mentioned, route exclusively to that user
+    #    - If mentioned user is AI agent → route to that agent only
+    #    - If mentioned user is human → no AI agents respond
+    # 2. Expression-based: Evaluate each agent's routing_expression (Liquid)
+    #
+    # Permission checks:
+    # - All agents need feedback permission on the creative to respond
+    # - searchable only affects discoverability, not response permission
+    #
+    class Matcher
+      def initialize(context)
+        @context = context
+      end
+
+      # Returns Array of User (AI agents) that are qualified to respond
+      def match
+        # Priority 1: Mention-based routing (exclusive)
+        mentioned_result = match_by_mention
+        return mentioned_result unless mentioned_result.nil?
+
+        # Priority 2: Liquid expression routing (fallback)
+        match_by_expression
+      end
+
+      private
+
+      # Returns Array of agents if mention found, nil if no mention
+      # When mention IS found, this is exclusive routing
+      def match_by_mention
+        mentioned_user_data = @context.dig("chat", "mentioned_user")
+        return nil unless mentioned_user_data && mentioned_user_data["id"]
+
+        mentioned_user = User.find_by(id: mentioned_user_data["id"])
+        return nil unless mentioned_user
+
+        # Mention found — exclusive routing
+        # If mentioned user is not an AI agent, no AI agents should receive it
+        return [] unless mentioned_user.ai_user?
+
+        # Permission check for mentioned AI agent
+        return [] unless has_creative_permission?(mentioned_user)
+
+        [ mentioned_user ]
+      end
+
+      def match_by_expression
+        # Find all AI agents with routing expressions
+        # Order by id for consistent ordering (important for round_robin strategy)
+        agents = User.where.not(llm_vendor: nil).where.not(routing_expression: [ nil, "" ]).order(:id)
+
+        agents.select do |agent|
+          next false unless has_creative_permission?(agent)
+
+          evaluate_routing_expression(agent)
+        end
+      end
+
+      def evaluate_routing_expression(agent)
+        expression = agent.routing_expression.strip
+
+        # Wrap in if block if not already a Liquid tag
+        unless expression.start_with?("{%")
+          expression = "{% if #{expression} %}true{% endif %}"
+        end
+
+        # Add agent to context for self-reference
+        agent_context = @context.merge("agent" => agent.as_json(only: [ :id, :name, :email ]))
+
+        template = Liquid::Template.parse(expression)
+        result = template.render(agent_context)
+
+        result.strip == "true"
+      rescue StandardError => e
+        Rails.logger.error("[Matcher] Routing error for agent #{agent.id}: #{e.message}")
+        false
+      end
+
+      def has_creative_permission?(agent)
+        # All agents need feedback permission on the creative to respond
+        # searchable only affects discoverability, not response permission
+        creative_id = @context.dig("creative", "id") || @context.dig(:creative, :id)
+        return false unless creative_id
+
+        creative = Creative.find_by(id: creative_id)
+        return false unless creative
+
+        creative.has_permission?(agent, :feedback)
+      end
+    end
+  end
+end