agent-harness 0.2.1

data/lib/agent_harness/orchestration/conductor.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+module AgentHarness
+  module Orchestration
+    # Main orchestration entry point
+    #
+    # Provides a simple interface for sending messages while managing
+    # provider selection, fallback, retries, and error handling internally.
+    #
+    # @example Basic usage
+    #   conductor = AgentHarness::Orchestration::Conductor.new
+    #   response = conductor.send_message("Hello, world!")
+    #
+    # @example With explicit provider
+    #   response = conductor.send_message("Hello", provider: :gemini)
+    class Conductor
+      attr_reader :provider_manager, :metrics
+
+      # Create a new conductor
+      #
+      # @param config [Configuration, nil] configuration object
+      def initialize(config: nil)
+        @config = config || AgentHarness.configuration
+        @provider_manager = ProviderManager.new(@config)
+        @metrics = Metrics.new
+      end
+
+      # Send a message with full orchestration
+      #
+      # Handles provider selection, fallback, retries, circuit breakers,
+      # and error handling transparently.
+      #
+      # @param prompt [String] the prompt to send
+      # @param provider [Symbol, nil] preferred provider
+      # @param model [String, nil] model to use
+      # @param options [Hash] additional options
+      # @return [Response] the response
+      # @raise [NoProvidersAvailableError] if all providers fail
+      def send_message(prompt, provider: nil, model: nil, **options)
+        provider_name = provider || @config.default_provider
+
+        with_orchestration(provider_name, model, options) do |selected_provider|
+          selected_provider.send_message(prompt: prompt, model: model, **options)
+        end
+      end
+
+      # Execute with explicit provider (bypass orchestration)
+      #
+      # @param prompt [String] the prompt to send
+      # @param provider [Symbol] the provider to use
+      # @param options [Hash] additional options
+      # @return [Response] the response
+      def execute_direct(prompt, provider:, **options)
+        provider_instance = @provider_manager.get_provider(provider)
+        provider_instance.send_message(prompt: prompt, **options)
+      end
+
+      # Get current orchestration status
+      #
+      # @return [Hash] status information
+      def status
+        {
+          current_provider: @provider_manager.current_provider,
+          available_providers: @provider_manager.available_providers,
+          health: @provider_manager.health_status,
+          metrics: @metrics.summary
+        }
+      end
+
+      # Reset all orchestration state
+      #
+      # @return [void]
+      def reset!
+        @provider_manager.reset!
+        @metrics.reset!
+      end
+
+      private
+
+      def with_orchestration(provider_name, model, options)
+        retries = 0
+        retry_config = @config.orchestration_config.retry_config
+        max_retries = retry_config.max_attempts
+        attempted_providers = []
+
+        begin
+          # Select provider (may return different provider based on health)
+          provider = @provider_manager.select_provider(provider_name)
+          provider_name = provider.class.provider_name
+          attempted_providers << provider_name
+
+          # Record attempt
+          @metrics.record_attempt(provider_name)
+
+          start_time = Time.now
+          response = yield(provider)
+          duration = Time.now - start_time
+
+          # Record success
+          @metrics.record_success(provider_name, duration)
+          @provider_manager.record_success(provider_name)
+
+          response
+        rescue RateLimitError => e
+          @provider_manager.mark_rate_limited(provider_name, reset_at: e.reset_time)
+          handle_provider_failure(e, provider_name, :switch)
+          retry if should_retry?(retries += 1, max_retries)
+          raise
+        rescue CircuitOpenError => e
+          handle_provider_failure(e, provider_name, :switch)
+          retry if should_retry?(retries += 1, max_retries)
+          raise
+        rescue TimeoutError, ProviderError => e
+          @provider_manager.record_failure(provider_name)
+          handle_provider_failure(e, provider_name, :retry)
+          retry if should_retry?(retries += 1, max_retries)
+          raise
+        rescue NoProvidersAvailableError
+          # Re-raise as-is, don't wrap
+          raise
+        rescue => e
+          @metrics.record_failure(provider_name, e)
+          @provider_manager.record_failure(provider_name)
+
+          # Try switching for unknown errors
+          handle_provider_failure(e, provider_name, :switch)
+          retry if should_retry?(retries += 1, max_retries)
+          raise ProviderError.new(e.message, original_error: e)
+        end
+      end
+
+      def should_retry?(current_retries, max_retries)
+        return false unless @config.orchestration_config.retry_config.enabled
+        current_retries < max_retries
+      end
+
+      def handle_provider_failure(error, provider_name, strategy)
+        @metrics.record_failure(provider_name, error)
+
+        case strategy
+        when :switch
+          if @config.orchestration_config.auto_switch_on_error
+            new_provider = begin
+              @provider_manager.switch_provider(
+                reason: error.class.name,
+                context: {error: error.message}
+              )
+            rescue NoProvidersAvailableError
+              nil
+            end
+
+            if new_provider
+              @metrics.record_switch(provider_name, new_provider.class.provider_name, error.class.name)
+            end
+          end
+        when :retry
+          delay = calculate_retry_delay
+          sleep(delay) if delay > 0
+        end
+      end
+
+      def calculate_retry_delay
+        retry_config = @config.orchestration_config.retry_config
+        return 0 unless retry_config.enabled
+
+        base = retry_config.base_delay
+        max = retry_config.max_delay
+
+        # Add jitter if configured
+        if retry_config.jitter
+          jitter = rand * base * 0.5
+          base += jitter
+        end
+
+        [base, max].min
+      end
+    end
+  end
+end

