llm.rb 4.8.0 → 4.10.0

data/lib/llm/provider.rb

@@ -50,6 +50,15 @@ class LLM::Provider
     "#<#{self.class.name}:0x#{object_id.to_s(16)} @key=[REDACTED] @client=#{@client.inspect} @tracer=#{tracer.inspect}>"
   end
 
+  ##
+  # @raise [NotImplementedError]
+  #  When the method is not implemented by a subclass
+  # @return [Symbol]
+  #  Returns the provider's name
+  def name
+    raise NotImplementedError
+  end
+
   ##
   # Provides an embedding
   # @param [String, Array<String>] input
@@ -93,10 +102,10 @@ class LLM::Provider
   # Starts a new chat powered by the chat completions API
   # @param prompt (see LLM::Provider#complete)
   # @param params (see LLM::Provider#complete)
-  # @return [LLM::Session]
+  # @return [LLM::Context]
   def chat(prompt, params = {})
     role = params.delete(:role)
-    LLM::Session.new(self, params).talk(prompt, role:)
+    LLM::Context.new(self, params).talk(prompt, role:)
   end
 
   ##
@@ -104,10 +113,10 @@ class LLM::Provider
   # @param prompt (see LLM::Provider#complete)
   # @param params (see LLM::Provider#complete)
   # @raise (see LLM::Provider#complete)
-  # @return [LLM::Session]
+  # @return [LLM::Context]
   def respond(prompt, params = {})
     role = params.delete(:role)
-    LLM::Session.new(self, params).respond(prompt, role:)
+    LLM::Context.new(self, params).respond(prompt, role:)
   end
 
   ##
@@ -122,7 +131,7 @@ class LLM::Provider
   end
 
   ##
-  # @return [LLM::OpenAI::Images, LLM::Gemini::Images]
+  # @return [LLM::OpenAI::Images, LLM::Google::Images]
   #  Returns an interface to the images API
   def images
     raise NotImplementedError
@@ -264,13 +273,13 @@ class LLM::Provider
 
   ##
   # @return [LLM::Tracer]
-  #  Returns a thread-local tracer
+  #  Returns a fiber-local tracer
   def tracer
     weakmap[self] || LLM::Tracer::Null.new(self)
   end
 
   ##
-  # Set a thread-local tracer
+  # Set a fiber-local tracer
   # @example
   #   llm = LLM.openai(key: ENV["KEY"])
   #   Thread.new do
@@ -367,16 +376,22 @@ class LLM::Provider
     args = (Net::HTTP === http) ? [request] : [URI.join(base_uri, request.path), request]
     res = if stream
       http.request(*args) do |res|
-        handler = event_handler.new stream_parser.new(stream)
-        parser = LLM::EventStream::Parser.new
-        parser.register(handler)
-        res.read_body(parser)
-        # If the handler body is empty, the response was
-        # most likely not streamed or parsing failed.
-        # Preserve the raw body in that case so standard
-        # JSON/error handling can parse it later.
-        body = handler.body.empty? ? parser.body : handler.body
-        res.body = Hash === body || Array === body ? LLM::Object.from(body) : body
+        if Net::HTTPSuccess === res
+          handler = event_handler.new stream_parser.new(stream)
+          parser = LLM::EventStream::Parser.new
+          parser.register(handler)
+          res.read_body(parser)
+          # If the handler body is empty, the response was
+          # most likely not streamed or parsing failed.
+          # Preserve the raw body in that case so standard
+          # JSON/error handling can parse it later.
+          body = handler.body.empty? ? parser.body : handler.body
+          res.body = Hash === body || Array === body ? LLM::Object.from(body) : body
+        else
+          body = +""
+          res.read_body { body << _1 }
+          res.body = body
+        end
       ensure
         parser&.free
       end

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

@@ -10,10 +10,10 @@ class LLM::Anthropic
   #   require "llm"
   #
   #   llm = LLM.anthropic(key: ENV["KEY"])
-  #   ses = LLM::Session.new(llm)
+  #   ctx = LLM::Context.new(llm)
   #   file = llm.files.create file: "/books/goodread.pdf"
