llm.rb 2.1.0 → 3.0.0

data/lib/llm/providers/anthropic.rb

@@ -14,14 +14,13 @@ module LLM
   #   bot.chat ["Tell me about this photo", File.open("/images/dog.jpg", "rb")]
   #   bot.messages.select(&:assistant?).each { print "[#{_1.role}]", _1.content, "\n" }
   class Anthropic < Provider
-    require_relative "anthropic/response/completion"
-    require_relative "anthropic/response/web_search"
-    require_relative "anthropic/format"
     require_relative "anthropic/error_handler"
+    require_relative "anthropic/request_adapter"
+    require_relative "anthropic/response_adapter"
     require_relative "anthropic/stream_parser"
-    require_relative "anthropic/files"
     require_relative "anthropic/models"
-    include Format
+    require_relative "anthropic/files"
+    include RequestAdapter
 
     HOST = "api.anthropic.com"
 
@@ -44,16 +43,15 @@ module LLM
     def complete(prompt, params = {})
       params = {role: :user, model: default_model, max_tokens: 1024}.merge!(params)
       tools  = resolve_tools(params.delete(:tools))
-      params = [params, format_tools(tools)].inject({}, &:merge!).compact
+      params = [params, adapt_tools(tools)].inject({}, &:merge!).compact
       role, stream = params.delete(:role), params.delete(:stream)
       params[:stream] = true if stream.respond_to?(:<<) || stream == true
       req = Net::HTTP::Post.new("/v1/messages", headers)
       messages = [*(params.delete(:messages) || []), Message.new(role, prompt)]
-      body = JSON.dump({messages: [format(messages)].flatten}.merge!(params))
+      body = LLM.json.dump({messages: [adapt(messages)].flatten}.merge!(params))
       set_body_stream(req, StringIO.new(body))
       res = execute(request: req, stream:)
-      LLM::Response.new(res)
-        .extend(LLM::Anthropic::Response::Completion)
+      ResponseAdapter.adapt(res, type: :completion)
         .extend(Module.new { define_method(:__tools__) { tools } })
     end
 
@@ -112,8 +110,7 @@ module LLM
     # @param query [String] The search query.
     # @return [LLM::Response] The response from the LLM provider.
     def web_search(query:)
-      complete(query, tools: [server_tools[:web_search]])
-        .extend(LLM::Anthropic::Response::WebSearch)
+      ResponseAdapter.adapt(complete(query, tools: [server_tools[:web_search]]), type: :web_search)
     end
 
     private

data/lib/llm/providers/deepseek/{format/completion_format.rb → request_adapter/completion.rb}

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
-module LLM::DeepSeek::Format
+module LLM::DeepSeek::RequestAdapter
   ##
   # @private
-  class CompletionFormat
+  class Completion
     ##
     # @param [LLM::Message, Hash] message
     #  The message to format
@@ -12,30 +12,30 @@ module LLM::DeepSeek::Format
     end
 
     ##
-    # Formats the message for the DeepSeek chat completions API
+    # Adapts the message for the DeepSeek chat completions API
     # @return [Hash]
-    def format
+    def adapt
       catch(:abort) do
         if Hash === message
-          {role: message[:role], content: format_content(message[:content])}
+          {role: message[:role], content: adapt_content(message[:content])}
         elsif message.tool_call?
           {role: message.role, content: nil, tool_calls: message.extra[:original_tool_calls]}
         else
-          format_message
+          adapt_message
         end
       end
     end
 
     private
 
-    def format_content(content)
+    def adapt_content(content)
       case content
       when String
         content.to_s
       when LLM::Message
-        format_content(content.content)
+        adapt_content(content.content)
       when LLM::Function::Return
-        throw(:abort, {role: "tool", tool_call_id: content.id, content: JSON.dump(content.value)})
+        throw(:abort, {role: "tool", tool_call_id: content.id, content: LLM.json.dump(content.value)})
       when LLM::Object
         prompt_error!(content)
       else
@@ -43,22 +43,22 @@ module LLM::DeepSeek::Format
       end
     end
 
-    def format_message
+    def adapt_message
       case content
       when Array
-        format_array
+        adapt_array
       else
-        {role: message.role, content: format_content(content)}
+        {role: message.role, content: adapt_content(content)}
       end
     end
 
-    def format_array
+    def adapt_array
       if content.empty?
         nil
       elsif returns.any?
-        returns.map { {role: "tool", tool_call_id: _1.id, content: JSON.dump(_1.value)} }
+        returns.map { {role: "tool", tool_call_id: _1.id, content: LLM.json.dump(_1.value)} }
       else
