lex-llm 0.1.1

data/lib/lex_llm/moderation.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module LexLLM
+  # Identify potentially harmful content in text.
+  # https://platform.openai.com/docs/guides/moderation
+  class Moderation
+    attr_reader :id, :model, :results
+
+    def initialize(id:, model:, results:)
+      @id = id
+      @model = model
+      @results = results
+    end
+
+    def self.moderate(input,
+                      model: nil,
+                      provider: nil,
+                      assume_model_exists: false,
+                      context: nil)
+      config = context&.config || LexLLM.config
+      model ||= config.default_moderation_model
+      model, provider_instance = Models.resolve(model, provider: provider, assume_exists: assume_model_exists,
+                                                       config: config)
+      model_id = model.id
+
+      provider_instance.moderate(input, model: model_id)
+    end
+
+    # Convenience method to get content from moderation result
+    def content
+      results
+    end
+
+    # Check if any content was flagged
+    def flagged?
+      results.any? { |result| result['flagged'] }
+    end
+
+    # Get all flagged categories across all results
+    def flagged_categories
+      results.flat_map do |result|
+        result['categories']&.select { |_category, flagged| flagged }&.keys || []
+      end.uniq
+    end
+
+    # Get category scores for the first result (most common case)
+    def category_scores
+      results.first&.dig('category_scores') || {}
+    end
+
+    # Get categories for the first result (most common case)
+    def categories
+      results.first&.dig('categories') || {}
+    end
+  end
+end

data/lib/lex_llm/provider.rb

@@ -0,0 +1,278 @@
+# frozen_string_literal: true
+
+module LexLLM
+  # 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 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
+        LexLLM::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 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

data/lib/lex_llm/railtie.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+if defined?(Rails::Railtie)
+  module LexLLM
+    # Rails integration for LexLLM
+    class Railtie < Rails::Railtie
+      initializer 'lex_llm.inflections' do
+        ActiveSupport::Inflector.inflections(:en) do |inflect|
+          inflect.acronym 'LexLLM'
+        end
+      end
+
+      initializer 'lex_llm.active_record' do
+        ActiveSupport.on_load :active_record do
+          if LexLLM.config.use_new_acts_as
+            require 'lex_llm/active_record/acts_as'
+            ::ActiveRecord::Base.include LexLLM::ActiveRecord::ActsAs
+          else
+            require 'lex_llm/active_record/acts_as_legacy'
+            ::ActiveRecord::Base.include LexLLM::ActiveRecord::ActsAsLegacy
+
+            Rails.logger.warn(
+              "\n!!! LexLLM's legacy acts_as API is deprecated and will be removed in LexLLM 2.0.0. " \
+              "Please consult the migration guide at https://github.com/LegionIO/lex-llm\n"
+            )
+          end
+        end
+      end
+
+      rake_tasks do
+        load 'tasks/lex_llm.rake'
+      end
+    end
+  end
+end

data/lib/lex_llm/routing/lane_key.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module LexLLM
+  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)]
+        parts << "ctx#{offering.context_window}" if include_context && offering.inference? && offering.context_window
+        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

