Class: Legion::Extensions::Llm::Provider

Inherits:
Object
  • Object
show all
Includes:
Cache::Helper, StopReasonMapping, Streaming, Logging::Helper
Defined in:
lib/legion/extensions/llm/provider.rb,
lib/legion/extensions/llm/provider/open_ai_compatible.rb

Overview

Base class for LLM providers.

Defined Under Namespace

Modules: OpenAICompatible

Constant Summary collapse

MODEL_DETAIL_CACHE_SCHEMA_VERSION = 
2
CAPABILITY_CONFIG_KEYS = 
%i[
  capabilities
  enable_completion
  enable_embedding
  enable_embeddings
  enable_streaming
  enable_tools
  enable_functions
  enable_function_calling
  enable_thinking
  enable_reasoning
  enable_vision
  enable_structured_output
  enable_moderation
  enable_image
  enable_images
  enable_image_generation
  enable_audio_transcription
  enable_audio_speech
  enable_audio_generation
  completion_flag
  embedding_flag
  embeddings_flag
  streaming_flag
  tool_flag
  tools_flag
  functions_flag
  function_calling_flag
  thinking_flag
  reasoning_flag
  vision_flag
  structured_output_flag
  moderation_flag
  image_flag
  images_flag
  image_generation_flag
  audio_transcription_flag
  audio_speech_flag
  audio_generation_flag
].freeze
HEALTHY_STATES = 
%w[ok ready healthy running].freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from StopReasonMapping

#stop_reason_lookup, #stop_reason_map, #stop_reason_map_additions

Methods included from Streaming

build_on_data_handler, build_stream_callback, build_stream_error_response, error_chunk?, faraday_1?, handle_data, handle_error_chunk, handle_error_event, handle_failed_response, handle_json_error_chunk, handle_parsed_error, handle_sse, handle_stream, json_error_payload?, parse_error_from_json, parse_streaming_error, persist_failed_response_body, persist_failed_response_custom_body?, persist_failed_response_env_body?, process_stream_chunk, raise_partial_streaming_error, raise_streaming_status_error, raise_unparseable_streaming_error, stream_response

Constructor Details

#initialize(config) ⇒ Provider

Returns a new instance of Provider.



83
84
85
86
87
 
# File 'lib/legion/extensions/llm/provider.rb', line 83

def initialize(config)
  @config = config.is_a?(Hash) ? HashConfig.new(config) : config
  ensure_configured!
  @connection = Connection.new(self, @config)
end

Instance Attribute Details

#config ⇒ Object (readonly)

Returns the value of attribute config.



81
82
83
 
# File 'lib/legion/extensions/llm/provider.rb', line 81

def config
  @config
end

#connection ⇒ Object (readonly)

Returns the value of attribute connection.



81
82
83
 
# File 'lib/legion/extensions/llm/provider.rb', line 81

def connection
  @connection
end

Class Method Details

.capabilities ⇒ Object 



742
743
744
 
# File 'lib/legion/extensions/llm/provider.rb', line 742

def capabilities
  nil
end

.configuration_options ⇒ Object 



750
751
752
 
# File 'lib/legion/extensions/llm/provider.rb', line 750

def configuration_options
  []
end

.configuration_requirements ⇒ Object 



746
747
748
 
# File 'lib/legion/extensions/llm/provider.rb', line 746

def configuration_requirements
  []
end

.configured?(config) ⇒ Boolean

Returns:

  • (Boolean) 


774
775
776
 
# File 'lib/legion/extensions/llm/provider.rb', line 774

def configured?(config)
  configuration_requirements.all? { |req| config.send(req) }
end

.default_tier ⇒ Object 



758
759
760
 
# File 'lib/legion/extensions/llm/provider.rb', line 758

def default_tier
  :frontier
end

.default_transport ⇒ Object 



754
755
756
 
# File 'lib/legion/extensions/llm/provider.rb', line 754

def default_transport
  :http
end

.local? ⇒ Boolean

Returns:

  • (Boolean) 


762
763
764
 
# File 'lib/legion/extensions/llm/provider.rb', line 762

def local?
  false
end

.model_identity(model) ⇒ Object

