llm.rb 11.3.1 → 12.1.0

data/lib/llm/active_record/acts_as_agent.rb

@@ -17,46 +17,6 @@ module LLM::ActiveRecord
   # class and forwarded to an internal agent subclass.
   module ActsAsAgent
     module ClassMethods
-      def model(model = nil, &block)
-        return agent.model if model.nil? && !block
-        agent.model(model, &block)
-      end
-
-      def tools(*tools, &block)
-        return agent.tools if tools.empty? && !block
-        agent.tools(*tools, &block)
-      end
-
-      def skills(*skills, &block)
-        return agent.skills if skills.empty? && !block
-        agent.skills(*skills, &block)
-      end
-
-      def schema(schema = nil, &block)
-        return agent.schema if schema.nil? && !block
-        agent.schema(schema, &block)
-      end
-
-      def instructions(instructions = nil)
-        return agent.instructions if instructions.nil?
-        agent.instructions(instructions)
-      end
-
-      def concurrency(concurrency = nil)
-        return agent.concurrency if concurrency.nil?
-        agent.concurrency(concurrency)
-      end
-
-      def confirm(*tool_names, &block)
-        return agent.confirm if tool_names.empty? && !block
-        agent.confirm(*tool_names, &block)
-      end
-
-      def tracer(tracer = nil, &block)
-        return agent.tracer if tracer.nil? && !block
-        agent.tracer(tracer, &block)
-      end
-
       def agent
         @agent ||= Class.new(LLM::Agent)
       end
@@ -92,13 +52,15 @@ module LLM::ActiveRecord
     #   Evaluated in the model class after the wrapper is installed, so agent
     #   DSL methods such as `model`, `tools`, `schema`, `instructions`, and
     #   `concurrency` can be configured inline.
+    # @yieldparam [LLM::Agent] agent
+    #  Yields an instance of {LLM::Agent LLM::Agent}.
     # @return [void]
     def acts_as_agent(options = EMPTY_HASH, &block)
       options = DEFAULTS.merge(options)
       class_attribute :llm_plugin_options, instance_accessor: false, default: DEFAULTS unless respond_to?(:llm_plugin_options)
       self.llm_plugin_options = options.freeze
       extend Hooks
-      class_exec(&block) if block
+      block_given? ? class_exec(agent, &block) : nil
     end
 
     module InstanceMethods

data/lib/llm/active_record/acts_as_llm.rb

@@ -204,6 +204,24 @@ module LLM::ActiveRecord
 
       private
 
+      ##
+      # @return [LLM::Provider]
+      def set_provider
+        raise NotImplementedError, "implement the set_provider callback"
+      end
+
+      ##
+      # @return [Hash]
+      def set_context
+        EMPTY_HASH.dup
+      end
+
+      ##
+      # @return [LLM::Tracer]
+      def set_tracer
+        nil
+      end
+
       ##
       # @return [LLM::Context]
       def ctx

data/lib/llm/active_record.rb

@@ -5,9 +5,9 @@ module LLM::ActiveRecord
   DEFAULTS = {
     data_column: :data,
     format: :string,
-    tracer: nil,
-    provider: nil,
-    context: EMPTY_HASH
+    provider: :set_provider,
+    context: :set_context,
+    tracer: :set_tracer
   }.freeze
 
   ##

data/lib/llm/agent.rb

@@ -61,7 +61,11 @@ module LLM
     #  Returns the current tools when no argument is provided
     def self.tools(*tools, &block)
       return @tools || [] if tools.empty? && !block
-      @tools = block || tools.flatten
+      if tools.size == 1 and tools.grep(Symbol).any?
+        @tools = tools.first
+      else
+        @tools = block || tools.flatten
+      end
     end
 
     ##
@@ -334,6 +338,15 @@ module LLM
       @tracer || @ctx.tracer
     end
 
+    ##
+    # @param [LLM::Tracer, nil] other
+    #  A tracer, or nil.
+    # @return [void]
+    def tracer=(other)
+      @ctx.tracer = other
+      @tracer = other
+    end
+
     ##
     # @return [LLM::Stream, #<<, nil]
     #  Returns a stream object, or nil
