lex-llm 0.1.2 → 0.1.4

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

@@ -0,0 +1,229 @@
+# frozen_string_literal: true
+
+require 'pathname'
+require 'uri'
+
+module Legion
+  module Extensions
+    module Llm
+      # A class representing a file attachment.
+      class Attachment
+        attr_reader :source, :filename, :mime_type
+
+        def initialize(source, filename: nil)
+          @source = source
+          @source = source_type_cast
+          @filename = filename || source_filename
+
+          determine_mime_type
+        end
+
+        def url?
+          @source.is_a?(URI) || (@source.is_a?(String) && @source.match?(%r{^https?://}))
+        end
+
+        def path?
+          @source.is_a?(Pathname) || (@source.is_a?(String) && !url?)
+        end
+
+        def io_like?
+          @source.respond_to?(:read) && !path? && !active_storage?
+        end
+
+        def active_storage?
+          return false unless defined?(ActiveStorage)
+
+          @source.is_a?(ActiveStorage::Blob) ||
+            @source.is_a?(ActiveStorage::Attached::One) ||
+            @source.is_a?(ActiveStorage::Attached::Many)
+        end
+
+        def content
+          return @content if defined?(@content) && !@content.nil?
+
+          if url?
+            fetch_content
+          elsif path?
+            load_content_from_path
+          elsif active_storage?
+            load_content_from_active_storage
+          elsif io_like?
+            load_content_from_io
+          else
+            Legion::Extensions::Llm.logger.warn(
+              "Source is neither a URL, path, ActiveStorage, nor IO-like: #{@source.class}"
+            )
+            nil
+          end
+
+          @content
+        end
+
+        def encoded
+          Base64.strict_encode64(content)
+        end
+
+        def save(path)
+          return unless io_like?
+
+          File.open(path, 'w') do |f|
+            f.puts(@source.read)
+          end
+        end
+
+        def for_llm
+          case type
+          when :text
+            "<file name='#{filename}' mime_type='#{mime_type}'>#{content}</file>"
+          else
+            "data:#{mime_type};base64,#{encoded}"
+          end
+        end
+
+        def type
+          return :image if image?
+          return :video if video?
+          return :audio if audio?
+          return :pdf if pdf?
+          return :text if text?
+
+          :unknown
+        end
+
+        def image?
+          Legion::Extensions::Llm::MimeType.image? mime_type
+        end
+
+        def video?
+          Legion::Extensions::Llm::MimeType.video? mime_type
+        end
+
+        def audio?
+          Legion::Extensions::Llm::MimeType.audio? mime_type
+        end
+
+        def format
+          case mime_type
+          when 'audio/mpeg'
+            'mp3'
+          when 'audio/wav', 'audio/wave', 'audio/x-wav'
+            'wav'
+          else
+            mime_type.split('/').last
+          end
+        end
+
+        def pdf?
+          Legion::Extensions::Llm::MimeType.pdf? mime_type
+        end
+
+        def text?
+          Legion::Extensions::Llm::MimeType.text? mime_type
+        end
+
+        def to_h
+          { type: type, source: @source }
+        end
+
+        private
+
+        def determine_mime_type
+          return @mime_type = active_storage_content_type if active_storage? && active_storage_content_type.present?
+
+          @mime_type = Legion::Extensions::Llm::MimeType.for(url? ? nil : @source, name: @filename)
+          @mime_type = Legion::Extensions::Llm::MimeType.for(content) if @mime_type == 'application/octet-stream'
+          @mime_type = 'audio/wav' if @mime_type == 'audio/x-wav' # Normalize WAV type
+        end
+
+        def fetch_content
+          response = Connection.basic.get @source.to_s
+          @content = response.body
+        end
+
+        def load_content_from_path
+          @content = File.binread(@source)
+        end
+
+        def load_content_from_io
+          @source.rewind if @source.respond_to? :rewind
+          @content = @source.read
+        end
+
+        def load_content_from_active_storage
+          return unless defined?(ActiveStorage)
+
+          @content = case @source
+                     when ActiveStorage::Blob
+                       @source.download
+                     when ActiveStorage::Attached::One
+                       @source.blob&.download
+                     when ActiveStorage::Attached::Many
+                       # For multiple attachments, just take the first one
+                       # This maintains the single-attachment interface
+                       @source.blobs.first&.download
+                     end
+        end
+
+        def source_type_cast
+          if url?
+            URI(@source)
+          elsif path?
+            Pathname.new(@source)
+          else
+            @source
+          end
+        end
+
+        def source_filename
+          if url?
+            File.basename(@source.path).to_s
+          elsif path?
+            @source.basename.to_s
+          elsif io_like?
+            extract_filename_from_io
+          elsif active_storage?
+            extract_filename_from_active_storage
+          end
+        end
+
+        def extract_filename_from_io
+          if defined?(ActionDispatch::Http::UploadedFile) && @source.is_a?(ActionDispatch::Http::UploadedFile)
+            @source.original_filename.to_s
+          elsif @source.respond_to?(:path)
+            File.basename(@source.path).to_s
+          else
+            'attachment'
+          end
+        end
+
+        def extract_filename_from_active_storage # rubocop:disable Metrics/PerceivedComplexity
+          return 'attachment' unless defined?(ActiveStorage)
+
+          case @source
+          when ActiveStorage::Blob
+            @source.filename.to_s
+          when ActiveStorage::Attached::One
+            @source.blob&.filename&.to_s || 'attachment'
+          when ActiveStorage::Attached::Many
+            @source.blobs.first&.filename&.to_s || 'attachment'
+          else
+            'attachment'
+          end
+        end
+
+        def active_storage_content_type
+          return unless defined?(ActiveStorage)
+
+          case @source
+          when ActiveStorage::Blob
+            @source.content_type
+          when ActiveStorage::Attached::One
+            @source.blob&.content_type
+          when ActiveStorage::Attached::Many
+            @source.blobs.first&.content_type
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,355 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Llm
+      # 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 || Legion::Extensions::Llm.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 = Legion::Extensions::Llm::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)
+          Legion::Extensions::Llm::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
+  end
+end

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

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Llm
+      class Chunk < Message
+      end
+    end
+  end
+end

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

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Llm
+      # Global configuration for Legion::Extensions::Llm
+      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 :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['LEGION_LLM_DEBUG'] ? Logger::DEBUG : Logger::INFO }
+        option :log_stream_debug, -> { ENV['LEGION_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
+            Legion::Extensions::Llm.logger.warn("log_regexp_timeout is not supported on Ruby #{RUBY_VERSION}")
+            @log_regexp_timeout = value
+          end
+        end
+      end
+    end
+  end
+end