-  #   ses.talk ["Tell me about this PDF", file]
-  #   ses.messages.select(&:assistant?).each { print "[#{_1.role}]", _1.content, "\n" }
+  #   ctx.talk ["Tell me about this PDF", file]
+  #   ctx.messages.select(&:assistant?).each { print "[#{_1.role}]", _1.content, "\n" }
   class Files
     ##
     # Returns a new Files object

data/lib/llm/providers/anthropic.rb

@@ -10,9 +10,9 @@ module LLM
   #   require "llm"
   #
   #   llm = LLM.anthropic(key: ENV["KEY"])
-  #   ses = LLM::Session.new(llm)
-  #   ses.talk ["Tell me about this photo", ses.local_file("/images/photo.png")]
-  #   ses.messages.select(&:assistant?).each { print "[#{_1.role}]", _1.content, "\n" }
+  #   ctx = LLM::Context.new(llm)
+  #   ctx.talk ["Tell me about this photo", ctx.local_file("/images/photo.png")]
+  #   ctx.messages.select(&:assistant?).each { print "[#{_1.role}]", _1.content, "\n" }
   class Anthropic < Provider
     require_relative "anthropic/error_handler"
     require_relative "anthropic/request_adapter"
@@ -30,6 +30,13 @@ module LLM
       super(host: HOST, **)
     end
 
+    ##
+    # @return [Symbol]
+    #  Returns the provider's name
+    def name
+      :anthropic
+    end
+
     ##
     # Provides an interface to the chat completions API
     # @see https://docs.anthropic.com/en/api/messages Anthropic docs
@@ -139,12 +146,20 @@ module LLM
     end
 
     def build_complete_request(prompt, params, role)
-      messages = [*(params.delete(:messages) || []), Message.new(role, prompt)]
+      messages = build_complete_messages(prompt, params, role)
       payload = adapt(messages)
       body = LLM.json.dump(payload.merge!(params))
       req = Net::HTTP::Post.new("/v1/messages", headers)
       set_body_stream(req, StringIO.new(body))
       req
     end
+
+    def build_complete_messages(prompt, params, role)
+      if LLM::Prompt === prompt
+        [*(params.delete(:messages) || []), *prompt.to_a]
+      else
+        [*(params.delete(:messages) || []), Message.new(role, prompt)]
+      end
+    end
   end
 end

data/lib/llm/providers/deepseek.rb

@@ -14,9 +14,9 @@ module LLM
   #   require "llm"
   #
   #   llm = LLM.deepseek(key: ENV["KEY"])
-  #   ses = LLM::Session.new(llm)
-  #   ses.talk ["Tell me about this photo", ses.local_file("/images/photo.png")]
-  #   ses.messages.select(&:assistant?).each { print "[#{_1.role}]", _1.content, "\n" }
+  #   ctx = LLM::Context.new(llm)
+  #   ctx.talk ["Tell me about this photo", ctx.local_file("/images/photo.png")]
+  #   ctx.messages.select(&:assistant?).each { print "[#{_1.role}]", _1.content, "\n" }
   class DeepSeek < OpenAI
     require_relative "deepseek/request_adapter"
     include DeepSeek::RequestAdapter
@@ -28,6 +28,13 @@ module LLM
       super
     end
 
+    ##
+    # @return [Symbol]
+    #  Returns the provider's name
+    def name
+      :deepseek
+    end
+
     ##
     # @raise [NotImplementedError]
     def files

data/lib/llm/providers/{gemini → google}/audio.rb

@@ -1,21 +1,21 @@
 # frozen_string_literal: true
 
-class LLM::Gemini
+class LLM::Google
   ##
-  # The {LLM::Gemini::Audio LLM::Gemini::Audio} class provides an audio
+  # The {LLM::Google::Audio LLM::Google::Audio} class provides an audio
   # object for interacting with [Gemini's audio API](https://ai.google.dev/gemini-api/docs/audio).
   # @example
   #   #!/usr/bin/env ruby
   #   require "llm"
   #
-  #   llm = LLM.gemini(key: ENV["KEY"])
+  #   llm = LLM.google(key: ENV["KEY"])
   #   res = llm.audio.create_transcription(input: "/audio/rocket.mp3")
   #   res.text # => "A dog on a rocket to the moon"
   class Audio
     ##
     # Returns a new Audio object
     # @param provider [LLM::Provider]
-    # @return [LLM::Gemini::Responses]
+    # @return [LLM::Google::Audio]
     def initialize(provider)
       @provider = provider
     end