@@ -375,6 +388,17 @@ module LLM
       @ctx.context_window
     end
 
+    ##
+    # Start a minimalist repl that can interact
+    # with the agent and its current state. This
+    # method requires the 'curses' gem to be installed
+    # and available to require.
+    # @return [void]
+    def repl
+      require_relative "repl" unless defined?(::LLM::Repl)
+      LLM::Repl.new(self).start
+    end
+
     ##
     # @see LLM::Context#params
     # @return [Hash]

data/lib/llm/context.rb

@@ -75,19 +75,22 @@ module LLM
     #  The parameters to maintain throughout the conversation.
     #  Any parameter the provider supports can be included and
     #  not only those listed here.
-    # @option params [Symbol] :mode Defaults to :completions
+    # @option params [Symbol] :mode
+    #   Defaults to `:responses` for OpenAI, otherwise it defaults
+    #   to `:completions`.
     # @option params [String] :model Defaults to the provider's default model
     # @option params [Array<LLM::Function>, nil] :tools Defaults to nil
     # @option params [Array<String>, nil] :skills Defaults to nil
     def initialize(llm, params = {})
       @llm = llm
-      @mode = params.delete(:mode) || :completions
+      @mode = params.delete(:mode) || (llm.name == :openai ? :responses : :completions)
       @compactor = params.delete(:compactor)
       @guard = params.delete(:guard)
       @transformer = params.delete(:transformer)
       tools = [*params.delete(:tools), *load_skills(params.delete(:skills))]
       @params = {model: llm.default_model, schema: nil}.compact.merge!(params)
       @params[:tools] = tools unless tools.empty?
+      @params[:store] ||= false if @mode == :responses
       @messages = LLM::Buffer.new(llm)
     end
 
@@ -199,7 +202,7 @@ module LLM
       role = params[:role] || @llm.user_role
       role = @llm.tool_role if params[:role].nil? && [*prompt].grep(LLM::Function::Return).any?
       @messages.concat LLM::Prompt === prompt ? prompt.to_a : [LLM::Message.new(role, prompt)]
-      @messages.concat [res.choices[-1]]
+      @messages.concat [res.choices[-1]].compact
       res
     end
 
@@ -418,6 +421,14 @@ module LLM
       @llm.tracer
     end
 
+    ##
+    # @param [LLM::Tracer, nil] other
+    #  A tracer, or nil.
+    # @return [void]
+    def tracer=(other)
+      @llm.tracer = nil
+    end
+
     ##
     # @return [LLM::Stream, #<<, nil]
     #  Returns a stream object, or nil
@@ -548,7 +559,8 @@ module LLM
       prompt, params = transform(prompt, params)
       bind!(params[:stream], params[:model], params[:tools])
       res_id = params[:store] == false ? nil : @messages.find(&:assistant?)&.response&.response_id
-      params = params.merge(previous_response_id: res_id, input: @messages.to_a).compact
+      input = res_id ? [] : @messages.to_a
+      params = params.merge(previous_response_id: res_id, input:).compact
       [prompt, params, @llm.responses.create(prompt, params)]
     end
 
@@ -597,7 +609,7 @@ module LLM
       [*message.extra.tool_calls].each do |tool|
         next if returns.any? { _1.id == tool[:id] }
         attrs = {cancelled: true, reason: "function call cancelled"}
-        cancelled << LLM::Function::Return.new(tool.id, tool.name, attrs)
+        cancelled << LLM::Function::Return.new(tool[:id], tool[:name], attrs)
       end
       messages << LLM::Message.new(@llm.tool_role, cancelled) unless cancelled.empty?
     end

data/lib/llm/contract/completion.rb

@@ -98,10 +98,10 @@ module LLM::Contract
     end
 
     ##
-    # @return [Hash]
+    # @return [LLM::Object]
     #  Returns the LLM response after parsing it as JSON
     def content!
-      LLM.json.load(content)
+      LLM::Object.from LLM.json.load(content)
     end
 
     ##

data/lib/llm/json_adapter.rb

