lex-llm 0.1.1

data/lib/lex_llm/chat.rb

@@ -0,0 +1,351 @@
+# frozen_string_literal: true
+
+module LexLLM
+  # Represents a conversation with an AI model
+  class Chat
+    include Enumerable
+
+    attr_reader :model, :messages, :tools, :tool_prefs, :params, :headers, :schema
+
+    def initialize(model: nil, provider: nil, assume_model_exists: false, context: nil)
+      if assume_model_exists && !provider
+        raise ArgumentError, 'Provider must be specified if assume_model_exists is true'
+      end
+
+      @context = context
+      @config = context&.config || LexLLM.config
+      model_id = model || @config.default_model
+      with_model(model_id, provider: provider, assume_exists: assume_model_exists)
+      @temperature = nil
+      @messages = []
+      @tools = {}
+      @tool_prefs = { choice: nil, calls: nil }
+      @params = {}
+      @headers = {}
+      @schema = nil
+      @thinking = nil
+      @on = {
+        new_message: nil,
+        end_message: nil,
+        tool_call: nil,
+        tool_result: nil
+      }
+    end
+
+    def ask(message = nil, with: nil, &)
+      add_message role: :user, content: build_content(message, with)
+      complete(&)
+    end
+
+    alias say ask
+
+    def with_instructions(instructions, append: false, replace: nil)
+      append ||= (replace == false) unless replace.nil?
+
+      if append
+        append_system_instruction(instructions)
+      else
+        replace_system_instruction(instructions)
+      end
+
+      self
+    end
+
+    def with_tool(tool, choice: nil, calls: nil)
+      unless tool.nil?
+        tool_instance = tool.is_a?(Class) ? tool.new : tool
+        @tools[tool_instance.name.to_sym] = tool_instance
+      end
+      update_tool_options(choice:, calls:)
+      self
+    end
+
+    def with_tools(*tools, replace: false, choice: nil, calls: nil)
+      @tools.clear if replace
+      tools.compact.each { |tool| with_tool tool }
+      update_tool_options(choice:, calls:)
+      self
+    end
+
+    def with_model(model_id, provider: nil, assume_exists: false)
+      @model, @provider = Models.resolve(model_id, provider:, assume_exists:, config: @config)
+      @connection = @provider.connection
+      self
+    end
+
+    def with_temperature(temperature)
+      @temperature = temperature
+      self
+    end
+
+    def with_thinking(effort: nil, budget: nil)
+      raise ArgumentError, 'with_thinking requires :effort or :budget' if effort.nil? && budget.nil?
+
+      @thinking = Thinking::Config.new(effort: effort, budget: budget)
+      self
+    end
+
+    def with_context(context)
+      @context = context
+      @config = context.config
+      with_model(@model.id, provider: @provider.slug, assume_exists: true)
+      self
+    end
+
+    def with_params(**params)
+      @params = params
+      self
+    end
+
+    def with_headers(**headers)
+      @headers = headers
+      self
+    end
+
+    def with_schema(schema)
+      schema_instance = schema.is_a?(Class) ? schema.new : schema
+
+      @schema = normalize_schema_payload(
+        schema_instance.respond_to?(:to_json_schema) ? schema_instance.to_json_schema : schema_instance
+      )
+
+      self
+    end
+
+    def on_new_message(&block)
+      @on[:new_message] = block
+      self
+    end
+
+    def on_end_message(&block)
+      @on[:end_message] = block
+      self
+    end
+
+    def on_tool_call(&block)
+      @on[:tool_call] = block
+      self
+    end
+
+    def on_tool_result(&block)
+      @on[:tool_result] = block
+      self
+    end
+
+    def each(&)
+      messages.each(&)
+    end
+
+    def complete(&) # rubocop:disable Metrics/PerceivedComplexity
+      response = @provider.complete(
+        messages,
+        tools: @tools,
+        tool_prefs: @tool_prefs,
+        temperature: @temperature,
+        model: @model,
+        params: @params,
+        headers: @headers,
+        schema: @schema,
+        thinking: @thinking,
+        &wrap_streaming_block(&)
+      )
+
+      @on[:new_message]&.call unless block_given?
+
+      if @schema && response.content.is_a?(String) && !response.tool_call?
+        begin
+          response.content = Legion::JSON.parse(response.content, symbolize_names: false)
+        rescue Legion::JSON::ParseError
+          # If parsing fails, keep content as string
+        end
+      end
+
+      add_message response
+      @on[:end_message]&.call(response)
+
+      if response.tool_call?
+        handle_tool_calls(response, &)
+      else
+        response
+      end
+    end
+
+    def add_message(message_or_attributes)
+      message = message_or_attributes.is_a?(Message) ? message_or_attributes : Message.new(message_or_attributes)
+      messages << message
+      message
+    end
+
+    def reset_messages!
+      @messages.clear
+    end
+
+    def instance_variables
+      super - %i[@connection @config]
+    end
+
+    private
+
+    def normalize_schema_payload(raw_schema)
+      return nil if raw_schema.nil?
+      return raw_schema unless raw_schema.is_a?(Hash)
+
+      schema = LexLLM::Utils.deep_symbolize_keys(raw_schema)
+      schema_def = extract_schema_definition(schema)
+      strict = extract_schema_strict(schema, schema_def)
+      build_schema_payload(schema, schema_def, strict)
+    end
+
+    def extract_schema_definition(schema)
+      LexLLM::Utils.deep_dup(schema[:schema] || schema)
+    end
+
+    def extract_schema_strict(schema, schema_def)
+      return schema[:strict] if schema.key?(:strict)
+      return schema_def.delete(:strict) if schema_def.is_a?(Hash)
+
+      nil
+    end
+
+    def build_schema_payload(schema, schema_def, strict)
+      {
+        name: sanitize_schema_name(schema[:name] || 'response'),
+        schema: schema_def,
+        strict: strict.nil? || strict,
+        description: schema[:description]
+      }.compact
+    end
+
+    def sanitize_schema_name(name)
+      sanitized = name.to_s.gsub(/[^a-zA-Z0-9_-]/, '_')
+      sanitized.empty? ? 'response' : sanitized
+    end
+
+    def wrap_streaming_block(&block)
+      return nil unless block_given?
+
+      @on[:new_message]&.call
+
+      proc do |chunk|
+        block.call chunk
+      end
+    end
+
+    def handle_tool_calls(response, &) # rubocop:disable Metrics/PerceivedComplexity
+      halt_result = nil
+
+      response.tool_calls.each_value do |tool_call|
+        @on[:new_message]&.call
+        @on[:tool_call]&.call(tool_call)
+        result = execute_tool tool_call
+        @on[:tool_result]&.call(result)
+        tool_payload = result.is_a?(Tool::Halt) ? result.content : result
+        content = content_like?(tool_payload) ? tool_payload : tool_payload.to_s
+        message = add_message role: :tool, content:, tool_call_id: tool_call.id
+        @on[:end_message]&.call(message)
+
+        halt_result = result if result.is_a?(Tool::Halt)
+      end
+
+      reset_tool_choice if forced_tool_choice?
+      halt_result || complete(&)
+    end
+
+    def execute_tool(tool_call)
+      tool = tools[tool_call.name.to_sym]
+      if tool.nil?
+        return {
+          error: "Model tried to call unavailable tool `#{tool_call.name}`. " \
+                 "Available tools: #{tools.keys.to_json}."
+        }
+      end
+
+      args = tool_call.arguments
+      tool.call(args)
+    end
+
+    def update_tool_options(choice:, calls:)
+      unless choice.nil?
+        normalized_choice = normalize_tool_choice(choice)
+        valid_tool_choices = %i[auto none required] + tools.keys
+        unless valid_tool_choices.include?(normalized_choice)
+          raise InvalidToolChoiceError,
+                "Invalid tool choice: #{choice}. Valid choices are: #{valid_tool_choices.join(', ')}"
+        end
+
+        @tool_prefs[:choice] = normalized_choice
+      end
+
+      @tool_prefs[:calls] = normalize_calls(calls) unless calls.nil?
+    end
+
+    def normalize_calls(calls)
+      case calls
+      when :many, 'many'
+        :many
+      when :one, 'one', 1
+        :one
+      else
+        raise ArgumentError, "Invalid calls value: #{calls.inspect}. Valid values are: :many, :one, or 1"
+      end
+    end
+
+    def normalize_tool_choice(choice)
+      return choice.to_sym if choice.is_a?(String) || choice.is_a?(Symbol)
+      return tool_name_for_choice_class(choice) if choice.is_a?(Class)
+
+      choice.respond_to?(:name) ? choice.name.to_sym : choice.to_sym
+    end
+
+    def tool_name_for_choice_class(tool_class)
+      matched_tool_name = tools.find { |_name, tool| tool.is_a?(tool_class) }&.first
+      return matched_tool_name if matched_tool_name
+
+      classify_tool_name(tool_class.name)
+    end
+
+    def classify_tool_name(class_name)
+      class_name.split('::').last
+                .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+                .downcase
+                .to_sym
+    end
+
+    def forced_tool_choice?
+      @tool_prefs[:choice] && !%i[auto none].include?(@tool_prefs[:choice])
+    end
+
+    def reset_tool_choice
+      @tool_prefs[:choice] = nil
+    end
+
+    def build_content(message, attachments)
+      return message if content_like?(message)
+
+      Content.new(message, attachments)
+    end
+
+    def content_like?(object)
+      object.is_a?(Content) || object.is_a?(Content::Raw)
+    end
+
+    def append_system_instruction(instructions)
+      system_messages, non_system_messages = @messages.partition { |msg| msg.role == :system }
+      system_messages << Message.new(role: :system, content: instructions)
+      @messages = system_messages + non_system_messages
+    end
+
+    def replace_system_instruction(instructions)
+      system_messages, non_system_messages = @messages.partition { |msg| msg.role == :system }
+
+      if system_messages.empty?
+        system_messages = [Message.new(role: :system, content: instructions)]
+      else
+        system_messages.first.content = instructions
+        system_messages = [system_messages.first]
+      end
+
+      @messages = system_messages + non_system_messages
+    end
+  end
+end

