Module: Legion::Extensions::Llm::Taxonomies

Defined in:
lib/legion/extensions/llm/taxonomies.rb

Overview

Frozen vocabularies shared across routing, inventory, and provider contracts: legacy tier/type/circuit enums plus the SSOT v3 operation, evidence, availability, outcome, and rejection enums.

Constant Summary collapse

TIERS = 
%i[direct local fleet cloud frontier].freeze
TYPES = 
%i[inference embedding image audio].freeze
OPERATION_TO_LANE_TYPE =

The current authoritative operation → Inventory lane-type mapping (the 4th field of the 5-tuple lane id). NON-LEGACY home: the deletion-scheduled LegacyCoordinatorAdapter consumes lane_type_for below until deletion; it must not retain a second mapping. moderate/count_tokens are non-generative inference operations — no moderation/count type exists in TYPES, so they map to :inference.

{
  chat: :inference,
  stream_chat: :inference,
  embed: :embedding,
  image: :image,
  transcribe: :audio,
  translate: :audio,
  speak: :audio,
  moderate: :inference,
  count_tokens: :inference
}.freeze
CIRCUIT_STATES = 
%i[closed half_open open].freeze
HEALTH_KEYS = 
%i[circuit_state denied available adjustment].freeze
OPERATIONS =

--- SSOT v3 runtime-contract enums (phase-1-lex-llm-additive.md section 6) ---

%i[
  chat stream_chat embed image transcribe translate speak moderate count_tokens
].freeze
CAPABILITY_EVIDENCE_STATES = 
%i[supported unsupported unknown].freeze
OPERATION_EVIDENCE_STATES = 
%i[supported unsupported unknown].freeze
VALUE_EVIDENCE_STATES = 
%i[known unknown].freeze
AVAILABILITY_STATES = 
%i[initializing available unavailable].freeze
AVAILABILITY_SOURCES = 
%i[startup_readiness readiness dispatch].freeze
PROBE_OUTCOMES = 
%i[success failure].freeze
PUBLICATION_STATES = 
%i[initializing complete].freeze
CALLABLE_STATES = 
%i[active retiring disposed].freeze
MUTATION_REASONS = 
%i[
  claimed activated snapshot_replaced readiness_observed instance_unavailable
  instance_recovered initial_readiness_failed removed stale_publisher stale_probe
  already_removed
].freeze
PROVIDER_OUTCOMES = 
%i[
  success instance_unavailable overloaded model_not_ready rate_limited
  authentication authorization billing policy invalid_request model_missing
  context_rejected safety_refusal malformed_output tool_failure timeout
  connection_failure provider_error cancelled client_disconnect
].freeze
REJECTION_KINDS = 
%i[
  invalid_routing_context invalid_request policy_denied failed_dependency
  too_early service_unavailable context_rejected attempts_exhausted stale_selection
].freeze
EXCLUSION_TARGET_KINDS = 
%i[
  attempt_target lane offering instance provider model quota_domain
].freeze
EXCLUSION_LIFETIMES = 
%i[request attempt_group].freeze
BODY_MODEL_HINT_DISPOSITIONS = 
%i[
  absent auto superseded_by_explicit_model ignored_disabled
  ignored_not_whitelisted ignored_blacklisted honored
].freeze
EVIDENCE_SOURCES = 
%i[
  provider_implementation model_metadata provider_catalog probe provider_envelope
  model_override instance_override provider_override default_false absent guessed
  failed_probe inconclusive_probe
].freeze
UNKNOWN_ONLY_EVIDENCE_SOURCES = 
%i[
  model_override instance_override provider_override default_false absent guessed
  failed_probe inconclusive_probe
].freeze
OPERATION_ALIASES =

Only these aliases are accepted, and only when allow_aliases: true.

{
  stream: :stream_chat,
  embedding: :embed,
  moderation: :moderate,
  audio_translation: :translate,
  speech: :speak
}.freeze

Class Method Summary collapse

Class Method Details

.lane_type_for(operation:) ⇒ Object 



101
102
103
104
 
# File 'lib/legion/extensions/llm/taxonomies.rb', line 101

def lane_type_for(operation:)
  canonical = normalize_operation(value: operation, allow_aliases: false)
  OPERATION_TO_LANE_TYPE.fetch(canonical)
end

.normalize_operation(value:, allow_aliases: false) ⇒ Object

Normalize an operation to one of OPERATIONS. Ingress and protocol-v2 compatibility adapters pass allow_aliases: true; registry records and exact-execution envelopes pass false. Unknown, empty, or invalid UTF-8 input always raises Inventory::Errors::ValidationError.

Raises:



110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
 
# File 'lib/legion/extensions/llm/taxonomies.rb', line 110

def normalize_operation(value:, allow_aliases: false)
  raise Inventory::Errors::ValidationError, 'operation must be a String or Symbol' unless value.is_a?(::String) || value.is_a?(::Symbol)

  string = value.to_s
  raise Inventory::Errors::ValidationError, 'operation is not valid UTF-8' unless [::Encoding::UTF_8, ::Encoding::US_ASCII].include?(string.encoding) && string.valid_encoding?

  trimmed = string.strip
  raise Inventory::Errors::ValidationError, 'operation must not be empty' if trimmed.empty?

  candidate = trimmed.to_sym
  return candidate if OPERATIONS.include?(candidate)
  return OPERATION_ALIASES[candidate] if allow_aliases && OPERATION_ALIASES.key?(candidate)

  raise Inventory::Errors::ValidationError, "operation is not a canonical operation (#{candidate})"
end