-        {role: message.role, content: content.flat_map { format_content(_1) }}
+        {role: message.role, content: content.flat_map { adapt_content(_1) }}
       end
     end
 

data/lib/llm/providers/deepseek/{format.rb → request_adapter.rb}

@@ -3,15 +3,15 @@
 class LLM::DeepSeek
   ##
   # @private
-  module Format
-    require_relative "format/completion_format"
+  module RequestAdapter
+    require_relative "request_adapter/completion"
     ##
     # @param [Array<LLM::Message>] messages
-    #  The messages to format
+    #  The messages to adapt
     # @return [Array<Hash>]
-    def format(messages, ...)
+    def adapt(messages, mode: nil)
       messages.filter_map do |message|
-        CompletionFormat.new(message).format
+        Completion.new(message).adapt
       end
     end
 
@@ -20,8 +20,8 @@ class LLM::DeepSeek
     ##
     # @param [Hash] params
     # @return [Hash]
-    def format_tools(tools)
-      (tools.nil? || tools.empty?) ? {} : {tools: tools.map { _1.format(self) }}
+    def adapt_tools(tools)
+      (tools.nil? || tools.empty?) ? {} : {tools: tools.map { _1.adapt(self) }}
     end
   end
 end

data/lib/llm/providers/deepseek.rb

@@ -18,8 +18,8 @@ module LLM
   #   bot.chat ["Tell me about this photo", File.open("/images/cat.jpg", "rb")]
   #   bot.messages.select(&:assistant?).each { print "[#{_1.role}]", _1.content, "\n" }
   class DeepSeek < OpenAI
-    require_relative "deepseek/format"
-    include DeepSeek::Format
+    require_relative "deepseek/request_adapter"
+    include DeepSeek::RequestAdapter
 
     ##
     # @param (see LLM::Provider#initialize)

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

@@ -43,7 +43,7 @@ class LLM::Gemini
       res = @provider.complete [
         "Your task is to transcribe the contents of an audio file",
         "Your response should include the transcription, and nothing else",
-        LLM::Object.from_hash(value: LLM.File(file), kind: :local_file)
+        LLM::Object.from(value: LLM.File(file), kind: :local_file)
       ], params.merge(role: :user, model:)
       res.tap { _1.define_singleton_method(:text) { choices[0].content } }
     end
@@ -65,7 +65,7 @@ class LLM::Gemini
       res = @provider.complete [
         "Your task is to translate the contents of an audio file into English",
         "Your response should include the translation, and nothing else",
-        LLM::Object.from_hash(value: LLM.File(file), kind: :local_file)
+        LLM::Object.from(value: LLM.File(file), kind: :local_file)
       ], params.merge(role: :user, model:)
       res.tap { _1.define_singleton_method(:text) { choices[0].content } }
     end

data/lib/llm/providers/gemini/error_handler.rb

@@ -29,19 +29,19 @@ class LLM::Gemini
         if reason == "API_KEY_INVALID"
           raise LLM::UnauthorizedError.new { _1.response = res }, "Authentication error"
         else
-          raise LLM::ResponseError.new { _1.response = res }, "Unexpected response"
+          raise LLM::Error.new { _1.response = res }, "Unexpected response"
         end
       when Net::HTTPTooManyRequests
         raise LLM::RateLimitError.new { _1.response = res }, "Too many requests"
       else
-        raise LLM::ResponseError.new { _1.response = res }, "Unexpected response"
+        raise LLM::Error.new { _1.response = res }, "Unexpected response"
       end
     end
 
     private
 
     def body
-      @body ||= JSON.parse(res.body)
+      @body ||= LLM.json.load(res.body)
     end
   end
 end

data/lib/llm/providers/gemini/files.rb

@@ -23,9 +23,6 @@ class LLM::Gemini
   #   bot.chat ["Tell me about this file", file]
   #   bot.messages.select(&:assistant?).each { print "[#{_1.role}]", _1.content, "\n" }
   class Files
-    require_relative "response/file"
-    require_relative "response/files"
-
     ##
     # Returns a new Files object
     # @param provider [LLM::Provider]
@@ -50,7 +47,7 @@ class LLM::Gemini
       query = URI.encode_www_form(params.merge!(key: key))
       req = Net::HTTP::Get.new("/v1beta/files?#{query}", headers)
       res = execute(request: req)
-      LLM::Response.new(res).extend(LLM::Gemini::Response::Files)
+      ResponseAdapter.adapt(res, type: :files)
     end
 
     ##
@@ -72,7 +69,7 @@ class LLM::Gemini
       file.with_io do |io|
         set_body_stream(req, io)
         res = execute(request: req)