@@ -38,11 +38,11 @@ module LLM
     def self.dump(obj, state = nil, **options)
       require "json" unless defined?(::JSON)
       if ::JSON::State === state
-        ::JSON.generate(obj, state)
+        ::JSON.generate(normalize(obj), state)
       elsif state
-        ::JSON.dump(obj, state, **options)
+        ::JSON.dump(normalize(obj), state, **options)
       else
-        ::JSON.dump(obj, **options)
+        ::JSON.dump(normalize(obj), **options)
       end
     end
 
@@ -59,6 +59,32 @@ module LLM
       require "json" unless defined?(::JSON)
       [::JSON::ParserError]
     end
+
+    ##
+    # JSON 3.0 compat
+    # Walks `obj` and encodes every string that is
+    # found into a UTF-8 compatible string.
+    def self.normalize(obj)
+      case obj
+      when String then normalize_string(obj)
+      when Array then obj.map { normalize(_1) }
+      when Hash then obj.map { [_1, normalize(_2)] }.to_h
+      when LLM::Object then obj.map { [_1, normalize(_2)] }.to_h
+      else obj
+      end
+    end
+    private_class_method :normalize
+
+    ##
+    # JSON 3.0 compat
+    # Normalizes a string as a UTF-8 encoded string
+    # that's compatible with the JSON spec.
+    def self.normalize_string(str)
+      return str if str.encoding == Encoding::UTF_8
+      str = (+str).force_encoding("UTF-8")
+      str.valid_encoding? ? str : str.scrub
+    end
+    private_class_method :normalize_string
   end
 
   ##

data/lib/llm/provider.rb

@@ -286,7 +286,7 @@ class LLM::Provider
   #  A tracer
   # @return [void]
   def tracer=(tracer)
-    @tracer = tracer
+    @tracer = tracer || LLM::Tracer::Null.new(self)
   end
 
   ##
@@ -348,8 +348,8 @@ class LLM::Provider
 
   private
 
-  def path(suffix)
-    return suffix if @base_path.empty?
+  def path(suffix, base_path: true)
+    return suffix if !base_path || @base_path.empty?
     "#{@base_path}#{suffix}"
   end
 

data/lib/llm/providers/deepinfra/audio.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+class LLM::DeepInfra
+  class Audio
+    ##
+    # @param [LLM::Provider] provider
+    #  A provider
+    # @return [LLM::DeepInfra::Audio]
+    def initialize(provider)
+      @provider = provider
+    end
+
+    ##
+    # @param [String] input
+    #  A string of text
+    # @param [String] model
+    #  A text-to-speech model.
+    #  Defaults to hexgrad/Kokoro-82M.
+    # @param [Hash] params
+    #  Any other model-specific parameters
+    # @return [LLM::Response]
+    def create_speech(input:, model: "hexgrad/Kokoro-82M", **params)
+      path = path("/v1/inference/#{model}", base_path: false)
+      req = LLM::Transport::Request.post(path, headers)
+      req.body = JSON.dump(params.merge(text: input))
+      res, span, tracer = execute(request: req, operation: "request")
+      res = ResponseAdapter.adapt LLM::Response.new(res), type: :audio
+      tracer.on_request_finish(operation: "request", model:, res:, span:)
+      res
+    end
+
+    ##
+    # @see https://deepinfra.com/models/automatic-speech-recognition speech-to-text models
+    # @see https://docs.deepinfra.com/apis/speech API docs
+    # @param [String, LLM::File] file
+    #  An audio file
+    # @param [String] model
+    #  A speech-to-text model.
+    # @param [Hash] params
+    #  Any other model-specific parameters
+    # @return [LLM::Response]
+    def create_transcription(file:, model: "openai/whisper-large-v3", **params)
+      path = path("/v1/inference/#{model}", base_path: false)
+      multi = LLM::Multipart.new(params.merge!(audio: LLM.File(file)))
+      req = LLM::Transport::Request.post(path, headers)
+      req["content-type"] = multi.content_type
+      transport.set_body_stream(req, multi.body)
+      res, span, tracer = execute(request: req, operation: "request")
+      res = LLM::Response.new(res)
+      tracer.on_request_finish(operation: "request", model:, res:, span:)
+      res
+    end
+
+    ##
+    # @raise [NotImplementedError]
+    def create_translation(...)
+      raise NotImplementedError
+    end
+
+    private
+
+    [:path, :headers, :execute, :transport].each do |m|
+      define_method(m) { |*args, **kwargs, &b| @provider.send(m, *args, **kwargs, &b) }
+    end
+  end
+end

