lex-llm 0.1.2 → 0.1.3

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

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Llm
+      # Connection class for managing API connections to various providers.
+      class Connection
+        attr_reader :provider, :connection, :config
+
+        def self.basic(&)
+          Faraday.new do |f|
+            f.response :logger,
+                       Legion::Extensions::Llm.logger,
+                       bodies: false,
+                       errors: true,
+                       headers: false,
+                       log_level: :debug
+            f.response :raise_error
+            yield f if block_given?
+          end
+        end
+
+        def initialize(provider, config)
+          @provider = provider
+          @config = config
+
+          ensure_configured!
+          @connection ||= Faraday.new(provider.api_base) do |faraday|
+            setup_timeout(faraday)
+            setup_logging(faraday)
+            setup_retry(faraday)
+            setup_middleware(faraday)
+            setup_http_proxy(faraday)
+          end
+        end
+
+        def post(url, payload, &)
+          @connection.post url, payload do |req|
+            req.headers.merge! @provider.headers if @provider.respond_to?(:headers)
+            yield req if block_given?
+          end
+        end
+
+        def get(url, &)
+          @connection.get url do |req|
+            req.headers.merge! @provider.headers if @provider.respond_to?(:headers)
+            yield req if block_given?
+          end
+        end
+
+        def instance_variables
+          super - %i[@config @connection]
+        end
+
+        private
+
+        def setup_timeout(faraday)
+          faraday.options.timeout = @config.request_timeout
+        end
+
+        def setup_logging(faraday)
+          faraday.response :logger,
+                           Legion::Extensions::Llm.logger,
+                           bodies: Legion::Extensions::Llm.logger.debug?,
+                           errors: true,
+                           headers: false,
+                           log_level: :debug do |logger|
+            logger.filter(logging_regexp('[A-Za-z0-9+/=]{100,}'), '[BASE64 DATA]')
+            logger.filter(logging_regexp('[-\\d.e,\\s]{100,}'), '[EMBEDDINGS ARRAY]')
+          end
+        end
+
+        def logging_regexp(pattern)
+          return Regexp.new(pattern) if @config.log_regexp_timeout.nil? || !Regexp.respond_to?(:timeout)
+
+          Regexp.new(pattern, timeout: @config.log_regexp_timeout)
+        end
+
+        def setup_retry(faraday)
+          faraday.request :retry, {
+            max: @config.max_retries,
+            interval: @config.retry_interval,
+            interval_randomness: @config.retry_interval_randomness,
+            backoff_factor: @config.retry_backoff_factor,
+            methods: Faraday::Retry::Middleware::IDEMPOTENT_METHODS + [:post],
+            exceptions: retry_exceptions
+          }
+        end
+
+        def setup_middleware(faraday)
+          faraday.request :multipart
+          faraday.request :json
+          faraday.response :json
+          faraday.adapter :net_http
+          faraday.use :llm_errors, provider: @provider
+        end
+
+        def setup_http_proxy(faraday)
+          return unless @config.http_proxy
+
+          faraday.proxy = @config.http_proxy
+        end
+
+        def retry_exceptions
+          [
+            Errno::ETIMEDOUT,
+            Timeout::Error,
+            Faraday::TimeoutError,
+            Faraday::ConnectionFailed,
+            Faraday::RetriableResponse,
+            Legion::Extensions::Llm::RateLimitError,
+            Legion::Extensions::Llm::ServerError,
+            Legion::Extensions::Llm::ServiceUnavailableError,
+            Legion::Extensions::Llm::OverloadedError
+          ]
+        end
+
+        def ensure_configured!
+          return if @provider.configured?
+
+          missing = @provider.configuration_requirements.reject { |req| @config.send(req) }
+          config_block = <<~RUBY
+            Legion::Extensions::Llm.configure do |config|
+              #{missing.map { |key| "config.#{key} = ENV['#{key.to_s.upcase}']" }.join("\n  ")}
+            end
+          RUBY
+
+          raise ConfigurationError,
+                "#{@provider.name} provider is not configured. Add this to your initialization:\n\n#{config_block}"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Llm
+      # Represents the content sent to or received from an LLM.
+      class Content
+        attr_reader :text, :attachments
+
+        def initialize(text = nil, attachments = nil)
+          @text = text
+          @attachments = []
+
+          process_attachments(attachments)
+          raise ArgumentError, 'Text and attachments cannot be both nil' if @text.nil? && @attachments.empty?
+        end
+
+        def add_attachment(source, filename: nil)
+          @attachments << Attachment.new(source, filename:)
+          self
+        end
+
+        def format
+          if @text && @attachments.empty?
+            @text
+          else
+            self
+          end
+        end
+
+        # Allows serializers to store the text payload without custom adapters.
+        def to_h
+          { text: @text, attachments: @attachments.map(&:to_h) }
+        end
+
+        private
+
+        def process_attachments_array_or_string(attachments)
+          Utils.to_safe_array(attachments).each do |file|
+            next if blank_attachment_entry?(file)
+
+            add_attachment(file)
+          end
+        end
+
+        def blank_attachment_entry?(file)
+          file.nil? || (file.is_a?(String) && file.strip.empty?)
+        end
+
+        def process_attachments(attachments)
+          if attachments.is_a?(Hash)
+            attachments.each_value { |attachment| process_attachments_array_or_string(attachment) }
+          else
+            process_attachments_array_or_string attachments
+          end
+        end
+      end
+
+      class Content
+        # Represents provider-specific payloads that should bypass Legion::Extensions::Llm formatting.
+        class Raw
+          attr_reader :value
+
+          def initialize(value)
+            raise ArgumentError, 'Raw content payload cannot be nil' if value.nil?
+
+            @value = value
+          end
+
+          def format
+            @value
+          end
+
+          def to_h
+            @value
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Llm
+      # Holds per-call configs
+      class Context
+        attr_reader :config
+
+        def initialize(config)
+          @config = config
+          @connections = {}
+        end
+
+        def chat(*, **, &)
+          Chat.new(*, **, context: self, &)
+        end
+
+        def embed(*, **, &)
+          Embedding.embed(*, **, context: self, &)
+        end
+
+        def paint(*, **, &)
+          Image.paint(*, **, context: self, &)
+        end
+
+        def connection_for(provider_instance)
+          provider_instance.connection
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,33 @@
+# 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/error.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Llm
+      # Custom error class that wraps API errors from different providers
+      # into a consistent format with helpful error messages.
+      class Error < StandardError
+        attr_reader :response
+
+        def initialize(response = nil, message = nil)
+          if response.is_a?(String)
+            message = response
+            response = nil
+          end
+
+          @response = response
+          super(message || response&.body)
+        end
+      end
+
+      # Error classes for non-HTTP errors
+      class ConfigurationError < StandardError; end
+      class PromptNotFoundError < StandardError; end
+      class InvalidRoleError < StandardError; end
+      class InvalidToolChoiceError < StandardError; end
+      class ModelNotFoundError < StandardError; end
+      class UnsupportedAttachmentError < StandardError; end
+
+      # Error classes for different HTTP status codes
+      class BadRequestError < Error; end
+      class ForbiddenError < Error; end
+      class ContextLengthExceededError < Error; end
+      class OverloadedError < Error; end
+      class PaymentRequiredError < Error; end
+      class RateLimitError < Error; end
+      class ServerError < Error; end
+      class ServiceUnavailableError < Error; end
+      class UnauthorizedError < Error; end
+
+      # Faraday middleware that maps provider-specific API errors to Legion::Extensions::Llm errors.
+      class ErrorMiddleware < Faraday::Middleware
+        def initialize(app, options = {})
+          super(app)
+          @provider = options[:provider]
+        end
+
+        def call(env)
+          @app.call(env).on_complete do |response|
+            self.class.parse_error(provider: @provider, response: response)
+          end
+        end
+
+        class << self
+          CONTEXT_LENGTH_PATTERNS = [
+            /context length/i,
+            /context window/i,
+            /maximum context/i,
+            /request too large/i,
+            /too many tokens/i,
+            /token count exceeds/i,
+            /input[_\s-]?token/i,
+            /input or output tokens? must be reduced/i,
+            /reduce the length of messages/i
+          ].freeze
+
+          def parse_error(provider:, response:) # rubocop:disable Metrics/PerceivedComplexity
+            message = provider&.parse_error(response)
+
+            case response.status
+            when 200..399
+              message
+            when 400
+              if context_length_exceeded?(message)
+                raise ContextLengthExceededError.new(response, message || 'Context length exceeded')
+              end
+
+              raise BadRequestError.new(response, message || 'Invalid request - please check your input')
+            when 401
+              raise UnauthorizedError.new(response, message || 'Invalid API key - check your credentials')
+            when 402
+              raise PaymentRequiredError.new(response, message || 'Payment required - please top up your account')
+            when 403
+              raise ForbiddenError.new(response,
+                                       message || 'Forbidden - you do not have permission to access this resource')
+            when 429
+              if context_length_exceeded?(message)
+                raise ContextLengthExceededError.new(response, message || 'Context length exceeded')
+              end
+
+              raise RateLimitError.new(response, message || 'Rate limit exceeded - please wait a moment')
+            when 500
+              raise ServerError.new(response, message || 'API server error - please try again')
+            when 502..504
+              raise ServiceUnavailableError.new(response, message || 'API server unavailable - please try again later')
+            when 529
+              raise OverloadedError.new(response, message || 'Service overloaded - please try again later')
+            else
+              raise Error.new(response, message || 'An unknown error occurred')
+            end
+          end
+
+          private
+
+          def context_length_exceeded?(message)
+            return false if message.to_s.empty?
+
+            CONTEXT_LENGTH_PATTERNS.any? { |pattern| message.match?(pattern) }
+          end
+        end
+      end
+    end
+  end
+end
+
+Faraday::Middleware.register_middleware(llm_errors: Legion::Extensions::Llm::ErrorMiddleware)

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

@@ -0,0 +1,109 @@
+# 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/message.rb

@@ -0,0 +1,111 @@
+# 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
+        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]
+
+          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,
+            thinking: thinking&.text,
+            thinking_signature: thinking&.signature
+          }.merge(tokens ? tokens.to_h : {}).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

@@ -0,0 +1,75 @@
+# 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