@@ -30,7 +30,7 @@ class LLM::Gemini
     ##
     # Create an audio transcription
     # @example
-    #   llm = LLM.gemini(key: ENV["KEY"])
+    #   llm = LLM.google(key: ENV["KEY"])
     #   res = llm.audio.create_transcription(file: "/audio/rocket.mp3")
     #   res.text # => "A dog on a rocket to the moon"
     # @see https://ai.google.dev/gemini-api/docs/audio Gemini docs
@@ -52,7 +52,7 @@ class LLM::Gemini
     # Create an audio translation (in English)
     # @example
     #   # Arabic => English
-    #   llm = LLM.gemini(key: ENV["KEY"])
+    #   llm = LLM.google(key: ENV["KEY"])
     #   res = llm.audio.create_translation(file: "/audio/bismillah.mp3")
     #   res.text # => "In the name of Allah, the Beneficent, the Merciful."
     # @see https://ai.google.dev/gemini-api/docs/audio Gemini docs

data/lib/llm/providers/{gemini → google}/error_handler.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-class LLM::Gemini
+class LLM::Google
   ##
   # @private
   class ErrorHandler
@@ -21,7 +21,7 @@ class LLM::Gemini
     #  The span
     # @param [Net::HTTPResponse] res
     #  The response from the server
-    # @return [LLM::Gemini::ErrorHandler]
+    # @return [LLM::Google::ErrorHandler]
     def initialize(tracer, span, res)
       @tracer = tracer
       @span = span

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

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
-class LLM::Gemini
+class LLM::Google
   ##
-  # The {LLM::Gemini::Files LLM::Gemini::Files} class provides a files
+  # The {LLM::Google::Files LLM::Google::Files} class provides a files
   # object for interacting with [Gemini's Files API](https://ai.google.dev/gemini-api/docs/files).
   # The files API allows a client to reference media files in prompts
   # where they can be referenced by their URL.
@@ -17,16 +17,16 @@ class LLM::Gemini
   #   #!/usr/bin/env ruby
   #   require "llm"
   #
-  #   llm = LLM.gemini(key: ENV["KEY"])
-  #   ses = LLM::Session.new(llm)
+  #   llm = LLM.google(key: ENV["KEY"])
+  #   ctx = LLM::Context.new(llm)
   #   file = llm.files.create(file: "/audio/haiku.mp3")
-  #   ses.talk ["Tell me about this file", file]
-  #   ses.messages.select(&:assistant?).each { print "[#{_1.role}]", _1.content, "\n" }
+  #   ctx.talk ["Tell me about this file", file]
+  #   ctx.messages.select(&:assistant?).each { print "[#{_1.role}]", _1.content, "\n" }
   class Files
     ##
     # Returns a new Files object
     # @param provider [LLM::Provider]
-    # @return [LLM::Gemini::Files]
+    # @return [LLM::Google::Files]
     def initialize(provider)
       @provider = provider
     end
@@ -34,7 +34,7 @@ class LLM::Gemini
     ##
     # List all files
     # @example
-    #   llm = LLM.gemini(key: ENV["KEY"])
+    #   llm = LLM.google(key: ENV["KEY"])
     #   res = llm.files.all
     #   res.each do |file|
     #     print "name: ", file.name, "\n"
@@ -55,7 +55,7 @@ class LLM::Gemini
     ##
     # Create a file
     # @example
-    #   llm = LLM.gemini(key: ENV["KEY"])
+    #   llm = LLM.google(key: ENV["KEY"])
     #   res = llm.files.create(file: "/audio/haiku.mp3")
     # @see https://ai.google.dev/gemini-api/docs/files Gemini docs
     # @param [String, LLM::File] file The file
@@ -80,7 +80,7 @@ class LLM::Gemini
     ##
     # Get a file
     # @example
-    #   llm = LLM.gemini(key: ENV["KEY"])
+    #   llm = LLM.google(key: ENV["KEY"])
     #   res = llm.files.get(file: "files/1234567890")
     #   print "name: ", res.name, "\n"
     # @see https://ai.google.dev/gemini-api/docs/files Gemini docs
@@ -101,7 +101,7 @@ class LLM::Gemini
     ##
     # Delete a file
     # @example
