llm.rb 11.3.0 → 12.0.0

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
@@ -18,7 +19,38 @@ 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]
     def adapt_tools(tools)
       (tools.nil? || tools.empty?) ? {} : {tools: tools.map { _1.adapt(self) }}

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,20 +21,37 @@ 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
 
     ##
-    # @param [Hash] params
+    # @param [Array<LLM::Function>] tools
     # @return [Hash]
     def adapt_tools(tools)
       return {} unless tools&.any?
       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

data/lib/llm/providers/google.rb

@@ -53,7 +53,7 @@ module LLM
     # @param params (see LLM::Provider#embed)
     # @raise (see LLM::Provider#request)
     # @return [LLM::Response]
-    def embed(input, model: "gemini-embedding-001", **params)
+    def embed(input, model: "gemini-embedding-2", **params)
       model = model.respond_to?(:id) ? model.id : model
       path = ["/v1beta/models/#{model}", "embedContent?key=#{@key}"].join(":")
       req = LLM::Transport::Request.post(path, headers)
@@ -118,10 +118,10 @@ module LLM
 
     ##
     # Returns the default model for chat completions
-    # @see https://ai.google.dev/gemini-api/docs/models#gemini-2.5-flash gemini-2.5-flash
+    # @see https://ai.google.dev/gemini-api/docs/models#gemini-31-flash-lite gemini-3.1-flash-lite
     # @return [String]
     def default_model
-      "gemini-2.5-flash"
+      "gemini-3.1-flash-lite"
     end
 
     ##
@@ -196,7 +196,7 @@ module LLM
     def normalize_complete_params(params)
       params = {role: :user, model: default_model}.merge!(params)
       tools  = resolve_tools(params.delete(:tools))
-      params = [params, adapt_schema(params), adapt_tools(tools)].inject({}, &:merge!).compact
+      params = [params, adapt_generation_config(params), adapt_tools(tools)].inject({}, &:merge!).compact
       role, model, stream = [:role, :model, :stream].map { params.delete(_1) }
       [params, stream, tools, role, model]
     end

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

@@ -19,7 +19,7 @@ class LLM::Ollama
     private
 
     ##
-    # @param [Hash] params
+    # @param [Array<LLM::Function>] tools
     # @return [Hash]
     def adapt_tools(tools)
       return {} unless tools&.any?

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

@@ -22,7 +22,7 @@ class LLM::OpenAI
     # @example
     #   llm = LLM.openai(key: ENV["KEY"])
     #   res = llm.images.create_speech(input: "A dog on a rocket to the moon")
-    #   File.binwrite("rocket.mp3", res.audio.string)
+    #   IO.copy_stream res.audio.decoded, "rocket.mp3"
     # @see https://platform.openai.com/docs/api-reference/audio/createSpeech OpenAI docs
     # @param [String] input The text input
     # @param [String] voice The voice to use
@@ -36,7 +36,11 @@ class LLM::OpenAI
       req.body = LLM.json.dump({input:, voice:, model:, response_format:}.merge!(params))
       io = StringIO.new("".b)
       res, span, tracer = execute(request: req, operation: "request") { _1.read_body { |chunk| io << chunk } }
-      res = LLM::Response.new(res).tap { _1.define_singleton_method(:audio) { io } }
+      content_type = res["content-type"].to_s.split(";").first
+      content_type = content_type.empty? ? LLM::Mime[".#{response_format}"] : content_type
+      data = "data:#{content_type};base64,#{[io.string].pack("m0")}"
+      res.body = LLM::Object.from(audio: data)
+      res = ResponseAdapter.adapt(LLM::Response.new(res), type: :audio)
       tracer.on_request_finish(operation: "request", model:, res:, span:)
       res
     end

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

@@ -4,28 +4,14 @@ class LLM::OpenAI
   ##
   # The {LLM::OpenAI::Images LLM::OpenAI::Images} class provides an interface
   # for [OpenAI's images API](https://platform.openai.com/docs/api-reference/images).
-  # OpenAI supports multiple response formats: temporary URLs, or binary strings
-  # encoded in base64. The default is to return base64-encoded image data.
+  # OpenAI's GPT Image models return base64-encoded image data.
   #
-  # @example Temporary URLs
+  # @example
   #   #!/usr/bin/env ruby
   #   require "llm"
-  #   require "open-uri"
-  #   require "fileutils"
   #
   #   llm = LLM.openai(key: ENV["KEY"])
-  #   res = llm.images.create prompt: "A dog on a rocket to the moon",
-  #                           response_format: "url"
-  #   FileUtils.mv OpenURI.open_uri(res.urls[0]).path,
-  #                "rocket.png"
-  #
-  # @example Binary strings
-  #   #!/usr/bin/env ruby
-  #   require "llm"
-  #
-  #   llm = LLM.openai(key: ENV["KEY"])
-  #   res = llm.images.create prompt: "A dog on a rocket to the moon",
-  #                           response_format: "b64_json"
+  #   res = llm.images.create prompt: "A dog on a rocket to the moon"
   #   IO.copy_stream res.images[0], "rocket.png"
   class Images
     ##