data/lib/agent_harness/orchestration/health_monitor.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+module AgentHarness
+  module Orchestration
+    # Monitors provider health based on success/failure metrics
+    #
+    # Tracks success and failure rates to determine provider health status.
+    # Uses a sliding window approach to focus on recent performance.
+    #
+    # @example
+    #   monitor = HealthMonitor.new
+    #   monitor.record_success(:claude)
+    #   monitor.healthy?(:claude) # => true
+    class HealthMonitor
+      DEFAULT_WINDOW_SIZE = 100
+      DEFAULT_HEALTH_THRESHOLD = 0.5
+
+      # Create a new health monitor
+      #
+      # @param config [HealthCheckConfig, nil] configuration object
+      # @param window_size [Integer] number of events to track
+      # @param health_threshold [Float] minimum success rate for healthy
+      def initialize(config = nil, window_size: nil, health_threshold: nil)
+        if config
+          @enabled = config.enabled
+          @failure_threshold = config.failure_threshold
+        else
+          @enabled = true
+          @failure_threshold = 3
+        end
+
+        @window_size = window_size || DEFAULT_WINDOW_SIZE
+        @health_threshold = health_threshold || DEFAULT_HEALTH_THRESHOLD
+        @provider_metrics = Hash.new { |h, k| h[k] = ProviderHealthMetrics.new(@window_size) }
+        @mutex = Mutex.new
+      end
+
+      # Record a successful call for a provider
+      #
+      # @param provider_name [Symbol, String] the provider name
+      # @return [void]
+      def record_success(provider_name)
+        @mutex.synchronize do
+          @provider_metrics[provider_name.to_sym].record_success
+        end
+      end
+
+      # Record a failed call for a provider
+      #
+      # @param provider_name [Symbol, String] the provider name
+      # @return [void]
+      def record_failure(provider_name)
+        @mutex.synchronize do
+          @provider_metrics[provider_name.to_sym].record_failure
+        end
+      end
+
+      # Check if a provider is healthy
+      #
+      # @param provider_name [Symbol, String] the provider name
+      # @return [Boolean] true if healthy
+      def healthy?(provider_name)
+        return true unless @enabled
+
+        metrics = @provider_metrics[provider_name.to_sym]
+        return true if metrics.total_calls == 0
+
+        metrics.success_rate >= @health_threshold
+      end
+
+      # Get health metrics for a provider
+      #
+      # @param provider_name [Symbol, String] the provider name
+      # @return [Hash] health metrics
+      def metrics_for(provider_name)
+        metrics = @provider_metrics[provider_name.to_sym]
+        {
+          success_rate: metrics.success_rate,
+          total_calls: metrics.total_calls,
+          recent_successes: metrics.recent_successes,
+          recent_failures: metrics.recent_failures,
+          healthy: healthy?(provider_name)
+        }
+      end
+
+      # Get health status for all tracked providers
+      #
+      # @return [Hash<Symbol, Hash>] health status by provider
+      def all_metrics
+        @provider_metrics.transform_values do |metrics|
+          {
+            success_rate: metrics.success_rate,
+            total_calls: metrics.total_calls,
+            recent_successes: metrics.recent_successes,
+            recent_failures: metrics.recent_failures
+          }
+        end
+      end
+
+      # Reset all health metrics
+      #
+      # @return [void]
+      def reset!
+        @mutex.synchronize do
+          @provider_metrics.clear
+        end
+      end
+
+      # Reset metrics for a specific provider
+      #
+      # @param provider_name [Symbol, String] the provider name
+      # @return [void]
+      def reset_provider!(provider_name)
+        @mutex.synchronize do
+          @provider_metrics.delete(provider_name.to_sym)
+        end
+      end
+    end
+
+    # Internal class for tracking per-provider metrics
+    class ProviderHealthMetrics
+      attr_reader :total_calls, :recent_successes, :recent_failures
+
+      def initialize(window_size)
+        @window_size = window_size
+        @events = []
+        @total_calls = 0
+        @recent_successes = 0
+        @recent_failures = 0
+      end
+
+      def record_success
+        add_event(:success)
+      end
+
+      def record_failure
+        add_event(:failure)
+      end
+
+      def success_rate
+        return 1.0 if @events.empty?
+        @recent_successes.to_f / @events.size
+      end
+
+      private
+
+      def add_event(type)
+        @total_calls += 1
+
+        # Remove oldest event if at capacity
+        if @events.size >= @window_size
+          old_event = @events.shift
+          if old_event == :success
+            @recent_successes -= 1
+          else
+            @recent_failures -= 1
+          end
+        end
+
+        # Add new event
+        @events << type
+        if type == :success
+          @recent_successes += 1
+        else
+          @recent_failures += 1
+        end
+      end
+    end
+  end
+end

