lex-llm 0.1.2 → 0.1.4

data/lib/legion/extensions/llm/provider/open_ai_compatible.rb

@@ -0,0 +1,276 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Llm
+      class Provider
+        # Shared OpenAI-compatible HTTP payload and response adapter.
+        module OpenAICompatible
+          def completion_url = '/v1/chat/completions'
+          def stream_url = completion_url
+          def models_url = '/v1/models'
+          def moderation_url = '/v1/moderations'
+          def embedding_url(**) = '/v1/embeddings'
+          def transcription_url = '/v1/audio/transcriptions'
+
+          def images_url(with:, mask:)
+            with || mask ? '/v1/images/edits' : '/v1/images/generations'
+          end
+
+          private
+
+          def render_payload(messages, tools:, temperature:, model:, stream:, schema:, thinking:, tool_prefs:) # rubocop:disable Metrics/ParameterLists
+            {
+              model: model.id,
+              messages: format_openai_messages(messages),
+              temperature: temperature,
+              stream: stream,
+              tools: format_openai_tools(tools),
+              tool_choice: openai_tool_choice(tool_prefs),
+              response_format: openai_response_format(schema),
+              reasoning_effort: openai_reasoning_effort(thinking)
+            }.compact
+          end
+
+          def format_openai_messages(messages)
+            messages.map do |message|
+              {
+                role: message.role.to_s,
+                content: openai_content(message.content),
+                tool_call_id: message.tool_call_id,
+                tool_calls: format_openai_tool_calls(message.tool_calls)
+              }.compact
+            end
+          end
+
+          def openai_content(content)
+            return content.format if content.is_a?(Legion::Extensions::Llm::Content::Raw)
+            return content unless content.respond_to?(:attachments)
+            return content.text.to_s if content.attachments.empty?
+
+            openai_content_parts(content)
+          end
+
+          def openai_content_parts(content)
+            parts = []
+            parts << { type: 'text', text: content.text.to_s } if content.text
+            content.attachments.each do |attachment|
+              parts << { type: 'image_url', image_url: { url: attachment.for_llm } } if attachment.image?
+            end
+            parts
+          end
+
+          def format_openai_tool_calls(tool_calls)
+            return nil unless tool_calls&.any?
+
+            tool_calls.values.map do |tool_call|
+              {
+                id: tool_call.id,
+                type: 'function',
+                function: {
+                  name: tool_call.name,
+                  arguments: Legion::JSON.generate(tool_call.arguments || {})
+                }
+              }
+            end
+          end
+
+          def format_openai_tools(tools)
+            return nil if tools.empty?
+
+            tools.values.map do |tool|
+              {
+                type: 'function',
+                function: {
+                  name: tool.name,
+                  description: tool.description,
+                  parameters: tool.params_schema || { type: 'object', properties: {} }
+                }
+              }
+            end
+          end
+
+          def openai_tool_choice(tool_prefs)
+            choice = tool_prefs && (tool_prefs[:choice] || tool_prefs['choice'])
+            return nil unless choice
+            return choice.to_s if %i[auto none required].include?(choice.to_sym)
+
+            { type: 'function', function: { name: choice.to_s } }
+          end
+
+          def openai_response_format(schema)
+            return nil unless schema
+
+            schema_hash = schema.respond_to?(:to_h) ? schema.to_h : schema
+            { type: 'json_schema', json_schema: schema_hash }
+          end
+
+          def openai_reasoning_effort(thinking)
+            return nil unless thinking.is_a?(Hash)
+
+            thinking[:effort] || thinking['effort']
+          end
+
+          def parse_completion_response(response)
+            body = response.body
+            choice = Array(body['choices']).first || {}
+            message = choice['message'] || {}
+            usage = body['usage'] || {}
+
+            Legion::Extensions::Llm::Message.new(
+              role: :assistant,
+              content: message['content'],
+              model_id: body['model'],
+              tool_calls: parse_tool_calls(message['tool_calls']),
+              input_tokens: usage['prompt_tokens'],
+              output_tokens: usage['completion_tokens'],
+              reasoning_tokens: usage.dig('completion_tokens_details', 'reasoning_tokens'),
+              raw: body
+            )
+          end
+
+          def build_chunk(data)
+            choice = Array(data['choices']).first || {}
+            delta = choice['delta'] || {}
+            usage = data['usage'] || {}
+
+            Legion::Extensions::Llm::Chunk.new(
+              role: :assistant,
+              content: delta['content'],
+              model_id: data['model'],
+              tool_calls: parse_tool_calls(delta['tool_calls']),
+              input_tokens: usage['prompt_tokens'],
+              output_tokens: usage['completion_tokens'],
+              raw: data
+            )
+          end
+
+          def parse_tool_calls(tool_calls)
+            return nil unless tool_calls&.any?
+
+            tool_calls.to_h do |call|
+              function = call.fetch('function', {})
+              name = function.fetch('name')
+              [
+                name.to_sym,
+                Legion::Extensions::Llm::ToolCall.new(
+                  id: call['id'] || name,
+                  name: name,
+                  arguments: parse_tool_arguments(function['arguments'])
+                )
+              ]
+            end
+          end
+
+          def parse_tool_arguments(arguments)
+            return {} if arguments.nil? || arguments == ''
+            return arguments if arguments.is_a?(Hash)
+
+            Legion::JSON.parse(arguments, symbolize_names: false)
+          rescue Legion::JSON::ParseError
+            {}
+          end
+
+          def parse_list_models_response(response, provider, capabilities)
+            response.body.fetch('data', []).map do |model|
+              critical_capabilities = critical_capabilities_for(capabilities, model)
+              Legion::Extensions::Llm::Model::Info.new(
+                id: model.fetch('id'),
+                name: model['id'],
+                provider: provider,
+                created_at: model_created_at(model['created']),
+                capabilities: critical_capabilities,
+                modalities: modalities_for_capabilities(critical_capabilities),
+                metadata: model
+              )
+            end
+          end
+
+          def model_created_at(value)
+            value.is_a?(Numeric) ? Time.at(value).utc : value
+          end
+
+          def critical_capabilities_for(capabilities, model)
+            return [] unless capabilities
+            return capabilities.critical_capabilities_for(model) if capabilities.respond_to?(:critical_capabilities_for)
+
+            {
+              'streaming' => :streaming?,
+              'function_calling' => :functions?,
+              'vision' => :vision?,
+              'embeddings' => :embeddings?,
+              'moderation' => :moderation?,
+              'image' => :images?,
+              'audio_transcription' => :audio_transcription?
+            }.filter_map do |capability, predicate|
+              capability if capabilities.respond_to?(predicate) && capabilities.public_send(predicate, model)
+            end
+          end
+
+          def modalities_for_capabilities(capabilities)
+            if capabilities.include?('embeddings') && (capabilities - ['embeddings']).empty?
+              { input: %w[text], output: %w[embeddings] }
+            elsif capabilities.include?('image')
+              { input: %w[text image], output: %w[image] }
+            elsif capabilities.include?('audio_transcription')
+              { input: %w[audio], output: %w[text] }
+            else
+              { input: %w[text image], output: %w[text] }
+            end
+          end
+
+          def render_embedding_payload(text, model:, dimensions:)
+            { model: model, input: text, dimensions: dimensions }.compact
+          end
+
+          def parse_embedding_response(response, model:, text:)
+            vectors = response.body.fetch('data', []).map { |item| item['embedding'] }
+            vectors = vectors.first unless text.is_a?(Array)
+            usage = response.body['usage'] || {}
+
+            Legion::Extensions::Llm::Embedding.new(vectors: vectors, model: model,
+                                                   input_tokens: usage['prompt_tokens'].to_i)
+          end
+
+          def render_moderation_payload(input, model:)
+            { model: model, input: input }.compact
+          end
+
+          def parse_moderation_response(response, model:)
+            Legion::Extensions::Llm::Moderation.new(id: response.body['id'], model: response.body['model'] || model,
+                                                    results: response.body.fetch('results', []))
+          end
+
+          def render_image_payload(prompt, model:, size:, with:, mask:, params:) # rubocop:disable Metrics/ParameterLists
+            { model: model, prompt: prompt, size: size, image: with, mask: mask }.merge(params).compact
+          end
+
+          def parse_image_response(response, model:)
+            image = response.body.fetch('data', []).first || {}
+            Legion::Extensions::Llm::Image.new(
+              url: image['url'],
+              data: image['b64_json'],
+              revised_prompt: image['revised_prompt'],
+              model_id: model,
+              usage: response.body['usage'] || {}
+            )
+          end
+
+          def render_transcription_payload(file_part, model:, language:, **options)
+            { model: model, file: file_part, language: language }.merge(options).compact
+          end
+
+          def parse_transcription_response(response, model:)
+            Legion::Extensions::Llm::Transcription.new(
+              text: response.body['text'],
+              model: model,
+              language: response.body['language'],
+              duration: response.body['duration'],
+              segments: response.body['segments']
+            )
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,337 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Llm
+      # Base class for LLM providers.
+      class Provider
+        include Streaming
+
+        attr_reader :config, :connection
+
+        def initialize(config)
+          @config = config
+          ensure_configured!
+          @connection = Connection.new(self, @config)
+        end
+
+        def api_base
+          raise NotImplementedError
+        end
+
+        def headers
+          {}
+        end
+
+        def slug
+          self.class.slug
+        end
+
+        def name
+          self.class.name
+        end
+
+        def capabilities
+          self.class.capabilities
+        end
+
+        def configuration_requirements
+          self.class.configuration_requirements
+        end
+
+        # rubocop:disable Metrics/ParameterLists
+        def complete(messages, tools:, temperature:, model:, params: {}, headers: {}, schema: nil, thinking: nil,
+                     tool_prefs: nil, &)
+          normalized_temperature = maybe_normalize_temperature(temperature, model)
+
+          payload = Utils.deep_merge(
+            render_payload(
+              messages,
+              tools: tools,
+              tool_prefs: tool_prefs,
+              temperature: normalized_temperature,
+              model: model,
+              stream: block_given?,
+              schema: schema,
+              thinking: thinking
+            ),
+            params
+          )
+
+          if block_given?
+            stream_response @connection, payload, headers, &
+          else
+            sync_response @connection, payload, headers
+          end
+        end
+        # rubocop:enable Metrics/ParameterLists
+
+        def list_models
+          response = @connection.get models_url
+          parse_list_models_response response, slug, capabilities
+        end
+
+        def embed(text, model:, dimensions:)
+          payload = render_embedding_payload(text, model:, dimensions:)
+          response = @connection.post(embedding_url(model:), payload)
+          parse_embedding_response(response, model:, text:)
+        end
+
+        def moderate(input, model:)
+          payload = render_moderation_payload(input, model:)
+          response = @connection.post moderation_url, payload
+          parse_moderation_response(response, model:)
+        end
+
+        def paint(prompt, model:, size:, with: nil, mask: nil, params: {}) # rubocop:disable Metrics/ParameterLists
+          validate_paint_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
+
+        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
+
+        def configured?
+          configuration_requirements.all? { |req| @config.send(req) }
+        end
+
+        def local?
+          self.class.local?
+        end
+
+        def remote?
+          self.class.remote?
+        end
+
+        def assume_models_exist?
+          self.class.assume_models_exist?
+        end
+
+        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? && health_ready?(response.body), health: response.body)
+        rescue StandardError => e
+          metadata.merge(ready: false, health: { error: e.class.name, message: e.message })
+        end
+
+        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
+            next
+          end
+        end
+
+        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('. ')
+          else
+            body
+          end
+        end
+
+        def format_messages(messages)
+          messages.map do |msg|
+            {
+              role: msg.role.to_s,
+              content: msg.content
+            }
+          end
+        end
+
+        def format_tool_calls(_tool_calls)
+          nil
+        end
+
+        def parse_tool_calls(_tool_calls)
+          nil
+        end
+
+        class << self
+          def name
+            to_s.split('::').last
+          end
+
+          def slug
+            name.downcase
+          end
+
+          def capabilities
+            nil
+          end
+
+          def configuration_requirements
+            []
+          end
+
+          def configuration_options
+            []
+          end
+
+          def local?
+            false
+          end
+
+          def remote?
+            !local?
+          end
+
+          def assume_models_exist?
+            false
+          end
+
+          def resolve_model_id(model_id, config: nil) # rubocop:disable Lint/UnusedMethodArgument
+            model_id
+          end
+
+          def configured?(config)
+            configuration_requirements.all? { |req| config.send(req) }
+          end
+
+          def register(name, provider_class)
+            providers[name.to_sym] = provider_class
+            Legion::Extensions::Llm::Configuration.register_provider_options(provider_class.configuration_options)
+          end
+
+          def resolve(name)
+            return nil if name.nil?
+
+            providers[name.to_sym]
+          end
+
+          def for(model)
+            model_info = Models.find(model)
+            resolve model_info.provider
+          end
+
+          def providers
+            @providers ||= {}
+          end
+
+          def local_providers
+            providers.select { |_slug, provider_class| provider_class.local? }
+          end
+
+          def remote_providers
+            providers.select { |_slug, provider_class| provider_class.remote? }
+          end
+
+          def configured_providers(config)
+            providers.select do |_slug, provider_class|
+              provider_class.configured?(config)
+            end.values
+          end
+
+          def configured_remote_providers(config)
+            providers.select do |_slug, provider_class|
+              provider_class.remote? && provider_class.configured?(config)
+            end.values
+          end
+        end
+
+        private
+
+        def validate_paint_inputs!(with:, mask:)
+          return if with.nil? && mask.nil?
+
+          raise UnsupportedAttachmentError, "#{name} does not support image references in paint"
+        end
+
+        def build_audio_file_part(file_path)
+          expanded_path = File.expand_path(file_path)
+          mime_type = Marcel::MimeType.for(Pathname.new(expanded_path))
+
+          Faraday::Multipart::FilePart.new(
+            expanded_path,
+            mime_type,
+            File.basename(expanded_path)
+          )
+        end
+
+        def try_parse_json(maybe_json)
+          return maybe_json unless maybe_json.is_a?(String)
+
+          Legion::JSON.parse(maybe_json, symbolize_names: false)
+        rescue Legion::JSON::ParseError
+          maybe_json
+        end
+
+        def ensure_configured!
+          missing = configuration_requirements.reject { |req| @config.send(req) }
+          return if missing.empty?
+
+          raise ConfigurationError, "Missing configuration for #{name}: #{missing.join(', ')}"
+        end
+
+        def maybe_normalize_temperature(temperature, _model)
+          temperature
+        end
+
+        def endpoint_methods
+          {
+            completion: :completion_url,
+            stream: :stream_url,
+            models: :models_url,
+            embeddings: :embedding_url,
+            moderation: :moderation_url,
+            images: :images_url,
+            transcription: :transcription_url,
+            health: :health_url,
+            version: :version_url
+          }
+        end
+
+        def health_ready?(body)
+          return body unless body.is_a?(Hash)
+
+          status = body['status'] || body[:status] || body['state'] || body[:state]
+          return true if status.nil?
+
+          %w[ok ready healthy running].include?(status.to_s.downcase)
+        end
+
+        def sync_response(connection, payload, additional_headers = {})
+          response = connection.post completion_url, payload do |req|
+            req.headers = additional_headers.merge(req.headers) unless additional_headers.empty?
+          end
+          parse_completion_response response
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/llm/routing/lane_key.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Llm
+      module Routing
+        # Builds stable fleet lane keys from provider-neutral model offerings.
+        module LaneKey
+          module_function
+
+          def for(offering, prefix: 'llm.fleet', include_context: true, include_fingerprint: false)
+            parts = [prefix, lane_kind(offering), model_slug(offering.model)]
+            if include_context && offering.inference? && offering.context_window
+              parts << "ctx#{offering.context_window}"
+            end
+            parts.push('elig', eligibility_fingerprint(offering)) if include_fingerprint
+            parts.join('.')
+          end
+
+          def lane_kind(offering)
+            offering.embedding? ? 'embed' : 'inference'
+          end
+
+          def model_slug(model)
+            model.to_s.downcase.gsub(/[^a-z0-9]+/, '-').gsub(/\A-+|-+\z/, '')
+          end
+
+          def eligibility_fingerprint(offering)
+            canonical = {
+              usage_type: offering.usage_type,
+              capabilities: offering.capabilities.sort,
+              context_window: offering.context_window,
+              max_output_tokens: offering.max_output_tokens,
+              policy_tags: offering.policy_tags.sort,
+              metadata: fingerprint_metadata(offering.metadata)
+            }
+            Digest::SHA1.hexdigest(Legion::JSON.generate(canonical))[0, 10]
+          end
+
+          def fingerprint_metadata(metadata)
+            metadata.fetch(:eligibility, {})
+                    .to_h
+                    .transform_keys(&:to_sym)
+                    .reject { |key, _| sensitive_fingerprint_key?(key) }
+                    .sort
+                    .to_h
+          end
+
+          def sensitive_fingerprint_key?(key)
+            %i[credential credentials endpoint endpoint_url identity path prompt reply_to secret secrets token
+               url].include?(key)
+          end
+        end
+      end
+    end
+  end
+end