lex-llm 0.7.6 → 0.8.0

data/lib/legion/extensions/llm/embedding.rb

@@ -1,33 +0,0 @@
-# frozen_string_literal: true
-
-module Legion
-  module Extensions
-    module Llm
-      # Core embedding interface.
-      class Embedding
-        attr_reader :vectors, :model, :input_tokens
-
-        def initialize(vectors:, model:, input_tokens: 0)
-          @vectors = vectors
-          @model = model
-          @input_tokens = input_tokens
-        end
-
-        def self.embed(text, # rubocop:disable Metrics/ParameterLists
-                       model: nil,
-                       provider: nil,
-                       assume_model_exists: false,
-                       context: nil,
-                       dimensions: nil)
-          config = context&.config || Legion::Extensions::Llm.config
-          model ||= config.default_embedding_model
-          model, provider_instance = Models.resolve(model, provider: provider, assume_exists: assume_model_exists,
-                                                           config: config)
-          model_id = model.id
-
-          provider_instance.embed(text:, model: model_id, dimensions:)
-        end
-      end
-    end
-  end
-end

data/lib/legion/extensions/llm/image.rb

@@ -1,109 +0,0 @@
-# frozen_string_literal: true
-
-module Legion
-  module Extensions
-    module Llm
-      # Represents a generated image from an AI model.
-      class Image
-        attr_reader :url, :data, :mime_type, :revised_prompt, :model_id, :usage
-
-        def initialize(url: nil, data: nil, mime_type: nil, revised_prompt: nil, model_id: nil, usage: {}) # rubocop:disable Metrics/ParameterLists
-          @url = url
-          @data = data
-          @mime_type = mime_type
-          @revised_prompt = revised_prompt
-          @model_id = model_id
-          @usage = usage
-        end
-
-        def base64?
-          !@data.nil?
-        end
-
-        def to_blob
-          if base64?
-            Base64.decode64 @data
-          else
-            response = Connection.basic.get @url
-            response.body
-          end
-        end
-
-        def save(path)
-          File.binwrite(File.expand_path(path), to_blob)
-          path
-        end
-
-        def self.paint(prompt, # rubocop:disable Metrics/ParameterLists
-                       model: nil,
-                       provider: nil,
-                       assume_model_exists: false,
-                       size: '1024x1024',
-                       context: nil,
-                       with: nil,
-                       mask: nil,
-                       params: {})
-          config = context&.config || Legion::Extensions::Llm.config
-          model ||= config.default_image_model
-          model, provider_instance = Models.resolve(model, provider: provider, assume_exists: assume_model_exists,
-                                                           config: config)
-          model_id = model.id
-
-          provider_instance.paint(prompt, model: model_id, size:, with:, mask:, params:)
-        end
-
-        def total_cost
-          input_cost + output_cost
-        end
-
-        def input_cost
-          return flat_input_cost unless detailed_input_usage?
-
-          text_input_cost + image_input_cost
-        end
-
-        def output_cost
-          tokens_for('output_tokens') * output_token_price.to_f / 1_000_000
-        end
-
-        def model_info
-          @model_info ||= Legion::Extensions::Llm.models.find(model_id)
-        end
-
-        private
-
-        def flat_input_cost
-          tokens_for('input_tokens') * model_info.input_price_per_million.to_f / 1_000_000
-        end
-
-        def text_input_cost
-          input_detail('text_tokens') * model_info.input_price_per_million.to_f / 1_000_000
-        end
-
-        def image_input_cost
-          input_detail('image_tokens') * image_input_token_price.to_f / 1_000_000
-        end
-
-        def output_token_price
-          model_info.pricing.images.output || model_info.output_price_per_million
-        end
-
-        def image_input_token_price
-          model_info.pricing.images.input || model_info.input_price_per_million
-        end
-
-        def detailed_input_usage?
-          usage['input_tokens_details'].is_a?(Hash)
-        end
-
-        def input_detail(key)
-          usage.dig('input_tokens_details', key).to_i
-        end
-
-        def tokens_for(key)
-          usage[key].to_i
-        end
-      end
-    end
-  end
-end

data/lib/legion/extensions/llm/inventory/capabilities.rb

