llm.rb 11.3.1 → 12.0.0

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/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/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
 
     ##

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

@@ -4,30 +4,21 @@ class LLM::XAI
   ##
   # The {LLM::XAI::Images LLM::XAI::Images} class provides an interface
   # for [xAI's images API](https://docs.x.ai/docs/guides/image-generations).
-  # xAI supports multiple response formats: temporary URLs, or binary strings
-  # encoded in base64. The default is to return base64-encoded image data.
+  # xAI returns base64-encoded image data.
   #
-  # @example Temporary URLs
+  # @example
   #   #!/usr/bin/env ruby
   #   require "llm"
-  #   require "open-uri"
-  #   require "fileutils"
   #
   #   llm = LLM.xai(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.xai(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 < LLM::OpenAI::Images
+    ##
+    # @api private
+    PATTERN = %r{\A(?:https?://|data:)}
+    private_constant :PATTERN
+
     ##
     # Create an image
     # @example
@@ -40,20 +31,52 @@ class LLM::XAI
     # @param [Hash] params Other parameters (see xAI docs)
     # @raise (see LLM::Provider#request)
     # @return [LLM::Response]
-    def create(prompt:, model: "grok-imagine-image", **params)
-      super
+    def create(prompt:, model: "grok-imagine-image-quality", **params)
+      req = LLM::Transport::Request.post(path("/images/generations"), headers)
+      req.body = LLM.json.dump({prompt:, n: 1, model:, response_format: "b64_json"}.merge!(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
 
     ##
-    # @raise [NotImplementedError]
-    def edit(model: "grok-imagine-image", **)
-      raise NotImplementedError
+    # Edit an image
+    # @example
+    #   llm = LLM.xai(key: ENV["KEY"])
+    #   res = llm.images.edit(image: "/images/book.png", prompt: "The book is floating in the clouds")
+    #   IO.copy_stream res.images[0], "floating-book.png"
+    # @see https://docs.x.ai/docs/guides/image-generations xAI docs
+    # @param [String, LLM::File, File] image The image to edit
+    # @param [String] prompt The prompt
+    # @param [String] model The model to use
+    # @param [Hash] params Other parameters (see xAI docs)
+    # @raise (see LLM::Provider#request)
+    # @return [LLM::Response]
+    def edit(image:, prompt:, model: "grok-imagine-image-quality", **params)
+      req = LLM::Transport::Request.post(path("/images/edits"), headers)
+      req.body = LLM.json.dump({
+        prompt:,
+        model:,
+        image: image_url(image),
+        response_format: "b64_json"
+      }.merge!(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
 
-    ##
-    # @raise [NotImplementedError]
-    def create_variation(model: "grok-imagine-image", **)
-      raise NotImplementedError
+    private
+
+    def image_url(image)
+      case image
+      when String
+        url = image.match?(PATTERN) ? image : LLM.File(image).to_data_uri
+      else
+        url = LLM.File(image).to_data_uri
+      end
+      {url:, type: "image_url"}
     end
   end
 end

data/lib/llm/providers/xai.rb

@@ -70,10 +70,10 @@ module LLM
 
     ##
     # Returns the default model for chat completions
-    # #see https://docs.x.ai/docs/models grok-4-0709
+    # #see https://docs.x.ai/docs/models grok-4.3
     # @return [String]
     def default_model
-      "grok-4-0709"
+      "grok-4.3"
     end
   end
 end

data/lib/llm/response.rb

@@ -56,6 +56,16 @@ module LLM
       @res.success?
     end
 
+    ##
+    # Returns the provider response id when present.
+    # @return [String, nil]
+    def id
+      return nil unless LLM::Object === body
+      body.id          ||
+      body.responseId  || body.response_id ||
+      body.requestId   || body.request_id
+    end
+
     ##
     # Returns true if the response is from the Files API
     # @return [Boolean]

data/lib/llm/schema/leaf.rb

@@ -95,7 +95,7 @@ class LLM::Schema
     ##
     # @return [Hash]
     def to_h
-      {description: @description, default: @default, enum: @enum}.compact
+      {description: @description, default: @default, enum: @enum, const: @const}.compact
     end
 
     ##
@@ -104,6 +104,12 @@ class LLM::Schema
       to_h.to_json(options)
     end
 
+    ##
+    # @return [String]
+    def to_s
+      LLM::Schema::Renderer.render(self)
+    end
+
     ##
     # @param [LLM::Schema::Leaf] other
     #  An object to compare

data/lib/llm/schema/renderer.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+class LLM::Schema
+  ##
+  # Internal renderer for prompt-friendly schema output.
+  # @api private
+  module Renderer
+    extend self
+
+    ##
+    # Render a schema node as a human-readable string.
+    # @param [LLM::Schema::Leaf] node
+    #  The schema node to render
+    # @param [Integer] indent
+    #  The indentation level
+    # @param [String, Symbol, nil] name
+    #  The property name for nested nodes
+    # @param [Boolean] root
+    #  Whether the node is the root schema object
+    # @return [String]
+    def render(node, indent: 0, name: nil, root: false)
+      line = (" " * indent).to_s
+      if name
+        line << name.to_s
+        line << "?" unless node.required?
+        line << ": "
+      end
+      line << type_name(node)
+      metadata = metadata_for(node, include_required: !root)
+      line << " (#{metadata.join(", ")})" unless metadata.empty?
+      line << " - #{node.description}" if node.respond_to?(:description) && node.description
+      nested = nested_lines(node, indent: indent + 2)
+      ([line] + nested).join("\n")
+    end
+
+    private
+
+    ##
+    # Render nested lines for compound schema nodes.
+    # @param [LLM::Schema::Leaf] node
+    #  The schema node
+    # @param [Integer] indent
+    #  The indentation level
+    # @return [Array<String>]
+    def nested_lines(node, indent:)
+      case node
+      when LLM::Schema::Object
+        node.properties.map { |key, val| render(val, indent:, name: key) }
+      when LLM::Schema::Array
+        items = node.to_h[:items]
+        items.is_a?(LLM::Schema::Object) ? [render(items, indent:, name: "items")] : []
+      else
+        []
+      end
+    end
+
+    ##
+    # Return the printable type name for a schema node.
+    # @param [LLM::Schema::Leaf] node
+    #  The schema node
+    # @return [String]
+    def type_name(node)
+      h = node.to_h
+      return "array<#{inline_type(h[:items])}>" if node.is_a?(LLM::Schema::Array)
+      return "anyOf<#{inline_types(h[:anyOf])}>" if node.is_a?(LLM::Schema::AnyOf)
+      return "oneOf<#{inline_types(h[:oneOf])}>" if node.is_a?(LLM::Schema::OneOf)
+      return "allOf<#{inline_types(h[:allOf])}>" if node.is_a?(LLM::Schema::AllOf)
+      h[:type] || "unknown"
+    end
+
+    ##
+    # Return the inline type description for a nested node.
+    # @param [LLM::Schema::Leaf, Object] node
+    #  The nested schema node
+    # @return [String]
+    def inline_type(node)
+      return type_name(node) if node.is_a?(LLM::Schema::Leaf)
+      node.inspect
+    end
+
+    ##
+    # Return the inline type description for a list of nodes.
+    # @param [Array<LLM::Schema::Leaf>] values
+    #  The union members
+    # @return [String]
+    def inline_types(values)
+      values.map { inline_type(_1) }.join(", ")
+    end
+
+    ##
+    # Extract printable metadata for a schema node.
+    # @param [LLM::Schema::Leaf] node
+    #  The schema node
+    # @param [Boolean] include_required
+    #  Whether to include the required marker
+    # @return [Array<String>]
+    def metadata_for(node, include_required:)
+      h = node.to_h.dup
+      details = []
+      details << "required" if include_required && node.required?
+      details << "default: #{value(node.default)}" if node.default
+      details << "enum: #{node.enum.map { value(_1) }.join(" | ")}" if node.enum
+      details << "const: #{value(node.const)}" if node.const
+      h.except(:type, :description, :default, :enum, :const, :required, :properties, :items, :anyOf, :oneOf, :allOf)
+        .each { |key, val| details << "#{key}: #{value(val)}" }
+      details
+    end
+
+    ##
+    # Convert a scalar value into its printable representation.
+    # @param [Object] val
+    #  The value to render
+    # @return [String]
+    def value(val)
+      case val
+      when ::String then val.inspect
+      else val.to_s
+      end
+    end
+  end
+end

data/lib/llm/schema.rb

@@ -34,6 +34,7 @@
 class LLM::Schema
   require_relative "schema/version"
   require_relative "schema/parser"
+  require_relative "schema/renderer"
   require_relative "schema/leaf"
   require_relative "schema/object"
   require_relative "schema/array"
@@ -121,6 +122,19 @@ class LLM::Schema
     end
   end
 
+  ##
+  # @param [Hash] defaults
+  # @return [LLM::Schema::Object]
+  def self.defaults(defaults)
+    lock do
+      object.tap do |schema|
+        defaults.each do |name, val|
+          Utils.fetch(schema.properties, name).default(val)
+        end
+      end
+    end
+  end
+
   ##
   # @api private
   # @return [LLM::Schema]
@@ -139,6 +153,14 @@ class LLM::Schema
     end
   end
 
+  ##
+  # Render the schema as a prompt-friendly string.
+  # @return [String]
+  def self.to_s
+    Renderer.render(object, root: true)
+  end
+  (class << self; self; end).alias_method(:inspect, :to_s)
+
   ##
   # @api private
   def self.lock(&)
@@ -220,4 +242,12 @@ class LLM::Schema
   def null
     Null.new
   end
+
+  ##
+  # Render a schema leaf as a prompt-friendly string.
+  # @return [String]
+  def to_s
+    self.class.to_s
+  end
+  alias_method :inspect, :to_s
 end