lex-llm 0.1.2 → 0.1.4

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

@@ -0,0 +1,258 @@
+# frozen_string_literal: true
+
+require 'ruby_llm/schema'
+
+module Legion
+  module Extensions
+    module Llm
+      # Parameter definition for Tool methods.
+      class Parameter
+        attr_reader :name, :type, :description, :required
+
+        def initialize(name, type: 'string', desc: nil, required: true)
+          @name = name
+          @type = type
+          @description = desc
+          @required = required
+        end
+      end
+
+      # Base class for creating tools that AI models can use
+      class Tool
+        # Stops conversation continuation after tool execution
+        class Halt
+          attr_reader :content
+
+          def initialize(content)
+            @content = content
+          end
+
+          def to_s
+            @content.to_s
+          end
+        end
+
+        class << self
+          attr_reader :params_schema_definition
+
+          def description(text = nil)
+            return @description unless text
+
+            @description = text
+          end
+
+          def param(name, **)
+            parameters[name] = Parameter.new(name, **)
+          end
+
+          def parameters
+            @parameters ||= {}
+          end
+
+          def params(schema = nil, &block)
+            @params_schema_definition = SchemaDefinition.new(schema:, block:)
+            self
+          end
+
+          def with_params(**params)
+            @provider_params = params
+            self
+          end
+
+          def provider_params
+            @provider_params ||= {}
+          end
+        end
+
+        def name
+          klass_name = self.class.name
+          normalized = klass_name.to_s.dup.force_encoding('UTF-8').unicode_normalize(:nfkd)
+          normalized.encode('ASCII', replace: '')
+                    .gsub(/[^a-zA-Z0-9_-]/, '-')
+                    .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+                    .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+                    .downcase
+                    .delete_suffix('_tool')
+        end
+
+        def description
+          self.class.description
+        end
+
+        def parameters
+          self.class.parameters
+        end
+
+        def provider_params
+          self.class.provider_params
+        end
+
+        def params_schema
+          return @params_schema if defined?(@params_schema)
+
+          @params_schema = begin
+            definition = self.class.params_schema_definition
+            if definition&.present?
+              definition.json_schema
+            elsif parameters.any?
+              SchemaDefinition.from_parameters(parameters)&.json_schema
+            end
+          end
+        end
+
+        def call(args)
+          normalized_args = normalize_args(args)
+          validation_error = validate_keyword_arguments(normalized_args)
+          return { error: "Invalid tool arguments: #{validation_error}" } if validation_error
+
+          Legion::Extensions::Llm.logger.debug { "Tool #{name} called with: #{normalized_args.inspect}" }
+          result = execute(**normalized_args)
+          Legion::Extensions::Llm.logger.debug { "Tool #{name} returned: #{result.inspect}" }
+          result
+        end
+
+        def execute(...)
+          raise NotImplementedError, 'Subclasses must implement #execute'
+        end
+
+        protected
+
+        def halt(message)
+          Halt.new(message)
+        end
+
+        def normalize_args(args)
+          return {} if args.nil?
+          return args.transform_keys(&:to_sym) if args.respond_to?(:transform_keys)
+
+          {}
+        end
+
+        def validate_keyword_arguments(arguments)
+          required_keywords, optional_keywords, accepts_extra_keywords = execute_keyword_signature
+
+          return nil if required_keywords.empty? && optional_keywords.empty?
+
+          argument_keys = arguments.keys
+          missing_keyword = first_missing_keyword(required_keywords, argument_keys)
+          return "missing keyword: #{missing_keyword}" if missing_keyword
+          return nil if accepts_extra_keywords
+
+          allowed_keywords = required_keywords + optional_keywords
+          unknown_keyword = first_unknown_keyword(argument_keys, allowed_keywords)
+          return "unknown keyword: #{unknown_keyword}" if unknown_keyword
+
+          nil
+        end
+
+        def execute_keyword_signature
+          keyword_signature = method(:execute).parameters
+          required_keywords = keyword_signature.filter_map { |kind, name| name if kind == :keyreq }
+          optional_keywords = keyword_signature.filter_map { |kind, name| name if kind == :key }
+          accepts_extra_keywords = keyword_signature.any? { |kind, _| kind == :keyrest }
+
+          [required_keywords, optional_keywords, accepts_extra_keywords]
+        end
+
+        def first_missing_keyword(required_keywords, argument_keys)
+          (required_keywords - argument_keys).first
+        end
+
+        def first_unknown_keyword(argument_keys, allowed_keywords)
+          (argument_keys - allowed_keywords).first
+        end
+
+        # Wraps schema handling for tool parameters, supporting JSON Schema hashes,
+        # Legion::Extensions::Llm::Schema instances/classes, and DSL blocks.
+        class SchemaDefinition
+          def self.from_parameters(parameters)
+            return nil if parameters.nil? || parameters.empty?
+
+            properties = parameters.to_h do |name, param|
+              schema = {
+                type: map_type(param.type),
+                description: param.description
+              }.compact
+
+              schema[:items] = default_items_schema if schema[:type] == 'array'
+
+              [name.to_s, schema]
+            end
+
+            required = parameters.select { |_, param| param.required }.keys.map(&:to_s)
+
+            json_schema = {
+              type: 'object',
+              properties: properties,
+              required: required,
+              additionalProperties: false,
+              strict: true
+            }
+
+            new(schema: json_schema)
+          end
+
+          def self.map_type(type)
+            case type.to_s
+            when 'integer', 'int' then 'integer'
+            when 'number', 'float', 'double' then 'number'
+            when 'boolean' then 'boolean'
+            when 'array' then 'array'
+            when 'object' then 'object'
+            else
+              'string'
+            end
+          end
+
+          def self.default_items_schema
+            { type: 'string' }
+          end
+
+          def initialize(schema: nil, block: nil)
+            @schema = schema
+            @block = block
+          end
+
+          def present?
+            @schema || @block
+          end
+
+          def json_schema
+            @json_schema ||= Legion::Extensions::Llm::Utils.deep_stringify_keys(resolve_schema)
+          end
+
+          private
+
+          def resolve_schema
+            return resolve_direct_schema(@schema) if @schema
+            return build_from_block(&@block) if @block
+
+            nil
+          end
+
+          def resolve_direct_schema(schema)
+            return extract_schema(schema.to_json_schema) if schema.respond_to?(:to_json_schema)
+            return Legion::Extensions::Llm::Utils.deep_dup(schema) if schema.is_a?(Hash)
+            if schema.is_a?(Class) && schema.method_defined?(:to_json_schema)
+              return extract_schema(schema.new.to_json_schema)
+            end
+
+            nil
+          end
+
+          def build_from_block(&)
+            schema_class = Legion::Extensions::Llm::Schema.create(&)
+            extract_schema(schema_class.new.to_json_schema)
+          end
+
+          def extract_schema(schema_hash)
+            return nil unless schema_hash.is_a?(Hash)
+
+            schema = schema_hash[:schema] || schema_hash['schema'] || schema_hash
+            Legion::Extensions::Llm::Utils.deep_dup(schema)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Llm
+      # Represents a function call from an AI model to a Tool.
+      class ToolCall
+        attr_reader :id, :name, :arguments
+        attr_accessor :thought_signature
+
+        def initialize(id:, name:, arguments: {}, thought_signature: nil)
+          @id = id
+          @name = name
+          @arguments = arguments
+          @thought_signature = thought_signature
+        end
+
+        def to_h
+          {
+            id: @id,
+            name: @name,
+            arguments: @arguments,
+            thought_signature: @thought_signature
+          }.compact
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Llm
+      # Represents a transcription of audio content.
+      class Transcription
+        attr_reader :text, :model, :language, :duration, :segments, :input_tokens, :output_tokens
+
+        def initialize(text:, model:, **attributes)
+          @text = text
+          @model = model
+          @language = attributes[:language]
+          @duration = attributes[:duration]
+          @segments = attributes[:segments]
+          @input_tokens = attributes[:input_tokens]
+          @output_tokens = attributes[:output_tokens]
+        end
+
+        def self.transcribe(audio_file, **kwargs)
+          model = kwargs.delete(:model)
+          language = kwargs.delete(:language)
+          provider = kwargs.delete(:provider)
+          assume_model_exists = kwargs.delete(:assume_model_exists) { false }
+          context = kwargs.delete(:context)
+          options = kwargs
+
+          config = context&.config || Legion::Extensions::Llm.config
+          model ||= config.default_transcription_model
+          model, provider_instance = Models.resolve(model, provider: provider, assume_exists: assume_model_exists,
+                                                           config: config)
+          model_id = model.id
+
+          provider_instance.transcribe(audio_file, model: model_id, language:, **options)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Llm
+      # Provides utility functions for data manipulation within the Legion::Extensions::Llm library
+      module Utils
+        module_function
+
+        def hash_get(hash, key)
+          hash[key.to_sym] || hash[key.to_s]
+        end
+
+        def to_safe_array(item)
+          case item
+          when Array
+            item
+          when Hash
+            [item]
+          else
+            Array(item)
+          end
+        end
+
+        def to_time(value)
+          return unless value
+
+          value.is_a?(Time) ? value : Time.parse(value.to_s)
+        end
+
+        def to_date(value)
+          return unless value
+
+          value.is_a?(Date) ? value : Date.parse(value.to_s)
+        end
+
+        def deep_merge(original, overrides)
+          original.merge(overrides) do |_key, original_value, overrides_value|
+            if original_value.is_a?(Hash) && overrides_value.is_a?(Hash)
+              deep_merge(original_value, overrides_value)
+            else
+              overrides_value
+            end
+          end
+        end
+
+        def deep_dup(value)
+          case value
+          when Hash
+            value.each_with_object({}) do |(key, val), duped|
+              duped[deep_dup(key)] = deep_dup(val)
+            end
+          when Array
+            value.map { |item| deep_dup(item) }
+          else
+            begin
+              value.dup
+            rescue TypeError
+              value
+            end
+          end
+        end
+
+        def deep_stringify_keys(value)
+          case value
+          when Hash
+            value.each_with_object({}) do |(key, val), result|
+              result[key.to_s] = deep_stringify_keys(val)
+            end
+          when Array
+            value.map { |item| deep_stringify_keys(item) }
+          when Symbol
+            value.to_s
+          else
+            value
+          end
+        end
+
+        def deep_symbolize_keys(value)
+          case value
+          when Hash
+            value.each_with_object({}) do |(key, val), result|
+              symbolized_key = key.respond_to?(:to_sym) ? key.to_sym : key
+              result[symbolized_key] = deep_symbolize_keys(val)
+            end
+          when Array
+            value.map { |item| deep_symbolize_keys(item) }
+          else
+            value
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Llm
+      VERSION = '0.1.4'
+    end
+  end
+end