@@ -1,40 +0,0 @@
-# frozen_string_literal: true
-
-require_relative '../capabilities'
-
-module Legion
-  module Extensions
-    module Llm
-      module Inventory
-        # Inventory-side capability normalization. Every per-gem DiscoveryRefresh actor
-        # calls this from `lanes_from_instance` to coerce offering capabilities into a
-        # canonical symbol list before writing the lane to Inventory. Without this
-        # constant, every actor's guard `return [] unless defined?(...)` fires and the
-        # lane is written with `capabilities: []` — even when the operator declared
-        # `enable_tools: true` / `enable_thinking: true` on the instance and the
-        # provider's CapabilityPolicy correctly resolved them in the offering.
-        #
-        # Delegates to Legion::Extensions::Llm::Capabilities so the alias table
-        # (function_calling/tool_use/tool_calls/tool/functions → tools, etc.) stays
-        # in one place.
-        module Capabilities
-          ALIASES = Legion::Extensions::Llm::Capabilities::ALIASES
-
-          module_function
-
-          def normalize(caps, **)
-            Legion::Extensions::Llm::Capabilities.normalize(caps, **)
-          end
-
-          def merge(*sets, **)
-            Legion::Extensions::Llm::Capabilities.merge(*sets, **)
-          end
-
-          def include_all?(available, required, **)
-            Legion::Extensions::Llm::Capabilities.include_all?(available, required, **)
-          end
-        end
-      end
-    end
-  end
-end

data/lib/legion/extensions/llm/inventory/scoped_refresher.rb

