collavre 0.2.5 → 0.3.1

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

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+module Collavre
+  module Orchestration
+    # PolicyResolver finds and merges applicable policies for a given context.
+    #
+    # Policy precedence (later overrides earlier):
+    # 1. Global policies
+    # 2. Creative-level policies
+    # 3. Topic-level policies
+    # 4. Agent-level policies (for scheduling)
+    #
+    # Usage:
+    #   resolver = PolicyResolver.new(context)
+    #   resolver.arbitration_config
+    #   # => { "strategy" => "primary_first", "max_responders" => 1 }
+    #
+    class PolicyResolver
+      # Default configurations when no policy is set
+      DEFAULTS = {
+        "arbitration" => {
+          "strategy" => "all",
+          "max_responders" => nil # nil means unlimited
+        },
+        "scheduling" => {
+          "max_concurrent_jobs" => 5,
+          "daily_token_limit" => 100_000,
+          "rate_limit_per_minute" => 20,
+          "backoff_strategy" => "exponential",
+          "topic_max_concurrent_jobs" => 1,
+          # Self-reflection settings
+          "self_reflection_enabled" => false,
+          "confidence_threshold" => 70,
+          "max_retries" => 3,
+          "retry_delay_seconds" => 5,
+          # Loop breaker settings
+          "loop_breaker_enabled" => false,
+          "ping_pong_threshold" => 5,           # Max back-and-forth between same agents
+          "creative_retry_threshold" => 10,     # Max tasks on same creative in time window
+          "creative_retry_window_minutes" => 30,
+          "task_timeout_minutes" => 60,         # Max time for a single task
+          "token_spike_threshold" => 50_000,    # Token usage spike in window
+          "token_spike_window_minutes" => 10
+        },
+        "stuck_detection" => {
+          "enabled" => true,
+          "task_stuck_threshold_minutes" => 30,       # Task running for > N minutes
+          "creative_stall_threshold_minutes" => 120,  # Creative no progress for > N minutes
+          "create_system_comment" => true             # Create system comment on escalation
+        }
+      }.freeze
+
+      def initialize(context)
+        @context = context
+      end
+
+      # Get merged arbitration config
+      def arbitration_config
+        @arbitration_config ||= merge_policies("arbitration")
+      end
+
+      # Get merged scheduling config for a specific agent
+      def scheduling_config_for(agent)
+        base = merge_policies("scheduling")
+
+        # Layer agent-specific policies on top
+        agent_policies = OrchestratorPolicy.for_agent(agent.id, policy_type: "scheduling")
+        agent_policies.each do |policy|
+          base = base.merge(policy.config)
+        end
+
+        base
+      end
+
+      # Get merged scheduling config (without agent-specific overrides)
+      def scheduling_config
+        @scheduling_config ||= merge_policies("scheduling")
+      end
+
+      # Topic-level concurrency limit
+      def topic_max_concurrent_jobs
+        scheduling_config["topic_max_concurrent_jobs"]
+      end
+
+      # Convenience methods
+      def arbitration_strategy
+        arbitration_config["strategy"]
+      end
+
+      def max_responders
+        arbitration_config["max_responders"]
+      end
+
+      def primary_agent_id
+        arbitration_config["primary_agent_id"]
+      end
+
+      # Bid strategy specific
+      def confidence_threshold
+        arbitration_config["confidence_threshold"]
+      end
+
+      def bid_fallback_enabled?
+        arbitration_config["bid_fallback_enabled"] != false
+      end
+
+      # Self-reflection settings
+      def self_reflection_enabled?
+        scheduling_config["self_reflection_enabled"] == true
+      end
+
+      def self_reflection_config
+        {
+          "enabled" => scheduling_config["self_reflection_enabled"],
+          "confidence_threshold" => scheduling_config["confidence_threshold"],
+          "max_retries" => scheduling_config["max_retries"],
+          "retry_delay_seconds" => scheduling_config["retry_delay_seconds"]
+        }
+      end
+
+      # Loop breaker settings
+      def loop_breaker_enabled?
+        scheduling_config["loop_breaker_enabled"] == true
+      end
+
+      def loop_breaker_config
+        {
+          "enabled" => scheduling_config["loop_breaker_enabled"],
+          "ping_pong_threshold" => scheduling_config["ping_pong_threshold"],
+          "creative_retry_threshold" => scheduling_config["creative_retry_threshold"],
+          "creative_retry_window_minutes" => scheduling_config["creative_retry_window_minutes"],
+          "task_timeout_minutes" => scheduling_config["task_timeout_minutes"],
+          "token_spike_threshold" => scheduling_config["token_spike_threshold"],
+          "token_spike_window_minutes" => scheduling_config["token_spike_window_minutes"]
+        }
+      end
+
+      # Stuck detection settings
+      def stuck_detection_enabled?
+        stuck_detection_config["enabled"] == true
+      end
+
+      def stuck_detection_config
+        @stuck_detection_config ||= resolve("stuck_detection")
+      end
+
+      # Generic resolve method for any policy type
+      def resolve(policy_type)
+        merge_policies(policy_type)
+      end
+
+      private
+
+      def merge_policies(policy_type)
+        # Start with defaults
+        config = DEFAULTS[policy_type]&.dup || {}
+
+        # Get applicable policies in priority order
+        policies = OrchestratorPolicy.for_context(@context, policy_type: policy_type)
+
+        # Merge each policy's config (later policies override earlier)
+        policies.each do |policy|
+          config = config.merge(policy.config)
+        end
+
+        config
+      end
+    end
+  end
+end

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

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module Collavre
+  module Orchestration
+    # ResourceTracker tracks per-agent resource usage for scheduling decisions.
+    #
+    # Tracks:
+    # - Active jobs count (concurrency)
+    # - Daily token usage (quota)
+    # - Request rate (rate limiting)
+    #
+    # Uses Rails.cache by default (memory-based).
+    # Can be extended to use Redis for multi-server deployments.
+    #
+    # Usage:
+    #   tracker = ResourceTracker.for(agent)
+    #   tracker.active_jobs          # => 2
+    #   tracker.can_accept_work?     # => true/false
+    #   tracker.reserve!(job_id)
+    #   tracker.release!(job_id, tokens_used: 1500)
+    #
+    class ResourceTracker
+      CACHE_EXPIRY_ACTIVE_JOBS = 1.hour
+      CACHE_EXPIRY_TOKENS = 2.days
+      CACHE_EXPIRY_RATE = 2.minutes
+
+      class << self
+        def for(agent)
+          new(agent)
+        end
+      end
+
+      def initialize(agent)
+        @agent = agent
+        @key_prefix = "orchestrator:agent:#{agent.id}"
+      end
+
+      # Current number of active jobs for this agent
+      def active_jobs
+        active_job_set.size
+      end
+
+      # Total tokens used today
+      def tokens_today
+        cache_read(tokens_today_key) || 0
+      end
+
+      # Requests in the current minute window
+      def requests_this_minute
+        cache_read(rate_limit_key) || 0
+      end
+
+      # Check if rate limited (exceeds requests per minute)
+      def rate_limited?(limit)
+        requests_this_minute >= limit
+      end
+
+      # Reserve resources for a job (call before starting work)
+      def reserve!(job_id)
+        jobs = active_job_set
+        jobs.add(job_id.to_s)
+        cache_write(active_jobs_key, jobs, expires_in: CACHE_EXPIRY_ACTIVE_JOBS)
+
+        # Increment rate counter
+        increment_rate_counter
+
+        true
+      end
+
+      # Release resources after job completion
+      def release!(job_id, tokens_used: 0)
+        # Remove from active jobs
+        jobs = active_job_set
+        jobs.delete(job_id.to_s)
+        cache_write(active_jobs_key, jobs, expires_in: CACHE_EXPIRY_ACTIVE_JOBS)
+
+        # Add to daily token usage
+        if tokens_used.positive?
+          current_tokens = tokens_today
+          cache_write(tokens_today_key, current_tokens + tokens_used, expires_in: CACHE_EXPIRY_TOKENS)
+        end
+
+        true
+      end
+
+      # Get current resource status
+      def status
+        {
+          active_jobs: active_jobs,
+          tokens_today: tokens_today,
+          requests_this_minute: requests_this_minute
+        }
+      end
+
+      # Reset all tracking (useful for testing)
+      def reset!
+        Rails.cache.delete(active_jobs_key)
+        Rails.cache.delete(tokens_today_key)
+        Rails.cache.delete(rate_limit_key)
+      end
+
+      private
+
+      def active_job_set
+        cache_read(active_jobs_key) || Set.new
+      end
+
+      def increment_rate_counter
+        current = requests_this_minute
+        cache_write(rate_limit_key, current + 1, expires_in: CACHE_EXPIRY_RATE)
+      end
+
+      def active_jobs_key
+        "#{@key_prefix}:active_jobs"
+      end
+
+      def tokens_today_key
+        "#{@key_prefix}:tokens:#{Date.current}"
+      end
+
+      def rate_limit_key
+        # Window by minute
+        "#{@key_prefix}:rate:#{Time.current.to_i / 60}"
+      end
+
+      def cache_read(key)
+        Rails.cache.read(key)
+      end
+
+      def cache_write(key, value, expires_in:)
+        Rails.cache.write(key, value, expires_in: expires_in)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+module Collavre
+  module Orchestration
+    # Scheduler decides when to execute agent jobs based on resource availability.
+    #
+    # Scheduling decisions:
+    # - :immediate - Execute now
+    # - :delayed - Execute after a delay (with :delay value)
+    # - :rejected - Do not execute (with :reason)
+    #
+    # Resource checks:
+    # - Active jobs count (concurrency limit)
+    # - Daily token usage (quota)
+    # - Rate limiting (requests per minute)
+    #
+    class Scheduler
+      # Default backoff delays
+      BACKOFF_DELAYS = {
+        immediate: 0,
+        linear: 30.seconds,
+        exponential_base: 10.seconds
+      }.freeze
+
+      def initialize(context, policy_resolver: nil)
+        @context = context
+        @policy_resolver = policy_resolver || PolicyResolver.new(context)
+      end
+
+      # Schedule agents for execution
+      # @param agents [Array<User>] Agents selected by Arbiter
+      # @return [Array<Hash>] Scheduling decisions
+      #   Each decision: { agent:, timing:, delay: (optional), reason: (optional) }
+      def schedule(agents)
+        topic_immediate_count = 0
+        agents.map do |agent|
+          decision = evaluate(agent, topic_immediate_count: topic_immediate_count)
+          topic_immediate_count += 1 if decision[:timing] == :immediate
+          decision
+        end
+      end
+
+      private
+
+      def evaluate(agent, topic_immediate_count: 0)
+        tracker = ResourceTracker.for(agent)
+        config = @policy_resolver.scheduling_config_for(agent)
+
+        # Check 0: Loop breaker
+        if @policy_resolver.loop_breaker_enabled?
+          loop_result = LoopBreaker.new(@context, policy_resolver: @policy_resolver).check
+          if loop_result.should_break?
+            return loop_broken_decision(agent, loop_result)
+          end
+        end
+
+        # Check 1: Concurrency limit
+        max_concurrent = config["max_concurrent_jobs"] || 5
+        if tracker.active_jobs >= max_concurrent
+          return delayed_decision(agent, :busy, config)
+        end
+
+        # Check 2: Daily token quota
+        daily_limit = config["daily_token_limit"]
+        if daily_limit && tracker.tokens_today >= daily_limit
+          return rejected_decision(agent, :quota_exceeded)
+        end
+
+        # Check 3: Rate limit
+        rate_limit = config["rate_limit_per_minute"]
+        if rate_limit && tracker.rate_limited?(rate_limit)
+          return delayed_decision(agent, :rate_limited, config)
+        end
+
+        # Check 4: Topic concurrency limit (applies to Main topic with nil topic_id too)
+        topic_max = @policy_resolver.topic_max_concurrent_jobs
+        if topic_max && @context.key?("topic")
+          topic_id = @context.dig("topic", "id")
+          if (Task.running_for_topic(topic_id).count + topic_immediate_count) >= topic_max
+            return deferred_decision(agent)
+          end
+        end
+
+        # All checks passed - immediate execution
+        immediate_decision(agent)
+      end
+
+      def immediate_decision(agent)
+        {
+          agent: agent,
+          timing: :immediate
+        }
+      end
+
+      def delayed_decision(agent, reason, config)
+        {
+          agent: agent,
+          timing: :delayed,
+          delay: calculate_delay(config, reason),
+          reason: reason
+        }
+      end
+
+      def deferred_decision(agent)
+        {
+          agent: agent,
+          timing: :deferred
+        }
+      end
+
+      def rejected_decision(agent, reason)
+        {
+          agent: agent,
+          timing: :rejected,
+          reason: reason
+        }
+      end
+
+      def loop_broken_decision(agent, loop_result)
+        {
+          agent: agent,
+          timing: :rejected,
+          reason: :loop_detected,
+          loop_break_reason: loop_result.reason,
+          loop_break_details: loop_result.details
+        }
+      end
+
+      def calculate_delay(config, _reason)
+        strategy = config["backoff_strategy"] || "linear"
+
+        case strategy
+        when "immediate"
+          BACKOFF_DELAYS[:immediate]
+        when "exponential"
+          # Simple exponential: base * 2^(active_jobs - max)
+          # For now, use a fixed multiplier
+          BACKOFF_DELAYS[:exponential_base] * 2
+        else # linear
+          BACKOFF_DELAYS[:linear]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,231 @@
+# frozen_string_literal: true
+
+module Collavre
+  module Orchestration
+    # SelfReflectionEvaluator evaluates an agent's response and determines
+    # whether the agent should retry, escalate, or mark the task as done.
+    #
+    # It parses confidence signals from the response and compares against
+    # policy-configured thresholds.
+    #
+    # Usage:
+    #   evaluator = SelfReflectionEvaluator.new(task)
+    #   result = evaluator.evaluate
+    #   case result.action
+    #   when :done then task.update!(status: "done")
+    #   when :retry then schedule_retry(result.delay)
+    #   when :escalate then notify_admin(result.reason)
+    #   end
+    #
+    class SelfReflectionEvaluator
+      Result = Struct.new(:action, :delay, :reason, :confidence, keyword_init: true)
+
+      # Patterns to extract confidence from agent response
+      CONFIDENCE_PATTERNS = [
+        /확신도[:\s]*(\d+)/i,
+        /confidence[:\s]*(\d+)/i,
+        /\[confidence[:\s]*(\d+)\]/i,
+        /확신[:\s]*(\d+)%?/i
+      ].freeze
+
+      # Patterns that indicate the agent is stuck or uncertain
+      UNCERTAINTY_PATTERNS = [
+        /잘\s*모르겠/,
+        /확실하지\s*않/,
+        /불확실/,
+        /도움이?\s*필요/,
+        /막혔/,
+        /I('m| am)\s*(not sure|uncertain|stuck)/i,
+        /need(s)?\s*help/i,
+        /cannot\s*(proceed|continue)/i
+      ].freeze
+
+      def initialize(task, response_content: nil, policy_resolver: nil)
+        @task = task
+        @response_content = response_content || ""
+        @policy_resolver = policy_resolver ||
+          PolicyResolver.new(task.trigger_event_payload || {})
+      end
+
+      # Evaluate the task's response and return a Result
+      # @return [Result] with :action (:done, :retry, :escalate), :delay, :reason, :confidence
+      def evaluate
+        return Result.new(action: :done, reason: "self_reflection_disabled") unless enabled?
+
+        confidence = parse_confidence
+        uncertainty_detected = detect_uncertainty
+
+        if confidence.nil? && !uncertainty_detected
+          # No confidence signal and no uncertainty - assume done
+          Result.new(action: :done, confidence: nil, reason: "no_signal")
+        elsif confidence && confidence >= threshold
+          # Confidence meets threshold - done
+          Result.new(action: :done, confidence: confidence, reason: "threshold_met")
+        elsif @task.retry_count >= max_retries
+          # Max retries exceeded - escalate
+          Result.new(
+            action: :escalate,
+            confidence: confidence,
+            reason: "max_retries_exceeded"
+          )
+        else
+          # Below threshold or uncertainty detected - retry
+          Result.new(
+            action: :retry,
+            delay: retry_delay,
+            confidence: confidence,
+            reason: uncertainty_detected ? "uncertainty_detected" : "below_threshold"
+          )
+        end
+      end
+
+      # Schedule a retry by creating a system message and re-triggering
+      # @param result [Result] pre-computed result from evaluate
+      def schedule_retry!(result)
+        return result unless result.action == :retry
+
+        # Increment retry count
+        @task.increment!(:retry_count)
+
+        # Create self-reflection prompt as a new comment
+        create_reflection_prompt
+
+        # Schedule the retry job
+        if result.delay.positive?
+          AiAgentJob.set(wait: result.delay.seconds).perform_later(@task)
+        else
+          AiAgentJob.perform_later(@task)
+        end
+
+        result
+      end
+
+      # Escalate to admin users
+      # @param result [Result] pre-computed result from evaluate
+      def escalate!(result)
+        return result unless result.action == :escalate
+
+        @task.update!(status: "escalated")
+        create_escalation_notice
+        notify_admins
+
+        result
+      end
+
+      private
+
+      def config
+        @config ||= @policy_resolver.self_reflection_config
+      end
+
+      def enabled?
+        config["enabled"] == true
+      end
+
+      def threshold
+        config["confidence_threshold"] || 70
+      end
+
+      def max_retries
+        config["max_retries"] || 3
+      end
+
+      def retry_delay
+        config["retry_delay_seconds"] || 5
+      end
+
+      def response_content
+        @response_content
+      end
+
+      def parse_confidence
+        CONFIDENCE_PATTERNS.each do |pattern|
+          match = response_content.match(pattern)
+          return match[1].to_i if match
+        end
+        nil
+      end
+
+      def detect_uncertainty
+        UNCERTAINTY_PATTERNS.any? { |pattern| response_content.match?(pattern) }
+      end
+
+      def create_reflection_prompt
+        creative_id = @task.trigger_event_payload&.dig("creative", "id")
+        return unless creative_id && @task.topic_id
+
+        creative = Creative.find_by(id: creative_id)
+        return unless creative
+
+        # Create a system message prompting self-reflection
+        creative.comments.create!(
+          content: reflection_prompt_content,
+          user: system_user,
+          topic_id: @task.topic_id,
+          private: false
+        )
+      end
+
+      def reflection_prompt_content
+        <<~PROMPT.strip
+          [시스템] 확신도가 낮습니다 (#{@task.retry_count + 1}/#{max_retries} 재시도).
+
+          다시 검토해주세요:
+          - 다른 접근법이 있나요?
+          - 부족한 정보가 있다면 @멘션으로 다른 Agent에게 요청하세요.
+          - 그래도 해결이 어려우면 상위로 에스컬레이션하세요.
+
+          응답 시 확신도를 명시해주세요: [confidence: 0-100]
+        PROMPT
+      end
+
+      def create_escalation_notice
+        creative_id = @task.trigger_event_payload&.dig("creative", "id")
+        return unless creative_id && @task.topic_id
+
+        creative = Creative.find_by(id: creative_id)
+        return unless creative
+
+        creative.comments.create!(
+          content: escalation_notice_content,
+          user: system_user,
+          topic_id: @task.topic_id,
+          private: false
+        )
+      end
+
+      def escalation_notice_content
+        <<~NOTICE.strip
+          [시스템] ⚠️ 에스컬레이션 발생
+
+          Agent: #{@task.agent&.name}
+          작업: #{@task.name}
+          재시도 횟수: #{@task.retry_count}회
+
+          최대 재시도 횟수를 초과하여 관리자에게 에스컬레이션되었습니다.
+          admin 권한을 가진 사용자의 검토가 필요합니다.
+        NOTICE
+      end
+
+      def notify_admins
+        # Find admin users for this creative and notify them
+        creative_id = @task.trigger_event_payload&.dig("creative", "id")
+        return unless creative_id
+
+        creative = Creative.find_by(id: creative_id)
+        return unless creative
+
+        # This could trigger notifications via various channels
+        # For now, the escalation notice in the topic serves as notification
+        Rails.logger.info(
+          "[SelfReflection] Task #{@task.id} escalated for creative #{creative_id}"
+        )
+      end
+
+      def system_user
+        @system_user ||= User.find_by(email: "system@collavre.local") ||
+          @task.agent # Fallback to agent if no system user
+      end
+    end
+  end
+end