Single source of truth for model-policy matching, usable at runtime (instance #model_allowed?). Substring, case-insensitive: a whitelist permits models containing any pattern; a blacklist denies models containing any pattern; whitelist is applied before blacklist. Empty list = no restriction from that side. Model identity for policy matching: the canonical id string. An object that responds to #id matches by its #id — never by its inspect string; bare strings pass through unchanged.



595
596
597
598
599
600
 
# File 'lib/legion/extensions/llm/provider.rb', line 595

def self.model_identity(model)
  candidate = model.respond_to?(:id) ? model.id : model
  candidate = model if candidate.nil?

  candidate.to_s
end

.name ⇒ Object 



734
735
736
 
# File 'lib/legion/extensions/llm/provider.rb', line 734

def name
  to_s.split('::').last
end

.policy_allows?(model_name, whitelist: [], blacklist: []) ⇒ Boolean

Returns:

  • (Boolean) 


602
603
604
605
606
607
608
609
610
611
 
# File 'lib/legion/extensions/llm/provider.rb', line 602

def self.policy_allows?(model_name, whitelist: [], blacklist: [])
  name = model_identity(model_name).downcase
  wl = Array(whitelist).map { |p| p.to_s.downcase }
  bl = Array(blacklist).map { |p| p.to_s.downcase }

  return false if wl.any? && wl.none? { |p| name.include?(p) }
  return false if bl.any? && bl.any? { |p| name.include?(p) }

  true
end

.remote? ⇒ Boolean

Returns:

  • (Boolean) 


766
767
768
 
# File 'lib/legion/extensions/llm/provider.rb', line 766

def remote?
  !local?
end

.resolve_model_id(model_id, config: nil) ⇒ Object

rubocop:disable Lint/UnusedMethodArgument



770
771
772
 
# File 'lib/legion/extensions/llm/provider.rb', line 770

def resolve_model_id(model_id, config: nil) # rubocop:disable Lint/UnusedMethodArgument
  model_id
end

.slug ⇒ Object 



738
739
740
 
# File 'lib/legion/extensions/llm/provider.rb', line 738

def slug
  name.downcase
end

Instance Method Details

#api_base ⇒ Object

Raises:

  • (NotImplementedError) 


94
95
96
 
# File 'lib/legion/extensions/llm/provider.rb', line 94

def api_base
  raise NotImplementedError
end

#cache_control_prefix_tokens ⇒ Object 



410
411
412
413
414
415
416
 
# File 'lib/legion/extensions/llm/provider.rb', line 410

def cache_control_prefix_tokens
  if config.respond_to?(:cache_control_prefix_tokens) && config.cache_control_prefix_tokens
    config.cache_control_prefix_tokens
  else
    4
  end
end

#cache_enabled? ⇒ Boolean

Returns:

  • (Boolean) 


397
398
399
400
401
402
403
404
405
406
407
408
 
# File 'lib/legion/extensions/llm/provider.rb', line 397

def cache_enabled?
  explicit = config.llm_cache_enabled if config.respond_to?(:llm_cache_enabled)

  unless explicit.nil?
    log.debug { "[#{slug}] cache_enabled? source=per_provider value=#{explicit}" }
    return explicit == true
  end

  global = global_prompt_caching_enabled?
  log.debug { "[#{slug}] cache_enabled? source=global value=#{global}" }
  global
end

#cache_instance_key ⇒ Object 



716
717
718
719
720
721
722
723
724
 
# File 'lib/legion/extensions/llm/provider.rb', line 716

def cache_instance_key
  if cache_local_instance?
    (respond_to?(:instance_id) ? instance_id : :default).to_s
  else
    require 'digest'
    urls = Array(config_base_url).map { |u| strip_scheme(u).downcase.chomp('/') }.sort
    Digest::SHA256.hexdigest(urls.join('|'))[0, 12]
  end
end

#cache_local_instance? ⇒ Boolean

── Cache helpers with local/shared tier selection ────────────────

Returns:

  • (Boolean) 


683
684
685
 
# File 'lib/legion/extensions/llm/provider.rb', line 683

def cache_local_instance?
  Array(config_base_url).any? { |url| Utils.localhost_url?(url) }
end

#capabilities ⇒ Object 



130
131
132
 
# File 'lib/legion/extensions/llm/provider.rb', line 130

def capabilities
  self.class.capabilities
end

#chat(messages, model:, tools: [], params: nil, headers: {}, schema: nil, thinking: nil, tool_prefs: nil) ⇒ Object

rubocop:disable Metrics/ParameterLists The single completion funnel (05 O1/O2): chat/stream_chat are thin delegates. Central enforcement — canonical input is checked HERE, once, before any rendering; providers never re-implement the check (08 F2). temperature lives only in Canonical::Params (05 O4).



184
185
186
 
# File 'lib/legion/extensions/llm/provider.rb', line 184

def chat(messages, model:, tools: [], params: nil, headers: {}, schema: nil, thinking: nil, tool_prefs: nil)
  complete(messages, tools:, model:, params:, headers:, schema:, thinking:, tool_prefs:)
end

#complete(messages, model:, tools: [], params: nil, headers: {}, schema: nil, thinking: nil, tool_prefs: nil) ⇒ Object 



193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
 
# File 'lib/legion/extensions/llm/provider.rb', line 193

def complete(messages, model:, tools: [], params: nil, headers: {}, schema: nil, thinking: nil,
             tool_prefs: nil, &)
  enforce_model_allowed!(model)
  enforce_canonical_messages!(messages)
  enforce_canonical_tools!(tools)
  log_provider_request(
    messages: messages,
    tools: tools,
    model: model,
    params: params,
    headers: headers,
    schema: schema,
    thinking: thinking,
    tool_prefs: tool_prefs,
    streaming: block_given?
  )

  payload = render_payload(
    messages,
    tools: tools,
    tool_prefs: tool_prefs,
    model: model,
    stream: block_given?,
    schema: schema,
    thinking: thinking,
    params: params
  )

  if block_given?
    stream_response @connection, payload, headers, model: model, &
  else
    sync_response @connection, payload, headers
  end
end

#config_base_url ⇒ Object 



641
642
643
 
# File 'lib/legion/extensions/llm/provider.rb', line 641

def config_base_url
  respond_to?(:settings) ? settings[:base_url] : nil
end

#configuration_requirements ⇒ Object 



134
135
136
 
# File 'lib/legion/extensions/llm/provider.rb', line 134

def configuration_requirements
  self.class.configuration_requirements
end

#configured? ⇒ Boolean

Returns:

  • (Boolean) 


393
394
395
 
# File 'lib/legion/extensions/llm/provider.rb', line 393

def configured?
  configuration_requirements.all? { |req| @config.send(req) }
end

#count_tokens(messages:, model:, params: nil) ⇒ Object 



347
348
349
350
351
352
353
 
# File 'lib/legion/extensions/llm/provider.rb', line 347

def count_tokens(messages:, model:, params: nil)
  _ = [model, params]
  enforce_canonical_messages!(messages)
  Array(messages).sum do |message|
    estimate_text_tokens(message.content)
  end
end

#disconnect ⇒ Object 



89
90
91
92
 
# File 'lib/legion/extensions/llm/provider.rb', line 89

def disconnect
  @connection&.close
  @connection = nil
end

#discover_offerings(live: false, raise_on_unreachable: false, **filters) ⇒ Object

Read path (07 C5): serves the activated inventory LANES for this provider instance from the SSOT registry snapshot — one LaneRecord per 5-tuple, in lexicographic id order. The stored inventory has no separate offering id: an offering IS a lane, keyed by the 5 tuple. A consumer needing per-model grouping groups by (instance_key, model) over the returned lanes. The per-gem writer is the sole publication path. H5: this read path performs NO transport — it is an in-memory snapshot lookup — so live: and raise_on_unreachable: are accepted for signature compatibility and have no effect here. filters select from the snapshot.



239
240
241
242
243
244
245
246
247
248
 
# File 'lib/legion/extensions/llm/provider.rb', line 239

def discover_offerings(live: false, raise_on_unreachable: false, **filters)
  _live = live
  _raise_on_unreachable = raise_on_unreachable
  instance_key = Inventory::Identity::InstanceKey.new(
    provider_family: slug.to_sym, instance_id: provider_instance_id
  )
  record = Inventory::Registry.snapshot.instance(instance_key: instance_key)
  lanes = record ? record.lanes_by_id.values.sort_by(&:lane_id) : []
  filter_inventory_offerings(lanes, filters)
end

#embed(text:, model:, dimensions: nil, params: nil, headers: {}) ⇒ Object 



318
319
320
321
322
323
324
325
326
 
# File 'lib/legion/extensions/llm/provider.rb', line 318

def embed(text:, model:, dimensions: nil, params: nil, headers: {})
  enforce_model_allowed!(model)
  payload = render_embedding_payload(text, model:, dimensions:)
  payload = Utils.deep_merge(payload, params.to_h) if params
  response = @connection.post(embedding_url(model:), payload) do |req|
    req.headers = headers.merge(req.headers) unless headers.empty?
  end
  parse_embedding_response(response, model:, text:)
end

#endpoint_manifest ⇒ Object 



448
449
450
451
452
453
454
455
456
457
458
 
# File 'lib/legion/extensions/llm/provider.rb', line 448

def endpoint_manifest
  endpoint_methods.each_with_object({}) do |(key, method_name), result|
    next unless respond_to?(method_name)

    value = public_send(method_name)
    result[key] = value unless value.nil?
  rescue ArgumentError, NotImplementedError => e
    handle_exception(e, level: :debug, handled: true, operation: 'llm.provider.endpoint_manifest', method: method_name)
    next
  end
end

#enforce_canonical_messages!(messages) ⇒ Object

N x N law — the dispatch boundary contract. Pipeline dispatch (direct SelectionDispatch, fleet worker rehydration) delivers Canonical::Message objects; provider callables are the canonical boundary and must reject anything else LOUDLY. No coercion, no hash tolerance, no fallback — a half-translated legacy shape here is the defect class the N x N method exists to kill.



144
145
146
147
148
149
150
151
152
153
 
# File 'lib/legion/extensions/llm/provider.rb', line 144

def enforce_canonical_messages!(messages)
  Array(messages).each do |message|
    next if message.is_a?(Canonical::Message)

    raise ArgumentError,
          "provider input must be Canonical::Message objects, got #{message.class} — " \
          'non-canonical message shapes must not cross the dispatch boundary'
  end
  messages
end

#enforce_canonical_tools!(tools) ⇒ Object

N x N law — the tools half of the dispatch boundary contract (H3). Enforced HERE, once, like messages: a non-empty tools value must be Hash<name, Canonical::ToolDefinition>. Hash-tolerant renderers and legacy Lex::Llm::Tool values are the defect class this check kills — the shared ToolSchema extractor already refuses them (04 §6).



160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
 
# File 'lib/legion/extensions/llm/provider.rb', line 160

def enforce_canonical_tools!(tools)
  return tools if tools.nil? || tools.empty?

  unless tools.is_a?(::Hash)
    raise ArgumentError,
          "provider tools must be Hash<name, Canonical::ToolDefinition>, got #{tools.class} — " \
          'non-canonical tool shapes must not cross the dispatch boundary'
  end

  tools.each_value do |tool|
    next if tool.is_a?(Canonical::ToolDefinition)

    raise ArgumentError,
          "provider tools values must be Canonical::ToolDefinition, got #{tool.class} — " \
          'non-canonical tool shapes must not cross the dispatch boundary'
  end
  tools
end

#enforce_model_allowed!(model_name) ⇒ Object

Compliance guard: refuse to dispatch any request for a model excluded by the configured model_whitelist / model_blacklist. Invoked at every dispatch entry point (the last line before the model API call) so a denied model can never reach a provider API, regardless of caller. Fail closed — raises rather than silently routing elsewhere.

Raises:



618
619
620
621
622
623
624
 
# File 'lib/legion/extensions/llm/provider.rb', line 618

def enforce_model_allowed!(model_name)
  return if model_allowed?(model_name)

  log.warn("[#{slug}] action=model_denied model=#{model_name} instance=#{provider_instance_id} " \
           'reason=model_whitelist_or_blacklist')
  raise ModelNotAllowedError.new(model: model_name, provider: slug)
end

#fetch_model_detail(_model_name) ⇒ Object

Override in subclasses to make a live API call for model detail. Must return a Hash with symbol keys (e.g. { context_window: 128000 }).



712
713
714
 
# File 'lib/legion/extensions/llm/provider.rb', line 712

def fetch_model_detail(_model_name)
  nil
end

#filter_inventory_offerings(offerings, filters) ⇒ Object

Read-path filter over inventory lanes: model/id/name match the lane model; instance/provider keys match the instance; unknown keys pass.



252
253
254
255
256
257
258
259
260
261
262
 
# File 'lib/legion/extensions/llm/provider.rb', line 252

def filter_inventory_offerings(offerings, filters)
  return offerings if filters.empty?

  offerings.select do |offering|
    filters.all? do |key, value|
      next true if value.nil? || (value.respond_to?(:empty?) && value.empty?)

      inventory_offering_matches_filter?(offering, key, value)
    end
  end
end

#find_reachable_url(urls) ⇒ Object 



653
654
655
656
657
658
659
 
# File 'lib/legion/extensions/llm/provider.rb', line 653

def find_reachable_url(urls)
  urls.each do |url|
    full = normalize_url(url)
    return full if url_reachable?(full)
  end
  nil
end

#format_messages(messages) ⇒ Object 



482
483
484
485
486
487
488
489
 
# File 'lib/legion/extensions/llm/provider.rb', line 482

def format_messages(messages)
  messages.map do |msg|
    {
      role: msg.role.to_s,
      content: msg.content
    }
  end
end

#format_tool_calls(_tool_calls) ⇒ Object 



491
492
493
 
# File 'lib/legion/extensions/llm/provider.rb', line 491

def format_tool_calls(_tool_calls)
  nil
end

#global_llm_setting(key) ⇒ Object

Global LLM setting: extensions.llm. (lowest specificity)



556
557
558
559
560
561
562
563
564
 
# File 'lib/legion/extensions/llm/provider.rb', line 556

def global_llm_setting(key)
  return nil unless defined?(Legion::Settings)

  llm_conf = Legion::Settings.dig(:extensions, :llm)
  llm_conf.is_a?(Hash) ? llm_conf[key] : nil
rescue StandardError => e
  handle_exception(e, level: :warn, handled: true, operation: 'llm.provider.global_llm_setting', key:)
  nil
end

#headers ⇒ Object 



98
99
100
 
# File 'lib/legion/extensions/llm/provider.rb', line 98

def headers
  identity_headers
end

#health(live: false) ⇒ Object 



277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
 
# File 'lib/legion/extensions/llm/provider.rb', line 277

def health(live: false)
  readiness_data = readiness(live:)
  raw_health = readiness_data[:health] || readiness_data['health'] || {}
  status = healthy?(readiness_data, raw_health) ? 'healthy' : 'unhealthy'
  latency_ms = (raw_health[:latency_ms] || raw_health['latency_ms'] if raw_health.is_a?(Hash))
  {
    provider: slug.to_sym,
    instance_id: provider_instance_id,
    status:,
    ready: readiness_data[:ready] == true || readiness_data['ready'] == true,
    circuit_state: status == 'healthy' ? 'closed' : 'open',
    latency_ms: latency_ms,
    raw: raw_health
  }.compact
rescue StandardError => e
  handle_exception(e, level: :warn, handled: true, operation: 'llm.provider.health')
  {
    provider: slug.to_sym,
    instance_id: provider_instance_id,
    status: 'unhealthy',
    ready: false,
    circuit_state: 'open',
    error: e.class.name,
    message: e.message
  }
end

#healthy?(readiness_data, raw_health) ⇒ Boolean

The one health classifier (10 §1E): a readiness/health body is healthy when ready is true, or the status/state names a healthy state. No other implicit health (fail-closed — 0.8.x law).

Returns:

  • (Boolean) 


307
308
309
310
311
312
313
314
315
316
 
# File 'lib/legion/extensions/llm/provider.rb', line 307

def healthy?(readiness_data, raw_health)
  return true if readiness_data.is_a?(Hash) && (readiness_data[:ready] == true || readiness_data['ready'] == true)

  status = if raw_health.is_a?(Hash)
             raw_health[:status] || raw_health['status'] || raw_health[:state] || raw_health['state']
           else
             raw_health
           end
  self.class::HEALTHY_STATES.include?(status.to_s.downcase)
end

#identity_headers ⇒ Object 



102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
 
# File 'lib/legion/extensions/llm/provider.rb', line 102

def identity_headers
  return {} unless defined?(Legion::Identity::Process) && Legion::Identity::Process.respond_to?(:identity_hash)

  id = Legion::Identity::Process.identity_hash
  hdrs = {
    'x-legion-identity-canonical-name' => id[:canonical_name].to_s,
    'x-legion-identity-trust' => id[:trust].to_s,
    'x-legion-identity-id' => id[:id].to_s,
    'x-legion-identity-kind' => id[:kind].to_s,
    'x-legion-identity-mode' => id[:mode].to_s,
    'x-legion-identity-source' => id[:source].to_s
  }
  hdrs['x-legion-identity-db-principal-id'] = id[:db_principal_id].to_s if id[:db_principal_id]
  hdrs['x-legion-identity-db-identity-id']  = id[:db_identity_id].to_s if id[:db_identity_id]
  hdrs
rescue StandardError => e
  handle_exception(e, level: :warn, handled: true, operation: 'llm.provider.identity_headers')
  {}
end

#image(prompt:, model:, size:, with: nil, mask: nil, params: {}) ⇒ Object

rubocop:disable Metrics/ParameterLists



339
340
341
342
343
344
345
 
# File 'lib/legion/extensions/llm/provider.rb', line 339

def image(prompt:, model:, size:, with: nil, mask: nil, params: {}) # rubocop:disable Metrics/ParameterLists
  enforce_model_allowed!(model)
  validate_image_inputs!(with:, mask:)
  payload = render_image_payload(prompt, model:, size:, with:, mask:, params:)
  response = @connection.post images_url(with:, mask:), payload
  parse_image_response(response, model:)
end

#instance_setting(key) ⇒ Object

Pull a setting from the instance-level settings hash (if available), distinct from the config object which is a HashConfig wrapper.



525
526
527
528
529
530
531
532
533
534
535
536
 
# File 'lib/legion/extensions/llm/provider.rb', line 525

def instance_setting(key)
  config_hash =
    if instance_variable_defined?(:@settings)
      @settings
    elsif respond_to?(:settings)
      settings
    else
      config
    end
  config_hash = config_hash.to_h if config_hash.respond_to?(:to_h)
  config_hash.is_a?(Hash) ? (config_hash[key] || config_hash[key.to_s]) : nil
end

#inventory_offering_matches_filter?(offering, key, value) ⇒ Boolean

Returns:

  • (Boolean) 


264
265
266
267
268
269
270
271
272
273
274
275
 
# File 'lib/legion/extensions/llm/provider.rb', line 264

def inventory_offering_matches_filter?(offering, key, value)
  case key.to_sym
  when :model, :id, :name
    offering.model.to_s == value.to_s
  when :instance, :instance_id, :provider_instance
    offering.instance_key.instance_id.to_s == value.to_s
  when :provider, :provider_family
    offering.instance_key.provider_family.to_s == value.to_s
  else
    true
  end
end

#local? ⇒ Boolean

Returns:

  • (Boolean) 


418
419
420
 
# File 'lib/legion/extensions/llm/provider.rb', line 418

def local?
  self.class.local?
end

#model_allowed?(model_name) ⇒ Boolean

Returns:

  • (Boolean) 


566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
 
# File 'lib/legion/extensions/llm/provider.rb', line 566

def model_allowed?(model_name)
  wl = model_whitelist
  bl = model_blacklist
  allowed = self.class.policy_allows?(model_name, whitelist: wl, blacklist: bl)

  unless allowed
    reason_parts = []
    reason_parts << 'whitelist' if wl.any?
    reason_parts << 'blacklist' if bl.any?
    reason_str = reason_parts.empty? ? 'policy' : reason_parts.join(',')
    policy_src = if wl.any?
                   "wl=[#{wl.first(5).join(',')}#{',...' if wl.size > 5}]"
                 else
                   'no-whitelist'
                 end
    log.debug("[#{self.class.slug}] action=model_rejected name=#{model_name} reason=#{reason_str} #{policy_src}")
  end

  allowed
end

#model_blacklist ⇒ Object

Resolve model_blacklist with the same specificity cascade as model_whitelist.



515
516
517
518
519
520
521
 
# File 'lib/legion/extensions/llm/provider.rb', line 515

def model_blacklist
  bl = config.model_blacklist if config.respond_to?(:model_blacklist)
  bl ||= instance_setting(:model_blacklist)
  bl ||= runtime_provider_setting(:model_blacklist)
  bl ||= global_llm_setting(:model_blacklist)
  Array(bl).map { |p| p.to_s.downcase }
end

#model_cache_get(key) ⇒ Object 



687
688
689
690
691
692
693
694
 
# File 'lib/legion/extensions/llm/provider.rb', line 687

def model_cache_get(key)
  return nil unless defined?(Legion::Cache)

  cache_local_instance? ? local_cache_get(key) : cache_get(key)
rescue StandardError => e
  handle_exception(e, level: :warn, handled: true, operation: 'llm.provider.model_cache_get', key:)
  nil
end

#model_detail(model_name) ⇒ Object 



696
697
698
699
700
701
702
703
704
705
706
707
708
 
# File 'lib/legion/extensions/llm/provider.rb', line 696

def model_detail(model_name)
  key = model_detail_cache_key(model_name)
  cached = cache_get(key)
  return cached if cached

  result = fetch_model_detail(model_name)
  cache_set(key, result, ttl: 86_400) if result
  result
rescue StandardError => e
  handle_exception(e, level: :warn, handled: true, operation: 'llm.provider.model_detail',
                      model: model_name)
  nil
end

#model_whitelist ⇒ Object

Resolve model_whitelist with specificity cascade:

  1. Instance-level (config.model_whitelist — extensions.llm..instances..model_whitelist)
  2. Provider-level (extensions.llm..model_whitelist)
  3. Global (extensions.llm.model_whitelist) Returns the first non-nil, non-empty value found.


506
507
508
509
510
511
512
 
# File 'lib/legion/extensions/llm/provider.rb', line 506

def model_whitelist
  wl = config.model_whitelist if config.respond_to?(:model_whitelist)
  wl ||= instance_setting(:model_whitelist)
  wl ||= runtime_provider_setting(:model_whitelist)
  wl ||= global_llm_setting(:model_whitelist)
  Array(wl).map { |p| p.to_s.downcase }
end

#moderate(input:, model:) ⇒ Object 



328
329
330
331
332
333
334
335
336
337
 
# File 'lib/legion/extensions/llm/provider.rb', line 328

def moderate(input:, model:)
  enforce_model_allowed!(model)
  unless input.is_a?(::String) || (input.is_a?(::Array) && input.all?(Canonical::Message))
    raise ArgumentError, "moderate input must be a String or Array<Canonical::Message>, got #{input.class}"
  end

  payload = render_moderation_payload(input, model:)
  response = @connection.post moderation_url, payload
  parse_moderation_response(response, model:)
end

#name ⇒ Object 



126
127
128
 
# File 'lib/legion/extensions/llm/provider.rb', line 126

def name
  self.class.name
end

#normalize_dispatch_error(error:) ⇒ Object

Runtime error-to-outcome normalization consumed by the common classifier. The inherited base is deliberately conservative: raw 503, Anthropic-style 529, ServiceUnavailableError, ServerError, and every unrecognized error return :provider_error, never :instance_unavailable. Provider PRs override only when their wire semantics supply stronger evidence. The fallback reason is the bounded exception class name — never a response body, credential, endpoint, or exception object. It is a base method, not a REQUIRED_SIGNATURES reflection entry.



385
386
387
388
389
390
391
 
# File 'lib/legion/extensions/llm/provider.rb', line 385

def normalize_dispatch_error(error:)
  reason = error.class.name
  reason = 'UnknownError' if reason.nil? || reason.empty?
  Legion::Extensions::Llm::Routing::ProviderOutcome.new(
    kind: Legion::Extensions::Llm::Routing::ProviderOutcome.kind_for(error), reason: reason
  )
end

#normalize_url(url) ⇒ Object 



645
646
647
648
649
650
651
 
# File 'lib/legion/extensions/llm/provider.rb', line 645

def normalize_url(url)
  raw = url.to_s.strip
  return raw if raw.match?(%r{^https?://})

  scheme = tls_enabled? ? 'https' : 'http'
  "#{scheme}://#{raw}"
end

#offering_tier ⇒ Object

── Offering defaults ─────────────────────────────────────────────



628
629
630
 
# File 'lib/legion/extensions/llm/provider.rb', line 628

def offering_tier
  config.respond_to?(:tier) ? config.tier : self.class.default_tier
end

#parse_error(response) ⇒ Object 



460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
 
# File 'lib/legion/extensions/llm/provider.rb', line 460

def parse_error(response)
  return if response.body.empty?

  body = try_parse_json(response.body)
  case body
  when Hash
    error = body['error']
    return error if error.is_a?(String)

    body.dig('error', 'message')
  when Array
    body.map do |part|
      error = part['error']
      error.is_a?(String) ? error : part.dig('error', 'message')
    end.join('. ')
  when String
    body[/"message"\s*:\s*"([^"]{1,500})/, 1] || body
  else
    body
  end
end

#parse_tool_calls(_tool_calls) ⇒ Object 



495
496
497
 
# File 'lib/legion/extensions/llm/provider.rb', line 495

def parse_tool_calls(_tool_calls)
  nil
end

#provider_instance_id ⇒ Object

M6: the instance identity is CARRIED from the owner (R6) — the single config→id derivation lives in Inventory::Identity. No local re-derivation (node names, family fallbacks) exists here.



729
730
731
 
# File 'lib/legion/extensions/llm/provider.rb', line 729

def provider_instance_id
  Inventory::Identity.instance_id(config).to_sym
end

#readiness(live: false) ⇒ Object 



426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
 
# File 'lib/legion/extensions/llm/provider.rb', line 426

def readiness(live: false)
  metadata = {
    provider: slug.to_sym,
    name: name,
    configured: configured?,
    ready: configured?,
    local: local?,
    remote: remote?,
    api_base: api_base,
    endpoints: endpoint_manifest,
    live: live
  }

  return metadata.merge(health: { checked: false }) unless live && metadata[:endpoints][:health]

  response = @connection.get(metadata[:endpoints][:health])
  metadata.merge(ready: configured? && healthy?(nil, response.body), health: response.body)
rescue StandardError => e
  handle_exception(e, level: :warn, handled: true, operation: 'llm.provider.readiness')
  metadata.merge(ready: false, health: { error: e.class.name, message: e.message })
end

#remote? ⇒ Boolean

Returns:

  • (Boolean) 


422
423
424
 
# File 'lib/legion/extensions/llm/provider.rb', line 422

def remote?
  self.class.remote?
end

#resolve_base_url ⇒ Object

── Multi-host base_url resolution ────────────────────────────────



634
635
636
637
638
639
 
# File 'lib/legion/extensions/llm/provider.rb', line 634

def resolve_base_url
  urls = Array(config_base_url)
  return nil if urls.empty?

  @resolve_base_url ||= find_reachable_url(urls) || normalize_url(urls.first)
end

#runtime_provider_setting(key) ⇒ Object

Provider-level setting: extensions.llm..



539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
 
# File 'lib/legion/extensions/llm/provider.rb', line 539

def runtime_provider_setting(key)
  return nil unless defined?(Legion::Settings)

  ext = Legion::Settings[:extensions]
  return nil unless ext.is_a?(Hash) && ext[:llm].is_a?(Hash)

  provider_key = self.class.respond_to?(:slug) ? self.class.slug.to_sym : nil
  return nil unless provider_key

  provider_conf = ext[:llm][provider_key]
  provider_conf.is_a?(Hash) ? provider_conf[key] : nil
rescue StandardError => e
  handle_exception(e, level: :warn, handled: true, operation: 'llm.provider.runtime_provider_setting', key:)
  nil
end

#slug ⇒ Object 



122
123
124
 
# File 'lib/legion/extensions/llm/provider.rb', line 122

def slug
  self.class.slug
end

#speak(text, model:, voice: nil, **provider_options) ⇒ Object

Raises:

  • (NotImplementedError) 


372
373
374
375
 
# File 'lib/legion/extensions/llm/provider.rb', line 372

def speak(text, model:, voice: nil, **provider_options)
  _ = [text, model, voice, provider_options]
  raise NotImplementedError, "#{self.class} does not implement speak"
end

#stream_chat(messages, model:, tools: [], params: nil, headers: {}, schema: nil, thinking: nil, tool_prefs: nil) ⇒ Object 



188
189
190
191
 
# File 'lib/legion/extensions/llm/provider.rb', line 188

def stream_chat(messages, model:, tools: [], params: nil, headers: {}, schema: nil,
                thinking: nil, tool_prefs: nil, &)
  complete(messages, tools:, model:, params:, headers:, schema:, thinking:, tool_prefs:, &)
end

#strip_scheme(url) ⇒ Object 



661
662
663
 
# File 'lib/legion/extensions/llm/provider.rb', line 661

def strip_scheme(url)
  url.to_s.sub(%r{^https?://}, '')
end

#tls_enabled? ⇒ Boolean

Returns:

  • (Boolean) 


676
677
678
679
 
# File 'lib/legion/extensions/llm/provider.rb', line 676

def tls_enabled?
  tls = respond_to?(:settings) ? settings[:tls] : nil
  tls.is_a?(Hash) && tls[:enabled] == true
end

#transcribe(audio_file, model:, language:) ⇒ Object 



355
356
357
358
359
360
 
# File 'lib/legion/extensions/llm/provider.rb', line 355

def transcribe(audio_file, model:, language:, **)
  file_part = build_audio_file_part(audio_file)
  payload = render_transcription_payload(file_part, model:, language:, **)
  response = @connection.post transcription_url, payload
  parse_transcription_response(response, model:)
end

#translate(audio_file, model:, language:, **provider_options) ⇒ Object

Fail-loud base audio operations. Unsupported providers inherit these and publish OperationEvidence(status: :unsupported) or :unknown; a provider may publish :supported only when its Phase 2 conformance spec exercises the actual callable path. Neither method reads configuration or infers a model.

Raises:

  • (NotImplementedError) 


367
368
369
370
 
# File 'lib/legion/extensions/llm/provider.rb', line 367

def translate(audio_file, model:, language:, **provider_options)
  _ = [audio_file, model, language, provider_options]
  raise NotImplementedError, "#{self.class} does not implement translate"
end

#url_reachable?(url) ⇒ Boolean

Returns:

  • (Boolean) 


665
666
667
668
669
670
671
672
673
674
 
# File 'lib/legion/extensions/llm/provider.rb', line 665

def url_reachable?(url)
  require 'uri'
  require 'socket'
  uri = URI.parse(url)
  Socket.tcp(uri.host, uri.port, connect_timeout: 1).close
  true
rescue StandardError => e
  handle_exception(e, level: :warn, handled: true, operation: 'llm.provider.url_reachable', url:)
  false
end