data/lib/lex_llm/routing/model_offering.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+module LexLLM
+  module Routing
+    # Describes one concrete model made available by one provider instance.
+    class ModelOffering
+      attr_reader :provider_family, :instance_id, :transport, :tier, :model, :usage_type, :capabilities, :limits,
+                  :credentials, :health, :cost, :policy_tags, :metadata
+
+      def initialize(data)
+        @provider_family = normalize_symbol(fetch_value(data, :provider_family, fetch_value(data, :provider)))
+        @instance_id = normalize_symbol(fetch_value(data, :instance_id, @provider_family))
+        @transport = normalize_symbol(fetch_value(data, :transport, :http))
+        @tier = normalize_symbol(fetch_value(data, :tier, default_tier))
+        @model = fetch_value(data, :model).to_s
+        @usage_type = normalize_usage_type(fetch_value(data, :usage_type,
+                                                       fetch_value(data, :type) ||
+                                                       fetch_value(data, :kind) ||
+                                                       infer_usage_type(data)))
+        @capabilities = normalize_array(fetch_value(data, :capabilities))
+        @limits = normalize_hash(fetch_value(data, :limits))
+        @credentials = fetch_value(data, :credentials)
+        @health = normalize_hash(fetch_value(data, :health))
+        @cost = normalize_hash(fetch_value(data, :cost))
+        @policy_tags = normalize_array(fetch_value(data, :policy_tags)).map(&:to_sym)
+        @metadata = normalize_hash(fetch_value(data, :metadata))
+      end
+
+      def enabled?
+        !metadata.key?(:enabled) || metadata[:enabled] != false
+      end
+
+      def embedding?
+        usage_type == :embedding
+      end
+
+      def inference?
+        %i[chat inference completion].include?(usage_type)
+      end
+
+      def context_window
+        integer_limit(:context_window) || integer_limit(:max_input_tokens)
+      end
+
+      def max_output_tokens
+        integer_limit(:max_output_tokens)
+      end
+
+      def supports?(capability)
+        capabilities.include?(capability.to_sym)
+      end
+
+      def eligible_for?(usage_type: nil, required_capabilities: [], min_context_window: nil, policy_tags: [])
+        return false unless enabled?
+        return false unless usage_type_matches?(usage_type)
+        return false unless capabilities_match?(required_capabilities)
+        return false unless context_window_matches?(min_context_window)
+        return false unless policy_tags_match?(policy_tags)
+
+        true
+      end
+
+      def lane_key(prefix: 'llm.fleet', include_context: true, include_fingerprint: false)
+        LaneKey.for(self, prefix:, include_context:, include_fingerprint:)
+      end
+
+      def eligibility_fingerprint
+        LaneKey.eligibility_fingerprint(self)
+      end
+
+      def to_h
+        {
+          provider_family: provider_family,
+          instance_id: instance_id,
+          transport: transport,
+          tier: tier,
+          model: model,
+          usage_type: usage_type,
+          capabilities: capabilities,
+          limits: limits,
+          credentials: credentials,
+          health: health,
+          cost: cost,
+          policy_tags: policy_tags,
+          metadata: metadata
+        }
+      end
+
+      private
+
+      def default_tier
+        case @transport
+        when :local
+          :local
+        when :rabbitmq
+          :fleet
+        else
+          :private
+        end
+      end
+
+      def infer_usage_type(data)
+        capabilities = normalize_array(fetch_value(data, :capabilities))
+        return :embedding if capabilities.include?(:embedding) || capabilities.include?(:embed)
+
+        :inference
+      end
+
+      def normalize_usage_type(value)
+        case value.to_sym
+        when :embed, :embeddings
+          :embedding
+        when :completion, :text, :chat
+          :inference
+        else
+          value.to_sym
+        end
+      end
+
+      def normalize_symbol(value)
+        return nil if value.nil?
+
+        value.to_sym
+      end
+
+      def normalize_array(value)
+        Array(value).compact.map(&:to_sym)
+      end
+
+      def normalize_hash(value)
+        (value || {}).to_h.transform_keys(&:to_sym)
+      end
+
+      def fetch_value(hash, key, default = nil)
+        return default unless hash.respond_to?(:key?)
+
+        string_key = key.to_s
+        return hash[string_key] if hash.key?(string_key)
+
+        hash.key?(key) ? hash[key] : default
+      end
+
+      def usage_type_matches?(expected)
+        expected.nil? || normalize_usage_type(expected) == usage_type
+      end
+
+      def capabilities_match?(required)
+        Array(required).all? { |capability| supports?(capability) }
+      end
+
+      def context_window_matches?(minimum)
+        minimum.nil? || (!!context_window && context_window >= minimum.to_i)
+      end
+
+      def policy_tags_match?(required)
+        Array(required).all? { |tag| policy_tags.include?(tag.to_sym) }
+      end
+
+      def integer_limit(key)
+        value = limits[key]
+        return nil if value.nil?
+
+        Integer(value)
+      rescue ArgumentError, TypeError
+        nil
+      end
+    end
+  end
+end

data/lib/lex_llm/routing.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module LexLLM
+  # Provider-neutral routing metadata used by Legion LLM provider gems.
+  module Routing
+  end
+end