lex-llm 0.1.1

data/lib/lex_llm/error.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module LexLLM
+  # 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 LexLLM 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
+
+Faraday::Middleware.register_middleware(llm_errors: LexLLM::ErrorMiddleware)

data/lib/lex_llm/image.rb

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

data/lib/lex_llm/message.rb

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

data/lib/lex_llm/mime_type.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require 'marcel'
+
+module LexLLM
+  # 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

data/lib/lex_llm/model/info.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module LexLLM
+  module Model
+    # Information about an AI model's capabilities, pricing, and metadata.
+    class Info
+      attr_reader :id, :name, :provider, :family, :created_at, :context_window, :max_output_tokens, :knowledge_cutoff,
+                  :modalities, :capabilities, :pricing, :metadata
+
+      # Create a default model with assumed capabilities
+      def self.default(model_id, provider)
+        new(
+          id: model_id,
+          name: model_id.tr('-', ' ').capitalize,
+          provider: provider,
+          capabilities: %w[function_calling streaming vision structured_output],
+          modalities: { input: %w[text image], output: %w[text] },
+          metadata: { warning: 'Assuming model exists, capabilities may not be accurate' }
+        )
+      end
+
+      def initialize(data)
+        @id = data[:id]
+        @name = data[:name]
+        @provider = data[:provider]
+        @family = data[:family]
+        @created_at = Utils.to_time(data[:created_at])&.utc
+        @context_window = data[:context_window]
+        @max_output_tokens = data[:max_output_tokens]
+        @knowledge_cutoff = Utils.to_date(data[:knowledge_cutoff])
+        @modalities = Modalities.new(data[:modalities] || {})
+        @capabilities = data[:capabilities] || []
+        @pricing = Pricing.new(data[:pricing] || {})
+        @metadata = data[:metadata] || {}
+      end
+
+      def supports?(capability)
+        capabilities.include?(capability.to_s)
+      end
+
+      %w[function_calling structured_output batch reasoning citations streaming].each do |cap|
+        define_method "#{cap}?" do
+          supports?(cap)
+        end
+      end
+
+      def display_name
+        name
+      end
+
+      def label
+        provider_name = provider_class&.name || provider
+        "#{provider_name} - #{display_name}"
+      end
+
+      def max_tokens
+        max_output_tokens
+      end
+
+      def supports_vision?
+        modalities.input.include?('image')
+      end
+
+      def supports_video?
+        modalities.input.include?('video')
+      end
+
+      def supports_functions?
+        function_calling?
+      end
+
+      def input_price_per_million
+        pricing.text_tokens.input
+      end
+
+      def output_price_per_million
+        pricing.text_tokens.output
+      end
+
+      def provider_class
+        LexLLM::Provider.resolve provider
+      end
+
+      def type
+        output = modalities.output
+        return 'embedding' if output.include?('embeddings')
+        return 'moderation' if output.include?('moderation')
+        return 'image' if output.include?('image')
+        return 'audio' if output.include?('audio')
+        return 'video' if output.include?('video')
+
+        'chat'
+      end
+
+      def to_h
+        {
+          id: id,
+          name: name,
+          provider: provider,
+          family: family,
+          created_at: created_at,
+          context_window: context_window,
+          max_output_tokens: max_output_tokens,
+          knowledge_cutoff: knowledge_cutoff,
+          modalities: modalities.to_h,
+          capabilities: capabilities,
+          pricing: pricing.to_h,
+          metadata: metadata
+        }
+      end
+    end
+  end
+end

data/lib/lex_llm/model/modalities.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module LexLLM
+  module Model
+    # Holds and manages input and output modalities for a language model
+    class Modalities
+      attr_reader :input, :output
+
+      def initialize(data)
+        @input = Array(data[:input]).map(&:to_s)
+        @output = Array(data[:output]).map(&:to_s)
+      end
+
+      def to_h
+        {
+          input: input,
+          output: output
+        }
+      end
+    end
+  end
+end

data/lib/lex_llm/model/pricing.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module LexLLM
+  module Model
+    # A collection that manages and provides access to different categories of pricing information
+    class Pricing
+      def initialize(data)
+        @data = {}
+
+        %i[text_tokens images audio_tokens embeddings].each do |category|
+          @data[category] = PricingCategory.new(data[category]) if data[category] && !empty_pricing?(data[category])
+        end
+      end
+
+      def method_missing(method, *args)
+        if respond_to_missing?(method)
+          @data[method.to_sym] || PricingCategory.new
+        else
+          super
+        end
+      end
+
+      def respond_to_missing?(method, include_private = false)
+        %i[text_tokens images audio_tokens embeddings].include?(method.to_sym) || super
+      end
+
+      def to_h
+        @data.transform_values(&:to_h)
+      end
+
+      private
+
+      def empty_pricing?(data)
+        return true unless data
+
+        %i[standard batch].each do |tier|
+          next unless data[tier]
+
+          data[tier].each_value do |value|
+            return false if value && value != 0.0
+          end
+        end
+
+        true
+      end
+    end
+  end
+end

data/lib/lex_llm/model/pricing_category.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module LexLLM
+  module Model
+    # Represents pricing tiers for different usage categories (standard and batch)
+    class PricingCategory
+      attr_reader :standard, :batch
+
+      def initialize(data = {})
+        @standard = PricingTier.new(data[:standard] || {}) unless empty_tier?(data[:standard])
+        @batch = PricingTier.new(data[:batch] || {}) unless empty_tier?(data[:batch])
+      end
+
+      def input
+        standard&.input_per_million
+      end
+
+      def output
+        standard&.output_per_million
+      end
+
+      def cached_input
+        standard&.cached_input_per_million
+      end
+
+      def [](key)
+        key == :batch ? batch : standard
+      end
+
+      def to_h
+        result = {}
+        result[:standard] = standard.to_h if standard
+        result[:batch] = batch.to_h if batch
+        result
+      end
+
+      private
+
+      def empty_tier?(tier_data)
+        return true unless tier_data
+
+        tier_data.values.all? { |v| v.nil? || v == 0.0 }
+      end
+    end
+  end
+end

data/lib/lex_llm/model/pricing_tier.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module LexLLM
+  module Model
+    # A dynamic class for storing non-zero pricing values with flexible attribute access
+    class PricingTier
+      def initialize(data = {})
+        @values = {}
+
+        data.each do |key, value|
+          @values[key.to_sym] = value if value && value != 0.0
+        end
+      end
+
+      def method_missing(method, *args)
+        if method.to_s.end_with?('=')
+          key = method.to_s.chomp('=').to_sym
+          @values[key] = args.first if args.first && args.first != 0.0
+        elsif @values.key?(method)
+          @values[method]
+        end
+      end
+
+      def respond_to_missing?(method, include_private = false)
+        method.to_s.end_with?('=') || @values.key?(method.to_sym) || super
+      end
+
+      def to_h
+        @values
+      end
+    end
+  end
+end

data/lib/lex_llm/model.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module LexLLM
+  # Model-related classes for working with LLM models
+  module Model
+  end
+end