Class: Ace::LLM::Molecules::FallbackOrchestrator

Inherits:
Object
  • Object
show all
Defined in:
lib/ace/llm/molecules/fallback_orchestrator.rb

Overview

FallbackOrchestrator manages provider fallback chain execution This is a molecule - it coordinates between atoms and handles complex logic

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(config:, status_callback: nil, timeout: nil) ⇒ FallbackOrchestrator

Returns a new instance of FallbackOrchestrator.

Parameters:

  • config (Models::FallbackConfig) —

    Fallback configuration

  • status_callback (Proc, nil) (defaults to: nil) —

    Optional callback for status messages

  • timeout (Integer, nil) (defaults to: nil) —

    Request timeout in seconds to forward to each client



18
19
20
21
22
23
24
25
 
# File 'lib/ace/llm/molecules/fallback_orchestrator.rb', line 18

def initialize(config:, status_callback: nil, timeout: nil)
  @config = config
  @status_callback = status_callback
  @timeout = timeout
  @visited_providers = Set.new
  @start_time = nil
  @last_failure_terminal = false
end

Instance Attribute Details

#config ⇒ Object (readonly)

Returns the value of attribute config.



13
14
15
 
# File 'lib/ace/llm/molecules/fallback_orchestrator.rb', line 13

def config
  @config
end

#status_callback ⇒ Object (readonly)

Returns the value of attribute status_callback.



13
14
15
 
# File 'lib/ace/llm/molecules/fallback_orchestrator.rb', line 13

def status_callback
  @status_callback
end

Instance Method Details

#execute(primary_provider:, registry:) {|client| ... } ⇒ Object

Execute a block with fallback support

Parameters:

  • primary_provider (String) —

    Primary provider name

  • registry (Molecules::ClientRegistry) —

    Client registry for getting fallback providers

Yields:

  • Block to execute with current provider

Yield Parameters:

  • client (Object) —

    Provider client

Returns:

  • (Object) —

    Result from successful execution

Raises:

  • (Error) —

    If all providers and retries exhausted



34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
 
# File 'lib/ace/llm/molecules/fallback_orchestrator.rb', line 34

def execute(primary_provider:, registry:)
  @start_time = Time.now
  @visited_providers.clear

  # If fallback disabled, just execute with primary
  return yield(get_client(primary_provider, registry), primary_provider) if @config.disabled?

  # Try primary provider with retries
  result = try_provider_with_retry(primary_provider, registry) do |client, provider_name|
    yield client, provider_name
  end
  return result if result

  # Try fallback providers in order (per-provider chain or default)
  @config.providers_for(primary_provider).each do |fallback_provider|
    # Skip if we've already tried this provider
    next if @visited_providers.include?(fallback_provider)

    # Check total timeout
    if timeout_exceeded?
      report_status("⚠ Total timeout exceeded (#{@config.max_total_timeout}s)") unless @last_failure_terminal
      break
    end

    report_status("ℹ Trying fallback provider #{fallback_provider}...")

    result = try_provider_with_retry(fallback_provider, registry) do |client, provider_name|
      yield client, provider_name
    end
    return result if result
  end

  # All providers exhausted
  raise Ace::LLM::ProviderError, build_exhaustion_error_message
end