@@ -45,40 +31,13 @@ class LLM::OpenAI
     # @see https://platform.openai.com/docs/api-reference/images/create OpenAI docs
     # @param [String] prompt The prompt
     # @param [String] model The model to use
-    # @param [String] response_format The response format ("b64_json" or "url")
+    # @param [String] output_format The output format ("png", "webp", or "jpeg")
     # @param [Hash] params Other parameters (see OpenAI docs)
     # @raise (see LLM::Provider#request)
     # @return [LLM::Response]
-    def create(prompt:, model: "dall-e-3", response_format: "b64_json", **params)
+    def create(prompt:, model: "gpt-image-1-mini", output_format: "png", **params)
       req = LLM::Transport::Request.post(path("/images/generations"), headers)
-      req.body = LLM.json.dump({prompt:, n: 1, model:, response_format:}.merge!(params))
-      res, span, tracer = execute(request: req, operation: "request")
-      res = ResponseAdapter.adapt(res, type: :image)
-      tracer.on_request_finish(operation: "request", model:, res:, span:)
-      res
-    end
-
-    ##
-    # Create image variations
-    # @example
-    #   llm = LLM.openai(key: ENV["KEY"])
-    #   res = llm.images.create_variation(image: "/images/hat.png", n: 5)
-    #   res.images.each.with_index do |image, index|
-    #     IO.copy_stream image, "variation#{index}.png"
-    #   end
-    # @see https://platform.openai.com/docs/api-reference/images/createVariation OpenAI docs
-    # @param [File] image The image to create variations from
-    # @param [String] model The model to use
-    # @param [String] response_format The response format ("b64_json" or "url")
-    # @param [Hash] params Other parameters (see OpenAI docs)
-    # @raise (see LLM::Provider#request)
-    # @return [LLM::Response]
-    def create_variation(image:, model: "dall-e-2", response_format: "b64_json", **params)
-      image = LLM.File(image)
-      multi = LLM::Multipart.new(params.merge!(image:, model:, response_format:))
-      req = LLM::Transport::Request.post(path("/images/variations"), headers)
-      req["content-type"] = multi.content_type
-      transport.set_body_stream(req, multi.body)
+      req.body = LLM.json.dump({prompt:, n: 1, model:, output_format:}.merge!(params))
       res, span, tracer = execute(request: req, operation: "request")
       res = ResponseAdapter.adapt(res, type: :image)
       tracer.on_request_finish(operation: "request", model:, res:, span:)
@@ -95,13 +54,13 @@ class LLM::OpenAI
     # @param [File] image The image to edit
     # @param [String] prompt The prompt
     # @param [String] model The model to use
-    # @param [String] response_format The response format ("b64_json" or "url")
+    # @param [String] output_format The output format ("png", "webp", or "jpeg")
     # @param [Hash] params Other parameters (see OpenAI docs)
     # @raise (see LLM::Provider#request)
     # @return [LLM::Response]
-    def edit(image:, prompt:, model: "dall-e-2", response_format: "b64_json", **params)
+    def edit(image:, prompt:, model: "gpt-image-1-mini", output_format: "png", **params)
       image = LLM.File(image)
-      multi = LLM::Multipart.new(params.merge!(image:, prompt:, model:, response_format:))
+      multi = LLM::Multipart.new(params.merge!(image:, prompt:, model:, output_format:))
       req = LLM::Transport::Request.post(path("/images/edits"), headers)
       req["content-type"] = multi.content_type
       transport.set_body_stream(req, multi.body)

data/lib/llm/providers/openai/request_adapter/respond.rb

@@ -16,7 +16,7 @@ module LLM::OpenAI::RequestAdapter
         if Hash === message
           {role: message[:role], content: adapt_content(message[:content])}
         elsif message.tool_call?
-          message.extra[:original_tool_calls]
+          adapt_tool_calls(message.extra[:original_tool_calls])
         else
           adapt_message
         end
@@ -33,11 +33,12 @@ module LLM::OpenAI::RequestAdapter
       when LLM::Message then adapt_content(content.content, role: content.role)
       when LLM::Object
         case content.kind
-        when :image_url then [{type: :image_url, image_url: {url: content.value.to_s}}]
+        when :image_url then [{type: :input_image, image_url: content.value.to_s}]
         when :remote_file then adapt_remote_file(content.value)
-        when :local_file then prompt_error!(content)
+        when :local_file then adapt_local_file(content.value)
         else prompt_error!(content)
         end
+      when Array then content.flat_map { adapt_content(_1, role:) }
       else
         prompt_error!(content)
       end
@@ -45,6 +46,8 @@ module LLM::OpenAI::RequestAdapter
 
     def adapt_message
       case content
+      when LLM::Function::Return
+        adapt_returns([content])
       when Array
         adapt_array
       else
