Class: Legion::Extensions::Llm::Routing::ProviderOutcome

Inherits:
Data
  • Object
show all
Defined in:
lib/legion/extensions/llm/routing/provider_outcome.rb

Overview

A provider-neutral normalized outcome. Adapters translate wire errors into one of these kinds; the common classifier branches only on kind, never on provider identity. The value contains no provider object, callable, response body, routing weight, or health-mutation instruction. HTTP 503/529 alone is not an input and cannot manufacture instance_unavailable. See phase-1-lex-llm-additive.md section 14.2.

Constant Summary collapse

RETRYABLE_KINDS =

06 F6: the transient kinds that may be retried at the fleet edge. Classification/contract/auth/policy kinds never retry.

%i[overloaded rate_limited timeout connection_failure provider_error].freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(kind:, reason:, quota_domain: nil, retry_after: nil, metadata: {}) ⇒ ProviderOutcome

Returns a new instance of ProviderOutcome.

Raises:

  • (errors::ValidationError) 


20
21
22
23
24
25
26
27
28
29
30
31
32
 
# File 'lib/legion/extensions/llm/routing/provider_outcome.rb', line 20

def initialize(kind:, reason:, quota_domain: nil, retry_after: nil, metadata: {})
  support = Legion::Extensions::Llm::Inventory::RecordSupport
  errors = Legion::Extensions::Llm::Inventory::Errors
  raise errors::ValidationError, 'kind must be a Taxonomies::PROVIDER_OUTCOMES value' unless Legion::Extensions::Llm::Taxonomies::PROVIDER_OUTCOMES.include?(kind)

  super(
    kind: kind,
    reason: support.sanitized_reason(value: reason, field: :reason),
    quota_domain: validate_quota_domain!(kind, quota_domain),
    retry_after: validate_retry_after!(retry_after),
    metadata: support.frozen_metadata(value: metadata)
  )
end

Instance Attribute Details

#kind ⇒ Object (readonly)

Returns the value of attribute kind

Returns:

  • (Object) —

    the current value of kind



19
20
21
 
# File 'lib/legion/extensions/llm/routing/provider_outcome.rb', line 19

def kind
  @kind
end

#metadata ⇒ Object (readonly)

Returns the value of attribute metadata

Returns:

  • (Object) —

    the current value of metadata



19
20
21
 
# File 'lib/legion/extensions/llm/routing/provider_outcome.rb', line 19

def metadata
  @metadata
end

#quota_domain ⇒ Object (readonly)

Returns the value of attribute quota_domain

Returns:

  • (Object) —

    the current value of quota_domain



19
20
21
 
# File 'lib/legion/extensions/llm/routing/provider_outcome.rb', line 19

def quota_domain
  @quota_domain
end

#reason ⇒ Object (readonly)

Returns the value of attribute reason

Returns:

  • (Object) —

    the current value of reason



19
20
21
 
# File 'lib/legion/extensions/llm/routing/provider_outcome.rb', line 19

def reason
  @reason
end

#retry_after ⇒ Object (readonly)

Returns the value of attribute retry_after

Returns:

  • (Object) —

    the current value of retry_after



19
20
21
 
# File 'lib/legion/extensions/llm/routing/provider_outcome.rb', line 19

def retry_after
  @retry_after
end

Class Method Details

.kind_for(error) ⇒ Object

The ONE error→kind base table (05 O6 / 08 E1). Providers override #normalize_dispatch_error only when their wire semantics supply stronger evidence; the table itself is frozen here and is also the source of fleet retryability (06 F6).



55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
 
# File 'lib/legion/extensions/llm/routing/provider_outcome.rb', line 55

def self.kind_for(error)
  case error
  when OverloadedError then :overloaded
  when RateLimitError then :rate_limited
  when UnauthorizedError then :authentication
  when PaymentRequiredError then :billing
  when ForbiddenError then :authorization
  when ContextLengthExceededError then :context_rejected
  when BadRequestError then :invalid_request
  when ModelNotFoundError then :model_missing
  when ModelNotAllowedError then :policy
  when Faraday::TimeoutError, Timeout::Error then :timeout
  when Faraday::ConnectionFailed, Errno::ECONNREFUSED, Errno::ECONNRESET, SocketError then :connection_failure
  else :provider_error
  end
end

Instance Method Details

#validate_quota_domain!(kind, quota_domain) ⇒ Object

Raises:

  • (errors::ValidationError) 


34
35
36
37
38
39
40
41
 
# File 'lib/legion/extensions/llm/routing/provider_outcome.rb', line 34

def validate_quota_domain!(kind, quota_domain)
  errors = Legion::Extensions::Llm::Inventory::Errors
  return nil if quota_domain.nil?
  raise errors::ValidationError, 'quota_domain must be a Routing::QuotaDomainKey' unless quota_domain.is_a?(QuotaDomainKey)
  raise errors::ValidationError, 'quota_domain is allowed only for rate_limited' unless kind == :rate_limited

  quota_domain
end

#validate_retry_after!(retry_after) ⇒ Object

Raises:



43
44
45
46
47
48
49
 
# File 'lib/legion/extensions/llm/routing/provider_outcome.rb', line 43

def validate_retry_after!(retry_after)
  return nil if retry_after.nil?
  return retry_after if retry_after.is_a?(::Numeric) && retry_after.finite? && !retry_after.negative?

  raise Legion::Extensions::Llm::Inventory::Errors::ValidationError,
        'retry_after must be nil or a finite nonnegative Numeric'
end