data/lib/llm/providers/deepinfra/images.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+class LLM::DeepInfra
+  ##
+  # The {LLM::DeepInfra::Images LLM::DeepInfra::Images} class provides an
+  # interface for [DeepInfra's images API](https://docs.deepinfra.com/apis/image-generation).
+  # DeepInfra returns base64-encoded image data.
+  #
+  # @example
+  #   #!/usr/bin/env ruby
+  #   require "llm"
+  #
+  #   llm = LLM.deepinfra(key: ENV["KEY"])
+  #   res = llm.images.create prompt: "A dog on a rocket to the moon"
+  #   IO.copy_stream res.images[0], "rocket.png"
+  class Images
+    ##
+    # @param [LLM::Provider] provider
+    # @return [LLM::DeepInfra::Images]
+    def initialize(provider)
+      @provider = provider
+    end
+
+    ##
+    # @see https://deepinfra.com/models/text-to-image DeepInfra Image Models
+    # @param [String] prompt
+    #  A prompt
+    # @param [String] model
+    #  A text-to-image model.
+    #  Defaults to the black-forest-labs/FLUX-2-klein-4b.
+    # @param [String] size
+    #  Image size (eg 1024x1024)
+    # @param [Integer] n
+    #  The number of images to default
+    # @param [String] response_format
+    #  No other options other than the default are supported.
+    # @param [String] quality
+    #  Exists for compat. Noop.
+    # @param [String] style
+    #  Exists for compat. Noop.
+    # @return [LLM::Response<LLM::OpenAI::ResponseAdapter::Image>]
+    #  Returns a response
+    def create(prompt:, model: "black-forest-labs/FLUX-2-klein-4b", size: "1024x1024", n: 1, response_format: "b64_json", quality: nil, style: nil)
+      req = LLM::Transport::Request.post(path("/images/generations"), headers)
+      params = {prompt:, model:, size:, n:, response_format:, quality:, style:}.compact
+      req.body = LLM.json.dump(params)
+      res, span, tracer = execute(request: req, operation: "request")
+      res = LLM::OpenAI::ResponseAdapter.adapt(res, type: :image)
+      tracer.on_request_finish(operation: "request", model:, res:, span:)
+      res
+    end
+
+    ##
+    # @see https://deepinfra.com/models/text-to-image DeepInfra Image Models
+    # @param [String, LLM::File, File] image
+    #  The image to edit.
+    # @param [String] prompt
+    #  A text description of the desired edits.
+    # @param [String] model
+    #  The model to use.
+    # @param [String] size
+    #  Image size (eg 1024x1024)
+    # @param [Integer] n
+    #  The number of images to generate.
+    # @param [String] response_format
+    #  DeepInfra currently supports b64_json.
+    # @param [Hash] params
+    #  Other parameters supported by DeepInfra, such as :mask or :user.
+    # @return [LLM::Response<LLM::OpenAI::ResponseAdapter::Image>]
+    #  Returns a response
+    def edit(image:, prompt:, model: "black-forest-labs/FLUX-2-klein-4b", size: "1024x1024", n: 1, response_format: "b64_json", **params)
+      params = params.merge!(image: LLM.File(image), prompt:, model:, size:, n:, response_format:)
+      params[:mask] = LLM.File(params[:mask]) if params[:mask]
+      multi = LLM::Multipart.new(params)
+      req = LLM::Transport::Request.post(path("/images/edits"), headers)
+      req["content-type"] = multi.content_type
+      transport.set_body_stream(req, multi.body)
+      res, span, tracer = execute(request: req, operation: "request")
+      res = LLM::OpenAI::ResponseAdapter.adapt(res, type: :image)
+      tracer.on_request_finish(operation: "request", model:, res:, span:)
+      res
+    end
+
+    private
+
+    [:path, :headers, :execute, :transport].each do |m|
+      define_method(m) { |*args, **kwargs, &b| @provider.send(m, *args, **kwargs, &b) }
+    end
+  end
+end