-        LLM::Response.new(res).extend(LLM::Gemini::Response::File)
+        ResponseAdapter.adapt(res, type: :file)
       end
     end
 
@@ -92,7 +89,7 @@ class LLM::Gemini
       query = URI.encode_www_form(params.merge!(key: key))
       req = Net::HTTP::Get.new("/v1beta/#{file_id}?#{query}", headers)
       res = execute(request: req)
-      LLM::Response.new(res).extend(LLM::Gemini::Response::File)
+      ResponseAdapter.adapt(res, type: :file)
     end
 
     ##
@@ -130,7 +127,7 @@ class LLM::Gemini
       req["X-Goog-Upload-Command"] = "start"
       req["X-Goog-Upload-Header-Content-Length"] = file.bytesize
       req["X-Goog-Upload-Header-Content-Type"] = file.mime_type
-      req.body = JSON.dump(file: {display_name: File.basename(file.path)})
+      req.body = LLM.json.dump(file: {display_name: File.basename(file.path)})
       res = execute(request: req)
       res["x-goog-upload-url"]
     end

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

@@ -15,8 +15,7 @@ class LLM::Gemini
   #   res = llm.images.create prompt: "A dog on a rocket to the moon"
   #   IO.copy_stream res.images[0], "rocket.png"
   class Images
-    require_relative "response/image"
-    include Format
+    include RequestAdapter
 
     ##
     # Returns a new Images object
@@ -37,20 +36,16 @@ class LLM::Gemini
     # @param [Hash] params Other parameters (see Gemini docs)
     # @raise (see LLM::Provider#request)
     # @raise [LLM::NoImageError] when no images are returned
-    # @note
-    #  The prompt should make it clear you want to generate an image, or you
-    #  might unexpectedly receive a purely textual response. This is due to how
-    #  Gemini implements image generation under the hood.
     # @return [LLM::Response]
     def create(prompt:, model: "gemini-2.5-flash-image", **params)
       req  = Net::HTTP::Post.new("/v1beta/models/#{model}:generateContent?key=#{key}", headers)