data/lib/legion/extensions/llm.rb

@@ -1,23 +1,100 @@
 # frozen_string_literal: true
 
-require 'lex_llm'
-require 'legion/extensions/llm/provider_settings'
-require 'legion/extensions/llm/transport/fleet_lane'
+require 'base64'
+require 'date'
+require 'digest/sha1'
+require 'event_stream_parser'
+require 'faraday'
+require 'faraday/multipart'
+require 'faraday/retry'
+require 'legion/json'
+require 'logger'
+require 'marcel'
+require 'ruby_llm/schema'
+require 'securerandom'
+require 'time'
+require 'zeitwerk'
+require_relative 'llm/version'
 
 module Legion
   module Extensions
     # Legion-native namespace for the shared LLM provider framework.
     module Llm
-      VERSION = LexLLM::VERSION unless const_defined?(:VERSION, false)
+      loader = Zeitwerk::Loader.new
+      loader.tag = 'lex-llm'
+      loader.inflector.inflect(
+        'api' => 'API',
+        'llm' => 'Llm',
+        'open_ai_compatible' => 'OpenAICompatible',
+        'pdf' => 'PDF',
+        'ui' => 'UI'
+      )
+      loader.ignore("#{__dir__}/llm/version.rb")
+      loader.push_dir("#{__dir__}/llm", namespace: self)
+      loader.setup
+
+      Schema = ::RubyLLM::Schema unless const_defined?(:Schema, false)
 
       # Provider-neutral value objects exposed under the Legion extension namespace.
       module Types