@@ -1,310 +0,0 @@
-# frozen_string_literal: true
-
-require 'legion/logging'
-require 'legion/extensions/llm/inventory/errors'
-require 'legion/extensions/llm/inventory/identity'
-require 'legion/extensions/llm/inventory/snapshot'
-require 'legion/extensions/llm/taxonomies'
-
-module Legion
-  module Extensions
-    module Llm
-      module Inventory
-        # DEPRECATED (Phase 4 removal): the only Phase 1 file permitted to hold a
-        # direct `Legion::LLM::Inventory` reverse reference. Old released provider
-        # actors keep using ScopedRefresher#tick until their Phase 2 migration; a
-        # migrated actor instead injects ScopedRefresher::LegacyCoordinatorAdapter
-        # into Inventory::Publisher and never calls #tick. Neither old lane hashes
-        # nor old health feed the new registry. Phase 4 deletes this file once
-        # every provider and coordinator floor has migrated.
-        #
-        # Mix into a Legion::Extensions::Llm::*::Actors::DiscoveryRefresh class.
-        # The host class must include Legion::Extensions::Helpers::Lex (auto-injects
-        # log / settings / handle_exception / cache_*) and define:
-        #   - #scope_key          — Hash like { provider: :vllm, instance: instance_id }
-        #   - #compute_lanes_for_scope — Array<Hash> lane fact-sheets (no health, no
-        #                               lane_weight — added by Inventory.write_lane).
-        #                               Each lane MUST set :id via compose_id.
-        #   - #credential_hash    — String identifying the auth credential for this scope
-        #                           (used by the auth-failure cooldown circuit).
-        module ScopedRefresher
-          # Auth-failure cooldown TTL (5 minutes). Operator can fix the credential
-          # and lanes auto-recover on the next tick after expiry.
-          AUTH_COOLDOWN_TTL = 300
-
-          # G22: 5-part lane id composed here and ONLY here. All gem writers MUST call
-          # this helper; Inventory.write_lane rejects any lane with a missing or malformed :id.
-          # Accepts a Hash (or keyword splat) with keys: tier, provider_family, instance_id, type, model.
-          def self.compose_id(lane_fields)
-            t  = lane_fields[:tier]
-            pf = lane_fields[:provider_family]
-            ii = lane_fields[:instance_id]
-            ty = lane_fields[:type]
-            mo = lane_fields[:model]
-            "#{t}:#{pf}:#{ii}:#{ty}:#{mo}"
-          end
-
-          # G7 write-then-delete-orphans: write new lanes FIRST (eliminates zero-results
-          # race window), then delete orphans from the previous scope snapshot.
-          def tick(**)
-            return if auth_cooldown_active?
-
-            new_lanes = safe_compute
-            log.info("[llm][scoped_refresher] action=tick provider=#{scope_key[:provider]} lanes_computed=#{new_lanes ? new_lanes.size : 0}")
-            return unless new_lanes&.any?
-
-            written = 0
-            new_lanes.each do |lane_fact|
-              written += 1 if Legion::LLM::Inventory.write_lane(lane: lane_fact)
-            end
-            log.info("[llm][scoped_refresher] action=tick_complete provider=#{scope_key[:provider]} lanes_computed=#{new_lanes.size} lanes_written=#{written}")
-
-            orphans = (@prev_scope_keys || []) - new_lanes.map { it[:id] }
-            orphans.each { |id| Legion::LLM::Inventory.delete_lane(id: id) }
-
-            @prev_scope_keys = new_lanes.map { it[:id] }
-          end
-
-          private
-
-          # Wraps compute_lanes_for_scope with auth-failure cooldown logic.
-          # If a cooldown key is present from a previous auth failure, skips the
-          # compute entirely (no real call burned). On a new auth failure, writes the
-          # cooldown key with AUTH_COOLDOWN_TTL so subsequent ticks also skip.
-          def safe_compute
-            if auth_cooldown_active?
-              log.warn("[llm][scoped_refresher] action=skip reason=auth_cooldown scope=#{scope_key}")
-              return nil
-            end
-            compute_lanes_for_scope
-          rescue NotImplementedError
-            raise
-          rescue StandardError => e
-            if auth_failure?(error: e)
-              Legion::Cache::Local.set(auth_cooldown_key, 1, ttl: AUTH_COOLDOWN_TTL)
-              handle_exception(e, level: :warn, handled: true,
-                                  operation: 'inventory.scoped_refresher.auth_failure',
-                                  scope: scope_key)
-            else
-              handle_exception(e, level: :warn, handled: true,
-                                  operation: 'inventory.scoped_refresher.compute',
-                                  scope: scope_key)
-            end
-            nil
-          end
-
-          def auth_cooldown_active?
-            !Legion::Cache::Local.get(auth_cooldown_key).nil?
-          rescue StandardError
-            false
-          end
-
-          def auth_cooldown_key
-            "llm_auth_failed:#{credential_hash}"
-          end
-
-          # Default auth-failure predicate. Matches HTTP 401/403 status codes and
-          # common auth-error message patterns. Provider gems may override this if
-          # their error shapes differ (e.g. Bedrock's AccessDeniedException).
-          def auth_failure?(error:, **)
-            return true if error.respond_to?(:status_code) && [401, 403].include?(error.status_code)
-            return true if error.respond_to?(:http_status) && [401, 403].include?(error.http_status)
-
-            error.message&.match?(/unauthorized|invalid[_ ]api[_ ]key|invalid[_ ]credentials|forbidden/i)
-          end
-
-          # One-way, post-commit projection of an already-committed new Snapshot
-          # into the old Legion::LLM::Inventory coordinator, for the mixed-version
-          # window only. It never rediscovers, selects, authorizes new state, or
-          # feeds an old fact back into the new Registry. See section 13.3.
-          class LegacyCoordinatorAdapter
-            include Legion::Logging::Helper
-
-            HEALTHY_COMPAT = { circuit_state: :closed, denied: false, available: true, adjustment: 0 }.freeze
-            LEGACY_CAPABILITIES = {
-              chat: :completion, stream_chat: :streaming, embed: :embedding, image: :image,
-              transcribe: :audio_transcription, translate: :audio_transcription, speak: :audio_speech, moderate: :moderation
-            }.freeze
-
-            def initialize(provider_family:, legacy_instance_ids_by_instance: {})
-              @provider_family = canonical_family(provider_family)
-              @legacy_instance_ids = deep_freeze_legacy_ids(legacy_instance_ids_by_instance)
-              @published_ids_by_instance = {}.freeze
-              @mutex = Mutex.new
-            end
-
-            def sync_snapshot(snapshot:, instance_key:, mutation_reason:)
-              validate_inputs!(snapshot, instance_key, mutation_reason)
-              return :not_loaded unless legacy_inventory_available?
-
-              project(snapshot, instance_key)
-            end
-
-            private
-
-            def project(snapshot, instance_key)
-              @mutex.synchronize { project_locked(snapshot, instance_key) }
-              :applied
-            rescue StandardError => e
-              handle_exception(
-                e, handled: true, level: :warn, operation: 'inventory.scoped_refresher.legacy_projection',
-                   provider_family: @provider_family, instance_id: instance_key.instance_id,
-                   source_generation: snapshot.generation
-              )
-              :failed
-            end
-
-            def project_locked(snapshot, instance_key)
-              desired = desired_lanes(snapshot, instance_key)
-              written = write_desired(desired)
-              reconcile_deletions(instance_key, written)
-              @published_ids_by_instance = @published_ids_by_instance.merge(
-                instance_key.instance_id => written.to_a.freeze
-              ).freeze
-            end
-
-            def desired_lanes(snapshot, instance_key)
-              record = snapshot.instance(instance_key: instance_key)
-              return {} if record.nil? || record.availability.state != :available
-
-              build_desired(group_lanes(snapshot, instance_key), snapshot.generation)
-            end
-
-            def group_lanes(snapshot, instance_key)
-              groups = {}
-              snapshot.lanes_for(instance_key: instance_key).each do |lane|
-                type = Taxonomies.lane_type_for(operation: lane.operation)
-                key = [lane.tier, instance_key.provider_family, instance_key.instance_id, type, lane.model]
-                group = (groups[key] ||= new_group(instance_key, lane, type))
-                accumulate_group(group, lane)
-              end
-              groups
-            end
-
-            def new_group(instance_key, lane, type)
-              {
-                tier: lane.tier, provider_family: instance_key.provider_family, instance_id: instance_key.instance_id,
-                type: type, model: lane.model, offering_ids: Set.new, capabilities: Set.new,
-                context_values: Set.new, max_output_values: Set.new
-              }
-            end
-
-            def accumulate_group(group, lane)
-              group[:offering_ids] << lane.offering_id
-              mapped = LEGACY_CAPABILITIES[lane.operation]
-              group[:capabilities] << mapped if mapped
-              lane.capability_evidence.each { |capability, evidence| group[:capabilities] << capability if evidence.supported? }
-              group[:context_values] << lane.context_evidence.value if lane.context_evidence.known?
-              group[:max_output_values] << lane.max_output_evidence.value if lane.max_output_evidence.known?
-            end
-
-            def build_desired(groups, generation)
-              by_id = {}
-              groups.each_value do |group|
-                legacy_id = ScopedRefresher.compose_id(identity_fields(group))
-                (by_id[legacy_id] ||= []) << group
-              end
-
-              by_id.each_with_object({}) do |(legacy_id, colliding), desired|
-                if colliding.size > 1 || colliding.first[:offering_ids].size != 1
-                  log.warn("[llm][inventory][legacy_adapter] action=fail_closed reason=ambiguous_group legacy_id=#{legacy_id}")
-                  next
-                end
-                desired[legacy_id] = build_lane_hash(legacy_id, colliding.first, generation)
-              end
-            end
-
-            def identity_fields(group)
-              {
-                tier: group[:tier], provider_family: group[:provider_family],
-                instance_id: group[:instance_id], type: group[:type], model: group[:model]
-              }.freeze
-            end
-
-            def build_lane_hash(legacy_id, group, generation)
-              {
-                id: legacy_id, tier: group[:tier], provider_family: group[:provider_family],
-                provider_instance: group[:instance_id], instance_id: group[:instance_id], type: group[:type],
-                model: group[:model], offering_id: group[:offering_ids].first,
-                capabilities: group[:capabilities].to_a.sort, limits: build_limits(group),
-                metadata: { ssot_v3_compatibility_projection: true, source_generation: generation }, enabled: true
-              }
-            end
-
-            def build_limits(group)
-              limits = {}
-              limits[:context_window] = group[:context_values].first if group[:context_values].size == 1
-              limits[:max_output_tokens] = group[:max_output_values].first if group[:max_output_values].size == 1
-              limits
-            end
-
-            def write_desired(desired)
-              written = Set.new
-              desired.each do |legacy_id, lane_hash|
-                result = ::Legion::LLM::Inventory.write_lane(lane: lane_hash, health: HEALTHY_COMPAT)
-                written << legacy_id unless result.nil?
-              end
-              written
-            end
-
-            def reconcile_deletions(instance_key, written)
-              tracked = @published_ids_by_instance.fetch(instance_key.instance_id, [])
-              candidates = (tracked.to_a + read_current_old_ids(instance_key).to_a).uniq
-              candidates.each do |old_id|
-                next if written.include?(old_id)
-
-                ::Legion::LLM::Inventory.delete_lane(id: old_id)
-              end
-            end
-
-            def read_current_old_ids(instance_key)
-              instance_ids_to_read(instance_key).each_with_object(Set.new) do |instance_id, ids|
-                lanes = ::Legion::LLM::Inventory.lanes_for(provider: @provider_family, instance: instance_id)
-                Array(lanes).each { |lane| ids << (lane.is_a?(::Hash) ? lane[:id] : lane) }
-              end
-            end
-
-            def instance_ids_to_read(instance_key)
-              ([instance_key.instance_id] + @legacy_instance_ids.fetch(instance_key.instance_id, [])).uniq
-            end
-
-            def validate_inputs!(snapshot, instance_key, mutation_reason)
-              raise Errors::ValidationError, 'snapshot must be an Inventory::Snapshot' unless snapshot.is_a?(Snapshot)
-              unless instance_key.is_a?(Identity::InstanceKey) && instance_key.provider_family == @provider_family
-                raise Errors::ValidationError, 'instance_key must belong to the adapter provider family'
-              end
-              return if Taxonomies::MUTATION_REASONS.include?(mutation_reason)
-
-              raise Errors::ValidationError, 'mutation_reason must be a Taxonomies::MUTATION_REASONS value'
-            end
-
-            def legacy_inventory_available?
-              defined?(::Legion::LLM::Inventory) &&
-                ::Legion::LLM::Inventory.respond_to?(:lanes_for) &&
-                ::Legion::LLM::Inventory.respond_to?(:write_lane) &&
-                ::Legion::LLM::Inventory.respond_to?(:delete_lane)
-            end
-
-            def canonical_family(value)
-              text = Identity.normalize_text(value: value, field: :provider_family).downcase
-              raise Errors::ValidationError, 'provider_family must be snake-case ASCII' unless text.match?(/\A[a-z][a-z0-9_]*\z/)
-
-              text.to_sym
-            end
-
-            def deep_freeze_legacy_ids(mapping)
-              raise Errors::ValidationError, 'legacy_instance_ids_by_instance must be a Hash' unless mapping.is_a?(::Hash)
-
-              mapping.each_with_object({}) do |(key, values), frozen|
-                raise Errors::ValidationError, 'legacy instance id keys must be Strings' unless key.is_a?(::String)
-                raise Errors::ValidationError, 'legacy superseded ids must be a nonempty Array of Strings' unless values.is_a?(::Array) && !values.empty? && values.all?(::String)
-
-                frozen[key.dup.freeze] = values.map { |value| value.dup.freeze }.freeze
-              end.freeze
-            end
-          end
-        end
-      end
-    end
-  end
-end

