lex-llm 0.1.1

data/lib/lex_llm/tool.rb

@@ -0,0 +1,254 @@
+# frozen_string_literal: true
+
+require 'ruby_llm/schema'
+
+module LexLLM
+  # 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
+
+      LexLLM.logger.debug { "Tool #{name} called with: #{normalized_args.inspect}" }
+      result = execute(**normalized_args)
+      LexLLM.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,
+    # LexLLM::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 ||= LexLLM::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 LexLLM::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 = LexLLM::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
+        LexLLM::Utils.deep_dup(schema)
+      end
+    end
+  end
+end

data/lib/lex_llm/tool_call.rb

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

data/lib/lex_llm/transcription.rb

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

data/lib/lex_llm/utils.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module LexLLM
+  # Provides utility functions for data manipulation within the LexLLM 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

data/lib/lex_llm/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module LexLLM
+  VERSION = '0.1.1'
+end

data/lib/lex_llm.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require 'base64'
+require 'digest/sha1'
+require 'event_stream_parser'
+require 'faraday'
+require 'faraday/multipart'
+require 'faraday/retry'
+require 'legion/json'
+require 'logger'
+require 'marcel'
+require 'securerandom'
+require 'date'
+require 'time'
+require 'ruby_llm/schema'
+require 'zeitwerk'
+
+# Shared LegionIO LLM provider framework.
+module LexLLM
+  loader = Zeitwerk::Loader.for_gem
+  loader.inflector.inflect(
+    'UI' => 'UI',
+    'api' => 'API',
+    'llm' => 'LLM',
+    'pdf' => 'PDF',
+    'lex_llm' => 'LexLLM'
+  )
+  loader.ignore("#{__dir__}/tasks")
+  loader.ignore("#{__dir__}/generators")
+  loader.ignore("#{__dir__}/lex_llm.rb")
+  loader.ignore("#{__dir__}/legion")
+  loader.ignore("#{__dir__}/lex_llm/railtie.rb")
+  loader.setup
+
+  Schema = ::RubyLLM::Schema unless const_defined?(:Schema, false)
+
+  class Error < StandardError; 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: 'LexLLM',
+        level: config.log_level
+      )
+    end
+  end
+end
+
+if defined?(Rails::Railtie)
+  require 'lex_llm/railtie'
+  require 'lex_llm/active_record/acts_as'
+end

data/lib/tasks/lex_llm.rake

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+def run_test_queue_rspec
+  workers = ENV.fetch('RSPEC_WORKERS', nil)
+  env = {}
+  env['TEST_QUEUE_WORKERS'] = workers if workers && !workers.empty? && ENV.fetch('TEST_QUEUE_WORKERS', '').empty?
+
+  system(env, 'bundle', 'exec', 'bin/rspec-queue')
+end
+
+namespace :lex_llm do
+  desc 'Load models from models.json into the database'
+  task load_models: :environment do
+    if LexLLM.config.model_registry_class
+      LexLLM.models.load_from_json!
+      model_class = LexLLM.config.model_registry_class.constantize
+      model_class.save_to_database
+      puts "✅ Loaded #{model_class.count} models into database"
+    else
+      puts 'Model registry not configured. Run bin/rails generate lex_llm:install'
+    end
+  end
+end