-        ModelOffering = LexLLM::Routing::ModelOffering unless const_defined?(:ModelOffering, false)
+        ModelOffering = Routing::ModelOffering unless const_defined?(:ModelOffering, false)
       end
 
       # Shared routing helpers exposed under the Legion extension namespace.
       module Routing
-        LaneKey = LexLLM::Routing::LaneKey unless const_defined?(:LaneKey, false)
+        LaneKey = ::Legion::Extensions::Llm::Routing::LaneKey unless const_defined?(:LaneKey, false)
+      end
+
+      class << self
+        def context
+          context_config = config.dup
+          yield context_config if block_given?
+          Context.new(context_config)
+        end
+
+        def chat(...)
+          Chat.new(...)
+        end
+
+        def embed(...)
+          Embedding.embed(...)
+        end
+
+        def moderate(...)
+          Moderation.moderate(...)
+        end
+
+        def paint(...)
+          Image.paint(...)
+        end
+
+        def transcribe(...)
+          Transcription.transcribe(...)
+        end
+
+        def models
+          Models.instance
+        end
+
+        def providers
+          Provider.providers.values
+        end
+
+        def configure
+          yield config
+        end
+
+        def config
+          @config ||= Configuration.new
+        end
+
+        def logger
+          @logger ||= config.logger || Logger.new(
+            config.log_file,
+            progname: 'Legion::Extensions::Llm',
+            level: config.log_level
+          )
+        end
       end
 
       def self.default_settings
@@ -45,6 +122,8 @@ module Legion
       def self.provider_settings(...)
         ProviderSettings.build(...)
       end
+
+      loader.eager_load
     end
   end
 end