-    #   llm = LLM.gemini(key: ENV["KEY"])
+    #   llm = LLM.google(key: ENV["KEY"])
     #   res = llm.files.delete(file: "files/1234567890")
     # @see https://ai.google.dev/gemini-api/docs/files Gemini docs
     # @param [#name, String] file The file to delete

data/lib/llm/providers/{gemini → google}/images.rb

@@ -1,15 +1,15 @@
 # frozen_string_literal: true
 
-class LLM::Gemini
+class LLM::Google
   ##
-  # The {LLM::Gemini::Images LLM::Gemini::Images} class provides an images
+  # The {LLM::Google::Images LLM::Google::Images} class provides an images
   # object for interacting with Google's Imagen text-to-image models via the
   # Imagen API: https://ai.google.dev/gemini-api/docs/imagen
   #
   # @example
   #   #!/usr/bin/env ruby
   #   require "llm"
-  #   llm = LLM.gemini(key: ENV["KEY"])
+  #   llm = LLM.google(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
@@ -18,7 +18,7 @@ class LLM::Gemini
     ##
     # Returns a new Images object
     # @param provider [LLM::Provider]
-    # @return [LLM::Gemini::Responses]
+    # @return [LLM::Google::Images]
     def initialize(provider)
       @provider = provider
     end
@@ -26,7 +26,7 @@ class LLM::Gemini
     ##
     # Create an image
     # @example
-    #   llm = LLM.gemini(key: ENV["KEY"])
+    #   llm = LLM.google(key: ENV["KEY"])
     #   res = llm.images.create prompt: "A dog on a rocket to the moon"
     #   IO.copy_stream res.images[0], "rocket.png"
     # @see https://ai.google.dev/gemini-api/docs/imagen Imagen docs
@@ -60,7 +60,7 @@ class LLM::Gemini
     ##
     # Edit an image
     # @example
-    #   llm = LLM.gemini(key: ENV["KEY"])
+    #   llm = LLM.google(key: ENV["KEY"])
     #   res = llm.images.edit image: "cat.png", prompt: "Add a hat to the cat"
     #   IO.copy_stream res.images[0], "hatoncat.png"
     # @see https://ai.google.dev/gemini-api/docs/image-generation Gemini docs
@@ -68,7 +68,7 @@ class LLM::Gemini
     # @param [String] prompt The prompt
     # @param [Hash] params Other parameters (see Gemini docs)
     # @raise (see LLM::Provider#request)
-    # @note (see LLM::Gemini::Images#create)
+    # @note (see LLM::Google::Images#create)
     # @return [LLM::Response]
     def edit(image:, prompt:, model: "gemini-2.5-flash-image", **params)
       raise NotImplementedError, "image editing is not yet supported by Gemini"

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

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
-class LLM::Gemini
+class LLM::Google
   ##
-  # The {LLM::Gemini::Models LLM::Gemini::Models} class provides a model
+  # The {LLM::Google::Models LLM::Google::Models} class provides a model
   # object for interacting with [Gemini's models API](https://ai.google.dev/api/models?hl=en#method:-models.list).
   # The models API allows a client to query Gemini for a list of models
   # that are available for use with the Gemini API.
@@ -11,7 +11,7 @@ class LLM::Gemini
   #   #!/usr/bin/env ruby
   #   require "llm"
   #
-  #   llm = LLM.gemini(key: ENV["KEY"])
+  #   llm = LLM.google(key: ENV["KEY"])
   #   res = llm.models.all
   #   res.each do |model|
   #     print "id: ", model.id, "\n"
@@ -22,7 +22,7 @@ class LLM::Gemini
     ##
     # Returns a new Models object
     # @param provider [LLM::Provider]
-    # @return [LLM::Gemini::Models]
+    # @return [LLM::Google::Models]
     def initialize(provider)
       @provider = provider
     end
@@ -30,7 +30,7 @@ class LLM::Gemini
     ##
     # List all models
     # @example
-    #   llm = LLM.gemini(key: ENV["KEY"])
+    #   llm = LLM.google(key: ENV["KEY"])
     #   res = llm.models.all
     #   res.each do |model|
     #     print "id: ", model.id, "\n"

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

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module LLM::Gemini::RequestAdapter
+module LLM::Google::RequestAdapter
   ##
   # @private
   class Completion