data/lib/llm/providers/deepinfra/response_adapter.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+class LLM::DeepInfra
+  ##
+  # @private
+  module ResponseAdapter
+    module Audio
+      ##
+      # @return [LLM::URIData]
+      def audio
+        @audio ||= LLM::URIData.parse(super)
+      end
+    end
+
+    module_function
+
+    ##
+    # @param [LLM::Response, Net::HTTPResponse] res
+    # @param [Symbol] type
+    # @return [LLM::Response]
+    def adapt(res, type:)
+      response = (LLM::Response === res) ? res : LLM::Response.new(res)
+      adapter = select(type)
+      response.extend(adapter)
+    end
+
+    ##
+    # @api private
+    def select(type)
+      case type
+      when :audio then Audio
+      else LLM::OpenAI::ResponseAdapter.select(type)
+      end
+    end
+  end
+end

data/lib/llm/providers/deepinfra.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require_relative "openai" unless defined?(LLM::OpenAI)
+
+module LLM
+  ##
+  # The DeepInfra class implements a provider for
+  # [DeepInfra](https://deepinfra.com)
+  # through its OpenAI-compatible API.
+  #
+  # @example
+  #   #!/usr/bin/env ruby
+  #   require "llm"
+  #
+  #   llm = LLM.deepinfra(key: ENV["KEY"])
+  #   ctx = LLM::Context.new(llm)
+  #   ctx.talk "Hello"
+  #   ctx.messages.select(&:assistant?).each { print "[#{_1.role}]", _1.content, "\n" }
+  class DeepInfra < OpenAI
+    HOST = "api.deepinfra.com"
+    BASE_PATH = "/v1/openai"
+    require_relative "deepinfra/images"
+    require_relative "deepinfra/audio"
+    require_relative "deepinfra/response_adapter"
+
+    ##
+    # @param key (see LLM::Provider#initialize)
+    # @param host (see LLM::Provider#initialize)
+    # @param base_path (see LLM::Provider#initialize)
+    # @return [LLM::DeepInfra]
+    def initialize(host: HOST, base_path: BASE_PATH, **)
+      super
+    end
+
+    ##
+    # @return [Symbol]
+    #  Returns the provider's name
+    def name
+      :deepinfra
+    end
+
+    ##
+    # Provides an interface to DeepInfra's OpenAI-compatible image API.
+    # @see https://deepinfra.com/models/text-to-image DeepInfra image models
+    # @return [LLM::DeepInfra::Images]
+    def images
+      LLM::DeepInfra::Images.new(self)
+    end
+
+    ##
+    # Provides an embedding.
+    # @see https://deepinfra.com/BAAI/bge-m3 BAAI/bge-m3
+    # @param input (see LLM::Provider#embed)
+    # @param model (see LLM::Provider#embed)
+    # @param params (see LLM::Provider#embed)
+    # @raise (see LLM::Provider#request)
+    # @return (see LLM::Provider#embed)
+    def embed(input, model: "BAAI/bge-m3", **params)
+      super
+    end
+
+    ##
+    # @raise [NotImplementedError]
+    def responses
+      raise NotImplementedError
+    end
+
+    ##
+    # @return [LLM::DeepInfra::Audio]
+    def audio
+      LLM::DeepInfra::Audio.new(self)
+    end
+
+    ##
+    # @raise [NotImplementedError]
+    def files
+      raise NotImplementedError
+    end
+
+    ##
+    # @raise [NotImplementedError]
+    def moderations
+      raise NotImplementedError
+    end
+
+    ##
+    # @raise [NotImplementedError]
+    def vector_stores
+      raise NotImplementedError
+    end
+
+    ##
+    # Returns the default model for chat completions
+    # @see https://deepinfra.com/models/zai-org/GLM-5.2 zai-org/GLM-5.2
+    # @return [String]
+    def default_model
+      "zai-org/GLM-5.2"
+    end
+  end
+end