data/lib/agent_harness/orchestration/metrics.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+module AgentHarness
+  module Orchestration
+    # Collects and aggregates orchestration metrics
+    #
+    # Tracks attempts, successes, failures, and timing information
+    # for provider orchestration.
+    class Metrics
+      def initialize
+        @mutex = Mutex.new
+        reset!
+      end
+
+      # Record an attempt for a provider
+      #
+      # @param provider_name [Symbol, String] the provider name
+      # @return [void]
+      def record_attempt(provider_name)
+        @mutex.synchronize do
+          provider = provider_name.to_sym
+          @attempts[provider] += 1
+          @total_attempts += 1
+        end
+      end
+
+      # Record a success for a provider
+      #
+      # @param provider_name [Symbol, String] the provider name
+      # @param duration [Float] request duration in seconds
+      # @return [void]
+      def record_success(provider_name, duration)
+        @mutex.synchronize do
+          provider = provider_name.to_sym
+          @successes[provider] += 1
+          @total_successes += 1
+          @durations[provider] << duration
+          @last_success_time = Time.now
+        end
+      end
+
+      # Record a failure for a provider
+      #
+      # @param provider_name [Symbol, String] the provider name
+      # @param error [Exception] the error that occurred
+      # @return [void]
+      def record_failure(provider_name, error)
+        @mutex.synchronize do
+          provider = provider_name.to_sym
+          @failures[provider] += 1
+          @total_failures += 1
+          @error_counts[error.class.name] += 1
+          @last_failure_time = Time.now
+        end
+      end
+
+      # Record a provider switch
+      #
+      # @param from_provider [Symbol, String] the original provider
+      # @param to_provider [Symbol, String] the new provider
+      # @param reason [String] reason for switch
+      # @return [void]
+      def record_switch(from_provider, to_provider, reason)
+        @mutex.synchronize do
+          @switches << {
+            from: from_provider.to_sym,
+            to: to_provider.to_sym,
+            reason: reason,
+            timestamp: Time.now
+          }
+          @total_switches += 1
+        end
+      end
+
+      # Get metrics summary
+      #
+      # @return [Hash] metrics summary
+      def summary
+        @mutex.synchronize do
+          {
+            total_attempts: @total_attempts,
+            total_successes: @total_successes,
+            total_failures: @total_failures,
+            total_switches: @total_switches,
+            success_rate: success_rate,
+            by_provider: provider_summary,
+            error_counts: @error_counts.dup,
+            last_success_time: @last_success_time,
+            last_failure_time: @last_failure_time,
+            recent_switches: @switches.last(10)
+          }
+        end
+      end
+
+      # Get metrics for a specific provider
+      #
+      # @param provider_name [Symbol, String] the provider name
+      # @return [Hash] provider metrics
+      def provider_metrics(provider_name)
+        provider = provider_name.to_sym
+        @mutex.synchronize do
+          {
+            attempts: @attempts[provider],
+            successes: @successes[provider],
+            failures: @failures[provider],
+            success_rate: provider_success_rate(provider),
+            average_duration: average_duration(provider)
+          }
+        end
+      end
+
+      # Reset all metrics
+      #
+      # @return [void]
+      def reset!
+        @mutex.synchronize do
+          @attempts = Hash.new(0)
+          @successes = Hash.new(0)
+          @failures = Hash.new(0)
+          @durations = Hash.new { |h, k| h[k] = [] }
+          @error_counts = Hash.new(0)
+          @switches = []
+
+          @total_attempts = 0
+          @total_successes = 0
+          @total_failures = 0
+          @total_switches = 0
+
+          @last_success_time = nil
+          @last_failure_time = nil
+        end
+      end
+
+      private
+
+      def success_rate
+        return 1.0 if @total_attempts == 0
+        @total_successes.to_f / @total_attempts
+      end
+
+      def provider_success_rate(provider)
+        attempts = @attempts[provider]
+        return 1.0 if attempts == 0
+        @successes[provider].to_f / attempts
+      end
+
+      def average_duration(provider)
+        durations = @durations[provider]
+        return 0.0 if durations.empty?
+        durations.sum / durations.size
+      end
+
+      def provider_summary
+        providers = (@attempts.keys + @successes.keys + @failures.keys).uniq
+        providers.to_h do |provider|
+          [provider, {
+            attempts: @attempts[provider],
+            successes: @successes[provider],
+            failures: @failures[provider],
+            success_rate: provider_success_rate(provider),
+            average_duration: average_duration(provider)
+          }]
+        end
+      end
+    end
+  end
+end