llm.rb 11.3.1 → 12.0.0

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/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
 
@@ -548,7 +551,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 +601,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/provider.rb

@@ -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

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

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+class LLM::DeepSeek
+  ##
+  # The {LLM::DeepSeek::Images LLM::DeepSeek::Images} class
+  # provides image generation capabilities through DeepSeek.
+  #
+  # DeepSeek does not provide an image generation model however
+  # its text-to-text models can generate vector graphics (SVGS)
+  # and that's the approach that this class takes. It is somewhat
+  # experimental.
+  #
+  # An SVG document can be converted to PNG or another format
+  # with tools like rsvg-convert.
+  class Images
+    ##
+    # @param [LLM::DeepSeek] provider
+    # @return [LLM::DeepSeek::Images]
+    def initialize(provider)
+      @provider = provider
+    end
+
+    ##
+    # @param [String] prompt
+    #  A prompt
+    # @param [String] model
+    #  A text-to-image model.
+    # @param [void] size
+    #  This parameter is a noop.
+    #  Exists for compatibility with other providers.
+    # @param [void] n
+    #  This parameter is a noop.
+    #  Exists for compatibility with other providers.
+    # @param [void] response_format
+    #  This parameter is a noop.
+    #  Exists for compatibility with other providers.
+    # @param [void] quality
+    #  This parameter is a noop.
+    #  Exists for compatibility with other providers.
+    # @param [void] style
+    #  This parameter is a noop.
+    #  Exists for compatibility with other providers.
+    # @return [LLM::Response<LLM::DeepSeek::ResponseAdapter::Image>]
+    #  Returns a response
+    def create(prompt:, model: @provider.default_model, agent: nil, size: nil, n: nil, response_format: nil, quality: nil, style: nil)
+      agent ||= LLM::Agent.new(@provider, model:, instructions: create_instructions, response_format: {type: "json_object"})
+      res = agent.talk(prompt)
+      res = LLM::DeepSeek::ResponseAdapter.adapt(res, type: :image)
+      res.define_singleton_method(:agent) { agent }
+      res
+    end
+
+    ##
+    # @param [String] prompt
+    #  A prompt
+    # @param [String] model
+    #  A text-to-image model.
+    # @param [String, LLM::File] image
+    #  The path to an SVG file
+    # @param [void] size
+    #  This parameter is a noop.
+    #  Exists for compatibility with other providers.
+    # @param [void] n
+    #  This parameter is a noop.
+    #  Exists for compatibility with other providers.
+    # @param [void] response_format
+    #  This parameter is a noop.
+    #  Exists for compatibility with other providers.
+    # @param [void] quality
+    #  This parameter is a noop.
+    #  Exists for compatibility with other providers.
+    # @param [void] style
+    #  This parameter is a noop.
+    #  Exists for compatibility with other providers.
+    # @return [LLM::Response<LLM::DeepSeek::ResponseAdapter::Image>]
+    #  Returns a response
+    def edit(prompt:, image:, model: @provider.default_model, agent: nil, size: nil, n: nil, response_format: nil, quality: nil, style: nil)
+      file = LLM.File(image)
+      agent ||= LLM::Agent.new(@provider, model:, instructions: edit_instructions(file), response_format: {type: "json_object"})
+      res = agent.talk(prompt)
+      res = LLM::DeepSeek::ResponseAdapter.adapt(res, type: :image)
+      res.define_singleton_method(:agent) { agent }
+      res
+    end
+
+    private
+
+    def create_instructions
+      "Generate a complete SVG document that satisfies the user's prompt. " \
+      "Respond with a JSON object that has exactly one key: svg. " \
+      "The value of svg must be a valid standalone SVG document as a string. " \
+      "Do not include markdown, code fences, commentary, or any keys other than svg."
+    end
+
+    def edit_instructions(file)
+      file.with_io do |io|
+        "Edit the SVG document that is provided according to the user's prompt" \
+        "Respond with a JSON object that has exactly one key: svg. " \
+        "The value of svg must be a valid standalone SVG document as a string. " \
+        "Do not include markdown, code fences, commentary, or any keys other than svg." \
+        "The SVG document follows:\n\n#{io.read}" \
+      end
+    end
+
+    [: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/deepseek/request_adapter.rb

@@ -5,6 +5,7 @@ class LLM::DeepSeek
   # @private
   module RequestAdapter
     require_relative "request_adapter/completion"
+
     ##
     # @param [Array<LLM::Message>] messages
     #  The messages to adapt
@@ -17,6 +18,37 @@ class LLM::DeepSeek
 
     private
 
+    ##
+    # Adapt a schema for the DeepSeek chat completions API.
+    #
+    # DeepSeek does not support OpenAI's `json_schema` response format,
+    # so llm.rb falls back to `json_object` and injects a system message
+    # that describes the expected shape in prompt-friendly terms.
+    #
+    # @param [Hash] params
+    #  The request params
+    # @return [Hash]
+    def adapt_schema(params)
+      return {} unless params && params[:schema]
+      schema = params.delete(:schema)
+      schema = schema.respond_to?(:object) ? schema.object : schema
+      params[:messages] ||= []
+      params[:messages] << LLM::Message.new(system_role, adapt_prompt(schema))
+      {response_format: {type: "json_object"}}
+    end
+
+    ##
+    # Build the system prompt that describes the schema.
+    # @param [#to_s] schema
+    #  The schema object
+    # @return [String]
+    def adapt_prompt(schema)
+      "Respond with a single valid JSON object. " \
+      "Do not include markdown, code fences, commentary, or any text outside the JSON object. " \
+      "The JSON object must match this schema: " \
+      "#{schema}"
+    end
+
     ##
     # @param [Array<LLM::Function>] tools
     # @return [Hash]

data/lib/llm/providers/deepseek/response_adapter/image.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module LLM::DeepSeek::ResponseAdapter
+  module Image
+    def images
+      [StringIO.new(content!.svg)]
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+class LLM::DeepSeek
+  ##
+  # @private
+  module ResponseAdapter
+    require_relative "response_adapter/image"
+    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 :image then LLM::DeepSeek::ResponseAdapter::Image
+      else LLM::OpenAI::ResponseAdapter.select(type)
+      end
+    end
+  end
+end

data/lib/llm/providers/deepseek.rb

@@ -19,6 +19,8 @@ module LLM
   #   ctx.messages.select(&:assistant?).each { print "[#{_1.role}]", _1.content, "\n" }
   class DeepSeek < OpenAI
     require_relative "deepseek/request_adapter"
+    require_relative "deepseek/response_adapter"
+    require_relative "deepseek/images"
     include DeepSeek::RequestAdapter
 
     ##
@@ -42,9 +44,9 @@ module LLM
     end
 
     ##
-    # @raise [NotImplementedError]
+    # @raise [LLM::DeepSeek::Images]
     def images
-      raise NotImplementedError
+      LLM::DeepSeek::Images.new(self)
     end
 
     ##

data/lib/llm/providers/google/request_adapter.rb

@@ -21,11 +21,17 @@ class LLM::Google
     ##
     # @param [Hash] params
     # @return [Hash]
-    def adapt_schema(params)
-      return {} unless params and params[:schema]
-      schema = params.delete(:schema)
-      schema = schema.respond_to?(:object) ? schema.object : schema
-      {generationConfig: {response_mime_type: "application/json", response_schema: schema}}
+    def adapt_generation_config(params)
+      return {} unless params
+      config = {}
+      if params[:schema]
+        schema = params.delete(:schema)
+        schema = schema.respond_to?(:object) ? schema.object : schema
+        config.merge!(response_mime_type: "application/json", response_schema: schema)
+      end
+      params_map.each { config[_1] = params.delete(_2) if params.key?(_2) }
+      config.merge!(params)
+      config.empty? ? {} : {generationConfig: config}
     end
 
     ##
@@ -36,5 +42,16 @@ class LLM::Google
       platform, functions = [tools.grep(LLM::ServerTool), tools.grep(LLM::Function)]
       {tools: [*platform, {functionDeclarations: functions.map { _1.adapt(self) }}]}
     end
+
+    ##
+    # @return [Hash]
+    def params_map
+      {
+        topP: :top_p,
+        topK: :top_k,
+        maxOutputTokens: :max_tokens,
+        stopSequences: :stop
+      }
+    end
   end
 end