data/lib/legion/extensions/llm/message.rb

@@ -1,118 +0,0 @@
-# frozen_string_literal: true
-
-module Legion
-  module Extensions
-    module Llm
-      # A single message in a chat conversation.
-      class Message
-        ROLES = %i[system user assistant tool].freeze
-
-        attr_reader :role, :model_id, :tool_calls, :tool_call_id, :raw, :thinking, :tokens, :stop_reason
-        attr_writer :content
-
-        def initialize(options = {})
-          @role = options.fetch(:role).to_sym
-          @tool_calls = options[:tool_calls]
-          @content = normalize_content(options.fetch(:content), role: @role, tool_calls: @tool_calls)
-          @model_id = options[:model_id]
-          @tool_call_id = options[:tool_call_id]
-          @tokens = options[:tokens] || Tokens.build(
-            input: options[:input_tokens],
-            output: options[:output_tokens],
-            cached: options[:cached_tokens],
-            cache_creation: options[:cache_creation_tokens],
-            thinking: options[:thinking_tokens],
-            reasoning: options[:reasoning_tokens]
-          )
-          @raw = options[:raw]
-          @thinking = options[:thinking]
-          @stop_reason = options[:stop_reason]
-
-          ensure_valid_role
-        end
-
-        def content
-          if @content.is_a?(Content) && @content.text && @content.attachments.empty?
-            @content.text
-          else
-            @content
-          end
-        end
-
-        def tool_call?
-          !tool_calls.nil? && !tool_calls.empty?
-        end
-
-        def tool_result?
-          !tool_call_id.nil? && !tool_call_id.empty?
-        end
-
-        def tool_results
-          content if tool_result?
-        end
-
-        def input_tokens
-          tokens&.input
-        end
-
-        def output_tokens
-          tokens&.output
-        end
-
-        def cached_tokens
-          tokens&.cached
-        end
-
-        def cache_creation_tokens
-          tokens&.cache_creation
-        end
-
-        def thinking_tokens
-          tokens&.thinking
-        end
-
-        def reasoning_tokens
-          tokens&.thinking
-        end
-
-        def to_h
-          {
-            role: role,
-            content: content,
-            model_id: model_id,
-            tool_calls: tool_calls,
-            tool_call_id: tool_call_id
-          }.merge(tokens ? tokens.to_h : {}).compact
-        end
-
-        def to_internal_h
-          to_h.merge(
-            thinking: thinking&.text,
-            thinking_signature: thinking&.signature,
-            raw: raw
-          ).compact
-        end
-
-        def instance_variables
-          super - [:@raw]
-        end
-
-        private
-
-        def normalize_content(content, role:, tool_calls:)
-          return '' if role == :assistant && content.nil? && tool_calls && !tool_calls.empty?
-
-          case content
-          when String then Content.new(content)
-          when Hash then Content.new(content[:text], content)
-          else content
-          end
-        end
-
-        def ensure_valid_role
-          raise InvalidRoleError, "Expected role to be one of: #{ROLES.join(', ')}" unless ROLES.include?(role)
-        end
-      end
-    end
-  end
-end