-      body = JSON.dump({
+      body = LLM.json.dump({
         contents: [{parts: [{text: create_prompt}, {text: prompt}]}],
         generationConfig: {responseModalities: ["TEXT", "IMAGE"]}
       }.merge!(params))
       req.body = body
       res = execute(request: req)
-      validate LLM::Response.new(res).extend(LLM::Gemini::Response::Image)
+      validate ResponseAdapter.adapt(res, type: :image)
     end
 
     ##
@@ -69,14 +64,14 @@ class LLM::Gemini
     # @return [LLM::Response]
     def edit(image:, prompt:, model: "gemini-2.5-flash-image", **params)
       req   = Net::HTTP::Post.new("/v1beta/models/#{model}:generateContent?key=#{key}", headers)
-      image = LLM::Object.from_hash(value: LLM.File(image), kind: :local_file)
-      body  = JSON.dump({
-        contents: [{parts: [{text: edit_prompt}, {text: prompt}, format.format_content(image)]}],
+      image = LLM::Object.from(value: LLM.File(image), kind: :local_file)
+      body  = LLM.json.dump({
+        contents: [{parts: [{text: edit_prompt}, {text: prompt}, adapter.adapt_content(image)]}],
         generationConfig: {responseModalities: ["TEXT", "IMAGE"]}
       }.merge!(params)).b
       set_body_stream(req, StringIO.new(body))
       res = execute(request: req)
-      validate LLM::Response.new(res).extend(LLM::Gemini::Response::Image)
+      validate ResponseAdapter.adapt(res, type: :image)
     end
 
     ##
@@ -88,8 +83,8 @@ class LLM::Gemini
 
     private
 
-    def format
-      @format ||= CompletionFormat.new(nil)
+    def adapter
+      @adapter ||= Completion.new(nil)
     end
 
     def key

data/lib/llm/providers/gemini/models.rb

@@ -17,7 +17,6 @@ class LLM::Gemini
   #     print "id: ", model.id, "\n"
   #   end
   class Models
-    require_relative "response/models"
     include LLM::Utils
 
     ##
@@ -44,7 +43,7 @@ class LLM::Gemini
       query = URI.encode_www_form(params.merge!(key: key))
       req = Net::HTTP::Get.new("/v1beta/models?#{query}", headers)
       res = execute(request: req)
-      LLM::Response.new(res).extend(LLM::Gemini::Response::Models)
+      ResponseAdapter.adapt(res, type: :models)
     end
 
     private

data/lib/llm/providers/gemini/{format/completion_format.rb → request_adapter/completion.rb}

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
-module LLM::Gemini::Format
+module LLM::Gemini::RequestAdapter
   ##
   # @private
-  class CompletionFormat
+  class Completion
     ##
     # @param [LLM::Message, Hash] message
     #  The message to format
@@ -12,40 +12,40 @@ module LLM::Gemini::Format
     end
 
     ##
-    # Formats the message for the Gemini chat completions API
+    # Adapts the message for the Gemini chat completions API
     # @return [Hash]
-    def format
+    def adapt
       catch(:abort) do
         if Hash === message
-          {role: message[:role], parts: format_content(message[:content])}
+          {role: message[:role], parts: adapt_content(message[:content])}
         elsif message.tool_call?
           {role: message.role, parts: message.extra[:original_tool_calls].map { {"functionCall" => _1} }}
         else
-          {role: message.role, parts: format_content(message.content)}
+          {role: message.role, parts: adapt_content(message.content)}
         end
       end
     end
 
-    def format_content(content)
+    def adapt_content(content)
       case content
       when Array
-        content.empty? ? throw(:abort, nil) : content.flat_map { format_content(_1) }
+        content.empty? ? throw(:abort, nil) : content.flat_map { adapt_content(_1) }
       when String
         [{text: content}]
       when LLM::Response
-        format_remote_file(content)
+        adapt_remote_file(content)
       when LLM::Message
-        format_content(content.content)
+        adapt_content(content.content)
       when LLM::Function::Return
         [{functionResponse: {name: content.name, response: content.value}}]
       when LLM::Object
-        format_object(content)
+        adapt_object(content)
       else
         prompt_error!(content)
       end
     end
 
-    def format_object(object)
+    def adapt_object(object)
       case object.kind
       when :image_url
         [{file_data: {mime_type: "image/*", file_uri: object.value.to_s}}]
@@ -53,13 +53,13 @@ module LLM::Gemini::Format
         file = object.value
         [{inline_data: {mime_type: file.mime_type, data: file.to_b64}}]
       when :remote_file
-        format_remote_file(object.value)
+        adapt_remote_file(object.value)
       else
         prompt_error!(object)
       end
     end
 
-    def format_remote_file(file)
+    def adapt_remote_file(file)
       return prompt_error!(file) unless file.file?
       [{file_data: {mime_type: file.mime_type, file_uri: file.uri}}]
     end

data/lib/llm/providers/gemini/{format.rb → request_adapter.rb}

@@ -3,16 +3,16 @@
 class LLM::Gemini
   ##
   # @private
-  module Format
-    require_relative "format/completion_format"
+  module RequestAdapter
+    require_relative "request_adapter/completion"
 
     ##
     # @param [Array<LLM::Message>] messages
-    #  The messages to format
+    #  The messages to adapt
     # @return [Array<Hash>]
-    def format(messages)
+    def adapt(messages, mode: nil)
       messages.filter_map do |message|
-        CompletionFormat.new(message).format
+        Completion.new(message).adapt
       end
     end
 
@@ -21,7 +21,7 @@ class LLM::Gemini
     ##
     # @param [Hash] params
     # @return [Hash]
-    def format_schema(params)
+    def adapt_schema(params)
       return {} unless params and params[:schema]
       schema = params.delete(:schema)
       schema = schema.respond_to?(:object) ? schema.object : schema
@@ -31,10 +31,10 @@ class LLM::Gemini
     ##
     # @param [Hash] params
     # @return [Hash]
-    def format_tools(tools)
+    def adapt_tools(tools)
       return {} unless tools&.any?
       platform, functions = [tools.grep(LLM::ServerTool), tools.grep(LLM::Function)]
-      {tools: [*platform, {functionDeclarations: functions.map { _1.format(self) }}]}
+      {tools: [*platform, {functionDeclarations: functions.map { _1.adapt(self) }}]}
     end
   end
 end

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

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module LLM::Gemini::ResponseAdapter
+  module Completion
+    ##
+    # (see LLM::Contract::Completion#messages)
+    def messages
+      adapt_choices
+    end
+    alias_method :choices, :messages
+
+    ##
+    # (see LLM::Contract::Completion#input_tokens)
+    def input_tokens
+      body.usageMetadata.promptTokenCount || 0
+    end
+
+    ##
+    # (see LLM::Contract::Completion#output_tokens)
+    def output_tokens
+      body.usageMetadata.candidatesTokenCount || 0
+    end
+
+    ##
+    # (see LLM::Contract::Completion#total_tokens)
+    def total_tokens
+      body.usageMetadata.totalTokenCount || 0
+    end
+
+    ##
+    # (see LLM::Contract::Completion#usage)
+    def usage
+      super
+    end
+
+    ##
+    # (see LLM::Contract::Completion#model)
+    def model
+      body.modelVersion
+    end
+
+    private
+
+    def adapt_choices
+      candidates.map.with_index do |choice, index|
+        content = choice.content || LLM::Object.new
+        role = content.role || "model"
+        parts = content.parts || [{"text" => choice.finishReason}]
+        text  = parts.filter_map { _1["text"] }.join
+        tools = parts.filter_map { _1["functionCall"] }
+        extra = {index:, response: self, tool_calls: adapt_tool_calls(tools), original_tool_calls: tools}
+        LLM::Message.new(role, text, extra)
+      end
+    end
+
+    def adapt_tool_calls(tools)
+      (tools || []).map do |tool|
+        function = {name: tool.name, arguments: tool.args}
+        function
+      end
+    end
+
+    def candidates = body.candidates || []
+
+    include LLM::Contract::Completion
+  end
+end

data/lib/llm/providers/gemini/{response → response_adapter}/embedding.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module LLM::Gemini::Response
+module LLM::Gemini::ResponseAdapter
   module Embedding
     def model = "text-embedding-004"
     def embeddings = body.dig("embedding", "values")

data/lib/llm/providers/gemini/{response → response_adapter}/file.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module LLM::Gemini::Response
+module LLM::Gemini::ResponseAdapter
   module File
     def name = respond_to?(:file) ? file.name : body.name
     def display_name = respond_to?(:file) ? file.displayName : body.displayName

data/lib/llm/providers/gemini/{response → response_adapter}/files.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module LLM::Gemini::Response
+module LLM::Gemini::ResponseAdapter
   module Files
     include ::Enumerable
     def each(&)

data/lib/llm/providers/gemini/{response → response_adapter}/image.rb

@@ -1,14 +1,14 @@
 # frozen_string_literal: true
 
-module LLM::Gemini::Response
+module LLM::Gemini::ResponseAdapter
   module Image
     ##
     # @return [Array<StringIO>]
     def images
       candidates.flat_map do |candidate|
-        parts = candidate&.dig(:content, :parts) || []
+        parts = candidate&.dig("content", "parts") || []
         parts.filter_map do
-          data = _1.dig(:inlineData, :data)
+          data = _1.dig("inlineData", "data")
           next unless data
           StringIO.new(data.unpack1("m0"))
         end

data/lib/llm/providers/gemini/{response → response_adapter}/models.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module LLM::Gemini::Response
+module LLM::Gemini::ResponseAdapter
   module Models
     include ::Enumerable
     def each(&)

data/lib/llm/providers/gemini/{response → response_adapter}/web_search.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
-module LLM::Gemini::Response
+module LLM::Gemini::ResponseAdapter
   ##
-  # The {LLM::Gemini::Response::WebSearch LLM::Gemini::Response::WebSearch}
+  # The {LLM::Gemini::ResponseAdapter::WebSearch LLM::Gemini::ResponseAdapter::WebSearch}
   # module provides methods for accessing web search results from a web search
   # tool call made via the {LLM::Provider#web_search LLM::Provider#web_search}
   # method.
@@ -11,7 +11,7 @@ module LLM::Gemini::Response
     # Returns one or more search results
     # @return [Array<LLM::Object>]
     def search_results
-      LLM::Object.from_hash(
+      LLM::Object.from(
         candidates[0]
           .groundingMetadata
           .groundingChunks

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

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+class LLM::Gemini
+  ##
+  # @private
+  module ResponseAdapter
+    require_relative "response_adapter/completion"
+    require_relative "response_adapter/embedding"
+    require_relative "response_adapter/file"
+    require_relative "response_adapter/files"
+    require_relative "response_adapter/image"
+    require_relative "response_adapter/models"
+    require_relative "response_adapter/web_search"
+
+    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)
+      response.extend(select(type))
+    end
+
+    ##
+    # @api private
+    def select(type)
+      case type
+      when :completion then LLM::Gemini::ResponseAdapter::Completion
+      when :embedding then LLM::Gemini::ResponseAdapter::Embedding
+      when :file then LLM::Gemini::ResponseAdapter::File
+      when :files then LLM::Gemini::ResponseAdapter::Files
+      when :image then LLM::Gemini::ResponseAdapter::Image
+      when :models then LLM::Gemini::ResponseAdapter::Models
+      when :web_search then LLM::Gemini::ResponseAdapter::WebSearch
+      else
+        raise ArgumentError, "Unknown response adapter type: #{type.inspect}"
+      end
+    end
+  end
+end