@@ -19,7 +19,7 @@ module LLM::Gemini::RequestAdapter
         if Hash === message
           {role: message[:role], parts: adapt_content(message[:content])}
         elsif message.tool_call?
-          {role: message.role, parts: message.extra[:original_tool_calls].map { {"functionCall" => _1} }}
+          {role: message.role, parts: message.extra.original_tool_calls}
         else
           {role: message.role, parts: adapt_content(message.content)}
         end
@@ -37,7 +37,7 @@ module LLM::Gemini::RequestAdapter
       when LLM::Message
         adapt_content(content.content)
       when LLM::Function::Return
-        [{functionResponse: {name: content.name, response: content.value}}]
+        [{functionResponse: {name: content.name, response: adapt_function_response(content.value)}}]
       when LLM::Object
         adapt_object(content)
       else
@@ -64,6 +64,10 @@ module LLM::Gemini::RequestAdapter
       [{file_data: {mime_type: file.mime_type, file_uri: file.uri}}]
     end
 
+    def adapt_function_response(value)
+      Hash === value ? value : {result: value}
+    end
+
     def prompt_error!(object)
       if LLM::Object === object
         raise LLM::PromptError, "The given LLM::Object with kind '#{content.kind}' is not " \

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

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-class LLM::Gemini
+class LLM::Google
   ##
   # @private
   module RequestAdapter

data/lib/llm/providers/{gemini → google}/response_adapter/completion.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module LLM::Gemini::ResponseAdapter
+module LLM::Google::ResponseAdapter
   module Completion
     ##
     # (see LLM::Contract::Completion#messages)
@@ -64,17 +64,17 @@ module LLM::Gemini::ResponseAdapter
         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"] }
+        text = parts.filter_map { _1["text"] }.join
+        tools = parts.select { _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
+    def adapt_tool_calls(parts)
+      (parts || []).map do |part|
+        tool = part["functionCall"]
+        {name: tool.name, arguments: tool.args}
       end
     end
 

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

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

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

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module LLM::Gemini::ResponseAdapter
+module LLM::Google::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 → google}/response_adapter/files.rb

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

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

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module LLM::Gemini::ResponseAdapter
+module LLM::Google::ResponseAdapter
   module Image
     ##
     # @return [Array<StringIO>]

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

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module LLM::Gemini::ResponseAdapter
+module LLM::Google::ResponseAdapter
   module Models
     include LLM::Model::Collection
 

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

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
-module LLM::Gemini::ResponseAdapter
+module LLM::Google::ResponseAdapter
   ##
-  # The {LLM::Gemini::ResponseAdapter::WebSearch LLM::Gemini::ResponseAdapter::WebSearch}
+  # The {LLM::Google::ResponseAdapter::WebSearch LLM::Google::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.

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

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-class LLM::Gemini
+class LLM::Google
   ##
   # @private
   module ResponseAdapter
@@ -27,13 +27,13 @@ class LLM::Gemini
     # @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
+      when :completion then LLM::Google::ResponseAdapter::Completion
+      when :embedding then LLM::Google::ResponseAdapter::Embedding
+      when :file then LLM::Google::ResponseAdapter::File
+      when :files then LLM::Google::ResponseAdapter::Files
+      when :image then LLM::Google::ResponseAdapter::Image
+      when :models then LLM::Google::ResponseAdapter::Models
+      when :web_search then LLM::Google::ResponseAdapter::WebSearch
       else
         raise ArgumentError, "Unknown response adapter type: #{type.inspect}"
       end

data/lib/llm/providers/{gemini → google}/stream_parser.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-class LLM::Gemini
+class LLM::Google
   ##
   # @private
   class StreamParser
@@ -11,7 +11,7 @@ class LLM::Gemini
 
     ##
     # @param [#<<] io An IO-like object
-    # @return [LLM::Gemini::StreamParser]
+    # @return [LLM::Google::StreamParser]
     def initialize(io)
       @body = {"candidates" => []}
       @io = io
@@ -19,7 +19,7 @@ class LLM::Gemini
 
     ##
     # @param [Hash] chunk
-    # @return [LLM::Gemini::StreamParser]
+    # @return [LLM::Google::StreamParser]
     def parse!(chunk)
       tap { merge_chunk!(chunk) }
     end