data/lib/legion/extensions/llm/mime_type.rb

@@ -1,75 +0,0 @@
-# frozen_string_literal: true
-
-require 'marcel'
-
-module Legion
-  module Extensions
-    module Llm
-      # MimeTypes module provides methods to handle MIME types using Marcel gem
-      module MimeType
-        module_function
-
-        def for(...)
-          Marcel::MimeType.for(...)
-        end
-
-        def image?(type)
-          type.start_with?('image/')
-        end
-
-        def video?(type)
-          type.start_with?('video/')
-        end
-
-        def audio?(type)
-          type.start_with?('audio/')
-        end
-
-        def pdf?(type)
-          type == 'application/pdf'
-        end
-
-        def text?(type)
-          type.start_with?('text/') ||
-            TEXT_SUFFIXES.any? { |suffix| type.end_with?(suffix) } ||
-            NON_TEXT_PREFIX_TEXT_MIME_TYPES.include?(type)
-        end
-
-        # MIME types that have a text/ prefix but need to be handled differently
-        TEXT_SUFFIXES = ['+json', '+xml', '+html', '+yaml', '+csv', '+plain', '+javascript', '+svg'].freeze
-
-        # MIME types that don't have a text/ prefix but should be treated as text
-        NON_TEXT_PREFIX_TEXT_MIME_TYPES = [
-          'application/json', # Base type, even if specific ones end with +json
-          'application/xml',  # Base type, even if specific ones end with +xml
-          'application/javascript',
-          'application/ecmascript',
-          'application/rtf',
-          'application/sql',
-          'application/x-sh',
-          'application/x-csh',
-          'application/x-httpd-php',
-          'application/sdp',
-          'application/sparql-query',
-          'application/graphql',
-          'application/yang', # Data modeling language, often serialized as XML/JSON but the type itself is distinct
-          'application/mbox', # Mailbox format
-          'application/x-tex',
-          'application/x-latex',
-          'application/x-perl',
-          'application/x-python',
-          'application/x-tcl',
-          'application/pgp-signature', # Often ASCII armored
-          'application/pgp-keys',      # Often ASCII armored
-          'application/vnd.coffeescript',
-          'application/vnd.dart',
-          'application/vnd.oai.openapi', # Base for OpenAPI, often with +json or +yaml suffix
-          'application/vnd.zul',         # ZK User Interface Language (can be XML-like)
-          'application/x-yaml',          # Common non-standard for YAML
-          'application/yaml',            # Standard for YAML
-          'application/toml'             # TOML configuration files
-        ].freeze
-      end
-    end
-  end
-end