data/lib/lex_llm/chunk.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module LexLLM
+  class Chunk < Message
+  end
+end

data/lib/lex_llm/configuration.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module LexLLM
+  # Global configuration for LexLLM
+  class Configuration
+    class << self
+      # Declare a single configuration option.
+      def option(key, default = nil)
+        key = key.to_sym
+        return if options.include?(key)
+
+        send(:attr_accessor, key)
+        option_keys << key
+        defaults[key] = default
+      end
+
+      def register_provider_options(options)
+        Array(options).each { |key| option(key, nil) }
+      end
+
+      def options
+        option_keys.dup
+      end
+
+      private
+
+      def option_keys = @option_keys ||= []
+      def defaults = @defaults ||= {}
+      private :option
+    end
+
+    # System-level options are declared here.
+    # Provider-specific options are declared in each provider class via
+    # `self.configuration_options` and registered through Provider.register.
+    option :default_model, nil
+    option :default_embedding_model, nil
+    option :default_moderation_model, nil
+    option :default_image_model, nil
+    option :default_transcription_model, nil
+
+    option :model_registry_file, -> { File.expand_path('models.json', __dir__) }
+    option :model_registry_class, 'Model'
+
+    option :use_new_acts_as, false
+
+    option :request_timeout, 300
+    option :max_retries, 3
+    option :retry_interval, 0.1
+    option :retry_backoff_factor, 2
+    option :retry_interval_randomness, 0.5
+    option :http_proxy, nil
+
+    option :logger, nil
+    option :log_file, -> { $stdout }
+    option :log_level, -> { ENV['LEX_LLM_DEBUG'] ? Logger::DEBUG : Logger::INFO }
+    option :log_stream_debug, -> { ENV['LEX_LLM_STREAM_DEBUG'] == 'true' }
+    option :log_regexp_timeout, -> { Regexp.respond_to?(:timeout) ? (Regexp.timeout || 1.0) : nil }
+
+    def initialize
+      self.class.send(:defaults).each do |key, default|
+        value = default.respond_to?(:call) ? instance_exec(&default) : default
+        public_send("#{key}=", value)
+      end
+    end
+
+    def instance_variables
+      super.reject { |ivar| ivar.to_s.match?(/_id|_key|_secret|_token$/) }
+    end
+
+    def log_regexp_timeout=(value)
+      if value.nil?
+        @log_regexp_timeout = nil
+      elsif Regexp.respond_to?(:timeout)
+        @log_regexp_timeout = value
+      else
+        LexLLM.logger.warn("log_regexp_timeout is not supported on Ruby #{RUBY_VERSION}")
+        @log_regexp_timeout = value
+      end
+    end
+  end
+end

data/lib/lex_llm/connection.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module LexLLM
+  # 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,
+                   LexLLM.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,
+                       LexLLM.logger,
+                       bodies: LexLLM.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,
+        LexLLM::RateLimitError,
+        LexLLM::ServerError,
+        LexLLM::ServiceUnavailableError,
+        LexLLM::OverloadedError
+      ]
+    end
+
+    def ensure_configured!
+      return if @provider.configured?
+
+      missing = @provider.configuration_requirements.reject { |req| @config.send(req) }
+      config_block = <<~RUBY
+        LexLLM.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

data/lib/lex_llm/content.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module LexLLM
+  # 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
+
+    # For Rails serialization
+    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 LexLLM 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

data/lib/lex_llm/context.rb

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

data/lib/lex_llm/embedding.rb

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