@@ -56,12 +59,35 @@ module LLM::OpenAI::RequestAdapter
       if content.empty?
         nil
       elsif returns.any?
-        returns.map { {type: "function_call_output", call_id: _1.id, output: LLM.json.dump(_1.value)} }
+        adapt_returns(returns)
       else
         {role: message.role, content: content.flat_map { adapt_content(_1, role: message.role) }}
       end
     end
 
+    def adapt_returns(returns)
+      returns.map { {type: "function_call_output", call_id: _1.id, output: LLM.json.dump(_1.value)} }
+    end
+
+    def adapt_tool_calls(tools)
+      [*tools].map do |tool|
+        h = LLM::Object.from(tool.to_h)
+        # Backward compatibility for conversations that
+        # started under the chat completions API and are
+        # later continued through Responses.
+        if h.type.to_s == "function"
+          {
+            type: "function_call",
+            call_id: h.id,
+            name: h.function.name,
+            arguments: h.function.arguments || "{}"
+          }
+        else
+          tool
+        end
+      end
+    end
+
     def adapt_remote_file(content)
       prompt_error!(content) unless content.file?
       file = LLM::File(content.filename)
@@ -72,6 +98,14 @@ module LLM::OpenAI::RequestAdapter
       end
     end
 
+    def adapt_local_file(file)
+      if file.image?
+        [{type: :input_image, image_url: file.to_data_uri}]
+      else
+        [{type: :input_file, filename: file.basename, file_data: file.to_data_uri}]
+      end
+    end
+
     def prompt_error!(content)
       if LLM::Object === content
         raise LLM::PromptError, "The given LLM::Object with kind '#{content.kind}' is not " \

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

@@ -42,7 +42,7 @@ class LLM::OpenAI
     end
 
     ##
-    # @param [Hash] params
+    # @param [Array<LLM::Function>] tools
     # @return [Hash]
     def adapt_tools(tools)
       if tools.nil? || tools.empty?

data/lib/llm/providers/openai/response_adapter/audio.rb

@@ -2,6 +2,10 @@
 
 module LLM::OpenAI::ResponseAdapter
   module Audio
-    def audio = body.audio
+    ##
+    # @return [LLM::URIData]
+    def audio
+      @audio ||= LLM::URIData.parse(super)
+    end
   end
 end

data/lib/llm/providers/openai/response_adapter/completion.rb

@@ -5,7 +5,7 @@ module LLM::OpenAI::ResponseAdapter
     ##
     # (see LLM::Contract::Completion#messages)
     def messages
-      body.choices.map.with_index do |choice, index|
+      [*body.choices].map.with_index do |choice, index|
         message = choice.message
         extra = {
           index:, response: self,

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

@@ -2,10 +2,6 @@
 
 module LLM::OpenAI::ResponseAdapter
   module Image
-    def urls
-      data.filter_map { _1["url"] }
-    end
-
     def images
       data.filter_map do
         next unless _1["b64_json"]

data/lib/llm/providers/openai/responses.rb

@@ -100,6 +100,7 @@ class LLM::OpenAI
     def adapt_schema(params)
       return {} unless params && params[:schema]
       schema = params.delete(:schema)
+      schema = schema.respond_to?(:object) ? schema.object : schema
       schema = schema.to_h.merge(additionalProperties: false)
       name = "JSONSchema"
       {text: {format: {type: "json_schema", name:, schema:}}}

data/lib/llm/providers/openai/stream_parser.rb

@@ -66,26 +66,25 @@ class LLM::OpenAI
     end
 
     def merge_delta!(target_message, delta)
-      if delta.length == 1
-        merge_single_delta!(target_message, delta)
-      elsif content = delta["content"]
+      if delta.key?("content") and (content = delta["content"])
         if target_content = target_message["content"]
           target_content << content
         else
           target_message["content"] = content
         end
         emit_content(content)
-      elsif reasoning = delta["reasoning_content"]
+      end
+      if delta.key?("reasoning_content") and (reasoning = delta["reasoning_content"])
         if target_reasoning = target_message["reasoning_content"]
           target_reasoning << reasoning
         else
           target_message["reasoning_content"] = reasoning
         end
         emit_reasoning_content(reasoning)
-      elsif tool_calls = delta["tool_calls"]
+      end
+      if delta.key?("tool_calls") and (tool_calls = delta["tool_calls"])
         merge_tools!(target_message, tool_calls)
       end
-      return if delta.length <= 1
       delta.each do |key, value|
         next if value.nil? || key == "content" || key == "reasoning_content" || key == "tool_calls"
         target_message[key] = value

data/lib/llm/providers/openai.rb

@@ -146,10 +146,10 @@ module LLM
 
     ##
     # Returns the default model for chat completions
-    # @see https://platform.openai.com/docs/models/gpt-4.1 gpt-4.1
+    # @see https://platform.openai.com/docs/models/gpt-5.4-mini gpt-5.4-mini
     # @return [String]
     def default_model
-      "gpt-4.1"
+      "gpt-5.4-mini"
     end
 
     ##