llm.rb 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9073b7495fb9bdad2deec1d2c086b6d3b554c5a440dd884108a2fa8d12f7c8a9
-  data.tar.gz: 514902fc97de61dc18df8c22d51d9e86472a62e1ffb0c4ce4394b0684cddbd8a
+  metadata.gz: 3939075c064b4abfd8853c3f67b6db7df6111d340d658d4d8ad0c4d1bccc96bc
+  data.tar.gz: 0ca274d3e4b032c25730aef896df903681c28033ebb0907c965339a33aff56d1
 SHA512:
-  metadata.gz: 0d0c35fa38ed3481872e29131d15e03e5a4bf0ad8a96c42ba64a5f48ed32584973d39b53ca630c966d54b6700a83a44abb1f4224c1bb9c1ca7f9e7a2d953e1c3
-  data.tar.gz: 8889034558c56a2bc1ff5321cf0ca45d82ac83ac7122c741e859caed7d060b34b99824cc53d20a5add4949dd135cf65c383f8400e7c112a44110fc1d4e0d2f4d
+  metadata.gz: feaf87457b8fa5b4f756a5fe8cc1f670c8b0286a730fe00273bc99678092fe7f704d58f01ba0a0baf4072a0dcee063bc87cf88bc7cdf53125334476adbce41f6
+  data.tar.gz: 3be8b460d9b483c0e172d9159b2394ea39da7a1475aee3ab47b224303e2a251f3b04f0543402494485040998225f84342be986db8c7b8ea80df92f561d4d6d92

data/README.md

@@ -3,7 +3,9 @@
 llm.rb is a lightweight library that provides a common interface
 and set of functionality for multiple Large Language Models (LLMs). It
 is designed to be simple, flexible, and easy to use – and it has been
-implemented with no dependencies outside Ruby's standard library.
+implemented with zero dependencies outside Ruby's standard library. See the
+[philosophy](#philosophy) section for more information on the design principles
+behind llm.rb.
 
 ## Examples
 
@@ -110,7 +112,7 @@ bot.messages.each { print "[#{_1.role}] ", _1.content, "\n" }
 #### Speech
 
 Some but not all providers implement audio generation capabilities that
-can create text from speech, transcribe audio to text, or translate
+can create speech from text, transcribe audio to text, or translate
 audio to text (usually English). The following example uses the OpenAI provider
 to create an audio file from a text prompt. The audio is then moved to
 `${HOME}/hello.mp3` as the final step. As always, consult the provider's
@@ -193,7 +195,7 @@ print res.text, "\n" # => "Good morning."
 
 #### Create
 
-Some but all LLM providers implement image generation capabilities that
+Some but not all LLM providers implement image generation capabilities that
 can create new images from a prompt, or edit an existing image with a
 prompt. The following example uses the OpenAI provider to create an
 image of a dog on a rocket to the moon. The image is then moved to
@@ -282,6 +284,42 @@ res.urls.each.with_index do |url, index|
 end
 ```
 
+### Files
+
+#### Create
+
+Most LLM providers provide a Files API where you can upload files
+that can be referenced from a prompt and llm.rb has first-class support
+for this feature. The following example uses the OpenAI provider to describe
+the contents of a PDF file after it has been uploaded. The file (an instance
+of [LLM::Response::File](https://0x1eef.github.io/x/llm.rb/LLM/Response/File.html))
+is passed directly to the chat method, and generally any object a prompt supports
+can be given to the chat method.
+
+Please also see provider-specific documentation for more provider-specific
+examples and documentation
+(eg
+[LLM::Gemini::Files](https://0x1eef.github.io/x/llm.rb/LLM/Gemini/Files.html),
+[LLM::OpenAI::Files](https://0x1eef.github.io/x/llm.rb/LLM/OpenAI/Files.html)):
+
+```ruby
+#!/usr/bin/env ruby
+require "llm"
+
+llm = LLM.openai(ENV["KEY"])
+bot = LLM::Chat.new(llm).lazy
+file = llm.files.create(file: LLM::File("/documents/openbsd_is_awesome.pdf"))
+bot.chat(file)
+bot.chat("What is this file about?")
+bot.messages.select(&:assistant?).each { print "[#{_1.role}] ", _1.content, "\n" }
+
+##
+# [assistant] This file is about OpenBSD, a free and open-source Unix-like operating system
+#             based on the Berkeley Software Distribution (BSD). It is known for its
+#             emphasis on security, code correctness, and code simplicity. The file
+#             contains information about the features, installation, and usage of OpenBSD.
+```
+
 ### Embeddings
 
 #### Text
@@ -354,6 +392,22 @@ llm.rb can be installed via rubygems.org:
 
 	gem install llm.rb
 
+## Philosophy
+
+llm.rb was built for developers who believe that simplicity is strength.
+It provides a clean, dependency-free interface to Large Language Models,
+treating Ruby itself as the primary platform – not Rails or any other
+specific framework or library. There is no hidden magic or extreme
+metaprogramming.
+
+Every part of llm.rb is designed to be explicit, composable, memory-safe,
+and production-ready without compromise. No unnecessary abstractions,
+no global configuration, and no dependencies that aren't part of standard
+Ruby. It has been inspired in part by other languages such as Python, but
+it is not a port of any other library.
+
+Good software doesn’t need marketing. It just needs to work. :)
+
 ## License
 
 [BSD Zero Clause](https://choosealicense.com/licenses/0bsd/)

data/lib/llm/error.rb

@@ -10,7 +10,7 @@ module LLM
 
     ##
     # The superclass of all HTTP protocol errors
-    class BadResponse < Error
+    class ResponseError < Error
       ##
       # @return [Net::HTTPResponse]
       #  Returns the response associated with an error
@@ -19,10 +19,10 @@ module LLM
 
     ##
     # HTTPUnauthorized
-    Unauthorized = Class.new(BadResponse)
+    Unauthorized = Class.new(ResponseError)
 
     ##
     # HTTPTooManyRequests
-    RateLimit = Class.new(BadResponse)
+    RateLimit = Class.new(ResponseError)
   end
 end

data/lib/llm/file.rb

@@ -41,6 +41,16 @@ class LLM::File
   def to_b64
     [File.binread(path)].pack("m0")
   end
+
+  ##
+  # @return [File]
+  #  Yields an IO object suitable to be streamed
+  def with_io
+    io = File.open(path, "rb")
+    yield(io)
+  ensure
+    io.close
+  end
 end
 
 ##

data/lib/llm/message.rb

@@ -50,6 +50,13 @@ module LLM
     end
     alias_method :eql?, :==
 
+    ##
+    # Returns true when the message is from the LLM
+    # @return [Boolean]
+    def assistant?
+      role == "assistant" || role == "model"
+    end
+
     ##
     # Returns a string representation of the message
     # @return [String]

data/lib/llm/multipart.rb

@@ -45,7 +45,9 @@ class LLM::Multipart
   # Returns the multipart request body
   # @return [String]
   def body
-    [*parts, "--#{@boundary}--\r\n"].inject(&:<<)
+    io = StringIO.new("".b)
+    [*parts, StringIO.new("--#{@boundary}--\r\n".b)].each { IO.copy_stream(_1.tap(&:rewind), io) }
+    io.tap(&:rewind)
   end
 
   private
@@ -61,7 +63,7 @@ class LLM::Multipart
 
   def multipart_header(type:, locals:)
     if type == :file
-      str = "".b
+      str = StringIO.new("".b)
       str << "--#{locals[:boundary]}" \
              "\r\n" \
              "Content-Disposition: form-data; name=\"#{locals[:key]}\";" \
@@ -70,7 +72,7 @@ class LLM::Multipart
              "Content-Type: #{locals[:content_type]}" \
              "\r\n\r\n"
     elsif type == :data
-      str = "".b
+      str = StringIO.new("".b)
       str << "--#{locals[:boundary]}" \
              "\r\n" \
              "Content-Disposition: form-data; name=\"#{locals[:key]}\"" \
@@ -82,17 +84,17 @@ class LLM::Multipart
 
   def file_part(key, file, locals)
     locals = locals.merge(attributes(file))
-    multipart_header(type: :file, locals:).tap do
-      _1 << File.binread(file.path)
-      _1 << "\r\n"
+    multipart_header(type: :file, locals:).tap do |io|
+      IO.copy_stream(file.path, io)
+      io << "\r\n"
     end
   end
 
   def data_part(key, value, locals)
     locals = locals.merge(value:)
-    multipart_header(type: :data, locals:).tap do
-      _1 << value.to_s
-      _1 << "\r\n"
+    multipart_header(type: :data, locals:).tap do |io|
+      io << value.to_s
+      io << "\r\n"
     end
   end
 end

data/lib/llm/provider.rb

@@ -15,8 +15,7 @@
 # @see LLM::Provider::Gemini
 # @see LLM::Provider::Ollama
 class LLM::Provider
-  require_relative "http_client"
-  include LLM::HTTPClient
+  require "net/http"
 
   ##
   # @param [String] secret
@@ -222,6 +221,32 @@ class LLM::Provider
     raise NotImplementedError
   end
 
+  ##
+  # Initiates a HTTP request
+  # @param [Net::HTTP] http
+  #  The HTTP object to use for the request
+  # @param [Net::HTTPRequest] req
+  #  The request to send
+  # @param [Proc] b
+  #  A block to yield the response to (optional)
+  # @return [Net::HTTPResponse]
+  #  The response from the server
+  # @raise [LLM::Error::Unauthorized]
+  #  When authentication fails
+  # @raise [LLM::Error::RateLimit]
+  #  When the rate limit is exceeded
+  # @raise [LLM::Error::ResponseError]
+  #  When any other unsuccessful status code is returned
+  # @raise [SystemCallError]
+  #  When there is a network error at the operating system level
+  def request(http, req, &b)
+    res = http.request(req, &b)
+    case res
+    when Net::HTTPOK then res
+    else error_handler.new(res).raise_error!
+    end
+  end
+
   ##
   # @param [String] provider
   #  The name of the provider

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

@@ -27,7 +27,7 @@ class LLM::Anthropic
       when Net::HTTPTooManyRequests
         raise LLM::Error::RateLimit.new { _1.response = res }, "Too many requests"
       else
-        raise LLM::Error::BadResponse.new { _1.response = res }, "Unexpected response"
+        raise LLM::Error::ResponseError.new { _1.response = res }, "Unexpected response"
       end
     end
   end

data/lib/llm/providers/anthropic.rb

@@ -28,7 +28,7 @@ module LLM
     #  The embedding model to use
     # @param [Hash] params
     #  Other embedding parameters
-    # @raise (see LLM::HTTPClient#request)
+    # @raise (see LLM::Provider#request)
     # @return (see LLM::Provider#embed)
     def embed(input, token:, model: "voyage-2", **params)
       llm = LLM.voyageai(token)
@@ -44,7 +44,7 @@ module LLM
     # @param max_tokens The maximum number of tokens to generate
     # @param params (see LLM::Provider#complete)
     # @example (see LLM::Provider#complete)
-    # @raise (see LLM::HTTPClient#request)
+    # @raise (see LLM::Provider#request)
     # @return (see LLM::Provider#complete)
     def complete(prompt, role = :user, model: "claude-3-5-sonnet-20240620", max_tokens: 1024, **params)
       params   = {max_tokens:, model:}.merge!(params)

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

@@ -37,7 +37,7 @@ class LLM::Gemini
     # @param [LLM::File, LLM::Response::File] file The input audio
     # @param [String] model The model to use
     # @param [Hash] params Other parameters (see Gemini docs)
-    # @raise (see LLM::HTTPClient#request)
+    # @raise (see LLM::Provider#request)
     # @return [LLM::Response::AudioTranscription]
     def create_transcription(file:, model: "gemini-1.5-flash", **params)
       res = @provider.complete [
@@ -61,7 +61,7 @@ class LLM::Gemini
     # @param [LLM::File, LLM::Response::File] file The input audio
     # @param [String] model The model to use
     # @param [Hash] params Other parameters (see Gemini docs)
-    # @raise (see LLM::HTTPClient#request)
+    # @raise (see LLM::Provider#request)
     # @return [LLM::Response::AudioTranslation]
     def create_translation(file:, model: "gemini-1.5-flash", **params)
       res = @provider.complete [

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

@@ -27,12 +27,12 @@ class LLM::Gemini
         if reason == "API_KEY_INVALID"
           raise LLM::Error::Unauthorized.new { _1.response = res }, "Authentication error"
         else
-          raise LLM::Error::BadResponse.new { _1.response = res }, "Unexpected response"
+          raise LLM::Error::ResponseError.new { _1.response = res }, "Unexpected response"
         end
       when Net::HTTPTooManyRequests
         raise LLM::Error::RateLimit.new { _1.response = res }, "Too many requests"
       else
-        raise LLM::Error::BadResponse.new { _1.response = res }, "Unexpected response"
+        raise LLM::Error::ResponseError.new { _1.response = res }, "Unexpected response"
       end
     end
 

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

@@ -17,9 +17,9 @@ class LLM::Gemini
   #   #!/usr/bin/env ruby
   #   require "llm"
   #
-  #   llm  = LLM.gemini(ENV["KEY"])
-  #   file = llm.files.create file: LLM::File("/audio/haiku.mp3")
+  #   llm = LLM.gemini(ENV["KEY"])
   #   bot = LLM::Chat.new(llm).lazy
+  #   file = llm.files.create file: LLM::File("/audio/haiku.mp3")
   #   bot.chat(file)
   #   bot.chat("Describe the audio file I sent to you")
   #   bot.chat("The audio file is the first message I sent to you.")
@@ -28,9 +28,9 @@ class LLM::Gemini
   #   #!/usr/bin/env ruby
   #   require "llm"
   #
-  #   llm  = LLM.gemini(ENV["KEY"])
-  #   file = llm.files.create file: LLM::File("/audio/haiku.mp3")
+  #   llm = LLM.gemini(ENV["KEY"])
   #   bot = LLM::Chat.new(llm).lazy
+  #   file = llm.files.create file: LLM::File("/audio/haiku.mp3")
   #   bot.chat(["Describe the audio file I sent to you", file])
   #   bot.messages.select(&:assistant?).each { print "[#{_1.role}]", _1.content, "\n" }
   class Files
@@ -52,7 +52,7 @@ class LLM::Gemini
     #   end
     # @see https://ai.google.dev/gemini-api/docs/files Gemini docs
     # @param [Hash] params Other parameters (see Gemini docs)
-    # @raise (see LLM::HTTPClient#request)
+    # @raise (see LLM::Provider#request)
     # @return [LLM::Response::FileList]
     def all(**params)
       query = URI.encode_www_form(params.merge!(key: secret))
@@ -75,16 +75,18 @@ class LLM::Gemini
     # @see https://ai.google.dev/gemini-api/docs/files Gemini docs
     # @param [File] file The file
     # @param [Hash] params Other parameters (see Gemini docs)
-    # @raise (see LLM::HTTPClient#request)
+    # @raise (see LLM::Provider#request)
     # @return [LLM::Response::File]
     def create(file:, **params)
       req = Net::HTTP::Post.new(request_upload_url(file:), {})
       req["content-length"] = file.bytesize
       req["X-Goog-Upload-Offset"] = 0
       req["X-Goog-Upload-Command"] = "upload, finalize"
-      req.body = File.binread(file.path)
-      res = request(http, req)
-      LLM::Response::File.new(res)
+      file.with_io do |io|
+        req.body_stream = io
+        res = request(http, req)
+        LLM::Response::File.new(res)
+      end
     end
 
     ##
@@ -96,7 +98,7 @@ class LLM::Gemini
     # @see https://ai.google.dev/gemini-api/docs/files Gemini docs
     # @param [#name, String] file The file to get
     # @param [Hash] params Other parameters (see Gemini docs)
-    # @raise (see LLM::HTTPClient#request)
+    # @raise (see LLM::Provider#request)
     # @return [LLM::Response::File]
     def get(file:, **params)
       file_id = file.respond_to?(:name) ? file.name : file.to_s
@@ -114,7 +116,7 @@ class LLM::Gemini
     # @see https://ai.google.dev/gemini-api/docs/files Gemini docs
     # @param [#name, String] file The file to delete
     # @param [Hash] params Other parameters (see Gemini docs)
-    # @raise (see LLM::HTTPClient#request)
+    # @raise (see LLM::Provider#request)
     # @return [LLM::Response::File]
     def delete(file:, **params)
       file_id = file.respond_to?(:name) ? file.name : file.to_s

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

@@ -34,18 +34,19 @@ class LLM::Gemini
     # @see https://ai.google.dev/gemini-api/docs/image-generation Gemini docs
     # @param [String] prompt The prompt
     # @param [Hash] params Other parameters (see Gemini docs)
-    # @raise (see LLM::HTTPClient#request)
+    # @raise (see LLM::Provider#request)
     # @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::Image]
     def create(prompt:, model: "gemini-2.0-flash-exp-image-generation", **params)
-      req = Net::HTTP::Post.new("/v1beta/models/#{model}:generateContent?key=#{secret}", headers)
-      req.body = JSON.dump({
+      req  = Net::HTTP::Post.new("/v1beta/models/#{model}:generateContent?key=#{secret}", headers)
+      body = JSON.dump({
         contents: [{parts: {text: prompt}}],
         generationConfig: {responseModalities: ["TEXT", "IMAGE"]}
       }.merge!(params))
+      req.body = body
       res = request(http, req)
       LLM::Response::Image.new(res).extend(response_parser)
     end
@@ -60,17 +61,16 @@ class LLM::Gemini
     # @param [LLM::File] image The image to edit
     # @param [String] prompt The prompt
     # @param [Hash] params Other parameters (see Gemini docs)
-    # @raise (see LLM::HTTPClient#request)
+    # @raise (see LLM::Provider#request)
     # @note (see LLM::Gemini::Images#create)
     # @return [LLM::Response::Image]
     def edit(image:, prompt:, model: "gemini-2.0-flash-exp-image-generation", **params)
-      req = Net::HTTP::Post.new("/v1beta/models/#{model}:generateContent?key=#{secret}", headers)
-      req.body = JSON.dump({
-        contents: [
-          {parts: [{text: prompt}, format_content(image)]}
-        ],
+      req  = Net::HTTP::Post.new("/v1beta/models/#{model}:generateContent?key=#{secret}", headers)
+      body = JSON.dump({
+        contents: [{parts: [{text: prompt}, format_content(image)]}],
         generationConfig: {responseModalities: ["TEXT", "IMAGE"]}
-      }.merge!(params))
+      }.merge!(params)).b
+      req.body_stream = StringIO.new(body)
       res = request(http, req)
       LLM::Response::Image.new(res).extend(response_parser)
     end

data/lib/llm/providers/gemini.rb

@@ -49,7 +49,7 @@ module LLM
     # @param input (see LLM::Provider#embed)
     # @param model (see LLM::Provider#embed)
     # @param params (see LLM::Provider#embed)
-    # @raise (see LLM::HTTPClient#request)
+    # @raise (see LLM::Provider#request)
     # @return (see LLM::Provider#embed)
     def embed(input, model: "text-embedding-004", **params)
       path = ["/v1beta/models/#{model}", "embedContent?key=#{@secret}"].join(":")
@@ -67,7 +67,7 @@ module LLM
     # @param model (see LLM::Provider#complete)
     # @param params (see LLM::Provider#complete)
     # @example (see LLM::Provider#complete)
-    # @raise (see LLM::HTTPClient#request)
+    # @raise (see LLM::Provider#request)
     # @return (see LLM::Provider#complete)
     def complete(prompt, role = :user, model: "gemini-1.5-flash", **params)
       path     = ["/v1beta/models/#{model}", "generateContent?key=#{@secret}"].join(":")

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

@@ -27,7 +27,7 @@ class LLM::Ollama
       when Net::HTTPTooManyRequests
         raise LLM::Error::RateLimit.new { _1.response = res }, "Too many requests"
       else
-        raise LLM::Error::BadResponse.new { _1.response = res }, "Unexpected response"
+        raise LLM::Error::ResponseError.new { _1.response = res }, "Unexpected response"
       end
     end
   end

data/lib/llm/providers/ollama.rb

@@ -37,7 +37,7 @@ module LLM
     # @param input (see LLM::Provider#embed)
     # @param model (see LLM::Provider#embed)
     # @param params (see LLM::Provider#embed)
-    # @raise (see LLM::HTTPClient#request)
+    # @raise (see LLM::Provider#request)
     # @return (see LLM::Provider#embed)
     def embed(input, model: "llama3.2", **params)
       params   = {model:}.merge!(params)
@@ -55,7 +55,7 @@ module LLM
     # @param model (see LLM::Provider#complete)
     # @param params (see LLM::Provider#complete)
     # @example (see LLM::Provider#complete)
-    # @raise (see LLM::HTTPClient#request)
+    # @raise (see LLM::Provider#request)
     # @return (see LLM::Provider#complete)
     def complete(prompt, role = :user, model: "llama3.2", **params)
       params   = {model:, stream: false}.merge!(params)

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

@@ -31,7 +31,7 @@ class LLM::OpenAI
     # @param [String] model The model to use
     # @param [String] response_format The response format
     # @param [Hash] params Other parameters (see OpenAI docs)
-    # @raise (see LLM::HTTPClient#request)
+    # @raise (see LLM::Provider#request)
     # @return [LLM::Response::Audio]
     def create_speech(input:, voice: "alloy", model: "gpt-4o-mini-tts", response_format: "mp3", **params)
       req = Net::HTTP::Post.new("/v1/audio/speech", headers)
@@ -51,13 +51,13 @@ class LLM::OpenAI
     # @param [LLM::File] file The input audio
     # @param [String] model The model to use
     # @param [Hash] params Other parameters (see OpenAI docs)
-    # @raise (see LLM::HTTPClient#request)
+    # @raise (see LLM::Provider#request)
     # @return [LLM::Response::AudioTranscription]
     def create_transcription(file:, model: "whisper-1", **params)
       multi = LLM::Multipart.new(params.merge!(file:, model:))
       req = Net::HTTP::Post.new("/v1/audio/transcriptions", headers)
       req["content-type"] = multi.content_type
-      req.body = multi.body
+      req.body_stream = multi.body
       res = request(http, req)
       LLM::Response::AudioTranscription.new(res).tap { _1.text = _1.body["text"] }
     end
@@ -73,13 +73,13 @@ class LLM::OpenAI
     # @param [LLM::File] file The input audio
     # @param [String] model The model to use
     # @param [Hash] params Other parameters (see OpenAI docs)
-    # @raise (see LLM::HTTPClient#request)
+    # @raise (see LLM::Provider#request)
     # @return [LLM::Response::AudioTranslation]
     def create_translation(file:, model: "whisper-1", **params)
       multi = LLM::Multipart.new(params.merge!(file:, model:))
       req = Net::HTTP::Post.new("/v1/audio/translations", headers)
       req["content-type"] = multi.content_type
-      req.body = multi.body
+      req.body_stream = multi.body
       res = request(http, req)
       LLM::Response::AudioTranslation.new(res).tap { _1.text = _1.body["text"] }
     end

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

@@ -27,7 +27,7 @@ class LLM::OpenAI
       when Net::HTTPTooManyRequests
         raise LLM::Error::RateLimit.new { _1.response = res }, "Too many requests"
       else
-        raise LLM::Error::BadResponse.new { _1.response = res }, "Unexpected response"
+        raise LLM::Error::ResponseError.new { _1.response = res }, "Unexpected response"
       end
     end
   end

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

@@ -46,7 +46,7 @@ class LLM::OpenAI
     #   end
     # @see https://platform.openai.com/docs/api-reference/files/list OpenAI docs
     # @param [Hash] params Other parameters (see OpenAI docs)
-    # @raise (see LLM::HTTPClient#request)
+    # @raise (see LLM::Provider#request)
     # @return [LLM::Response::FileList]
     def all(**params)
       query = URI.encode_www_form(params)
@@ -67,13 +67,13 @@ class LLM::OpenAI
     # @param [File] file The file
     # @param [String] purpose The purpose of the file (see OpenAI docs)
     # @param [Hash] params Other parameters (see OpenAI docs)
-    # @raise (see LLM::HTTPClient#request)
+    # @raise (see LLM::Provider#request)
     # @return [LLM::Response::File]
     def create(file:, purpose: "assistants", **params)
       multi = LLM::Multipart.new(params.merge!(file:, purpose:))
       req = Net::HTTP::Post.new("/v1/files", headers)
       req["content-type"] = multi.content_type
-      req.body = multi.body
+      req.body_stream = multi.body
       res = request(http, req)
       LLM::Response::File.new(res)
     end
@@ -87,7 +87,7 @@ class LLM::OpenAI
     # @see https://platform.openai.com/docs/api-reference/files/get OpenAI docs
     # @param [#id, #to_s] file The file ID
     # @param [Hash] params Other parameters (see OpenAI docs)
-    # @raise (see LLM::HTTPClient#request)
+    # @raise (see LLM::Provider#request)
     # @return [LLM::Response::File]
     def get(file:, **params)
       file_id = file.respond_to?(:id) ? file.id : file
@@ -107,7 +107,7 @@ class LLM::OpenAI
     # @see https://platform.openai.com/docs/api-reference/files/content OpenAI docs
     # @param [#id, #to_s] file The file ID
     # @param [Hash] params Other parameters (see OpenAI docs)
-    # @raise (see LLM::HTTPClient#request)
+    # @raise (see LLM::Provider#request)
     # @return [LLM::Response::DownloadFile]
     def download(file:, **params)
       query = URI.encode_www_form(params)
@@ -126,7 +126,7 @@ class LLM::OpenAI
     #   print res.deleted, "\n"
     # @see https://platform.openai.com/docs/api-reference/files/delete OpenAI docs
     # @param [#id, #to_s] file The file ID
-    # @raise (see LLM::HTTPClient#request)
+    # @raise (see LLM::Provider#request)
     # @return [OpenStruct] Response body
     def delete(file:)
       file_id = file.respond_to?(:id) ? file.id : file

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

@@ -32,6 +32,7 @@ class LLM::OpenAI
         case content
         when Array then content.flat_map { format_content(_1, mode) }
         when URI then [{type: :image_url, image_url: {url: content.to_s}}]
+        when LLM::Response::File then [{type: :file, file: {file_id: content.id}}]
         else [{type: :text, text: content.to_s}]
         end
       elsif mode == :response

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

@@ -44,7 +44,7 @@ class LLM::OpenAI
     # @param [String] prompt The prompt
     # @param [String] model The model to use
     # @param [Hash] params Other parameters (see OpenAI docs)
-    # @raise (see LLM::HTTPClient#request)
+    # @raise (see LLM::Provider#request)
     # @return [LLM::Response::Image]
     def create(prompt:, model: "dall-e-3", **params)
       req = Net::HTTP::Post.new("/v1/images/generations", headers)
@@ -63,13 +63,13 @@ class LLM::OpenAI
     # @param [File] image The image to create variations from
     # @param [String] model The model to use
     # @param [Hash] params Other parameters (see OpenAI docs)
-    # @raise (see LLM::HTTPClient#request)
+    # @raise (see LLM::Provider#request)
     # @return [LLM::Response::Image]
     def create_variation(image:, model: "dall-e-2", **params)
       multi = LLM::Multipart.new(params.merge!(image:, model:))
       req = Net::HTTP::Post.new("/v1/images/variations", headers)
       req["content-type"] = multi.content_type
-      req.body = multi.body
+      req.body_stream = multi.body
       res = request(http, req)
       LLM::Response::Image.new(res).extend(response_parser)
     end
@@ -85,13 +85,13 @@ class LLM::OpenAI
     # @param [String] prompt The prompt
     # @param [String] model The model to use
     # @param [Hash] params Other parameters (see OpenAI docs)
-    # @raise (see LLM::HTTPClient#request)
+    # @raise (see LLM::Provider#request)
     # @return [LLM::Response::Image]
     def edit(image:, prompt:, model: "dall-e-2", **params)
       multi = LLM::Multipart.new(params.merge!(image:, prompt:, model:))
       req = Net::HTTP::Post.new("/v1/images/edits", headers)
       req["content-type"] = multi.content_type
-      req.body = multi.body
+      req.body_stream = multi.body
       res = request(http, req)
       LLM::Response::Image.new(res).extend(response_parser)
     end

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

@@ -4,7 +4,14 @@ class LLM::OpenAI
   ##
   # The {LLM::OpenAI::Responses LLM::OpenAI::Responses} class provides a responses
   # object for interacting with [OpenAI's response API](https://platform.openai.com/docs/guides/conversation-state?api-mode=responses).
+  # The responses API is similar to the chat completions API but it can maintain
+  # conversation state across multiple requests. This is useful when you want to
+  # save bandwidth and/or not maintain the message thread by yourself.
+  #
   # @example
+  #   #!/usr/bin/env ruby
+  #   require "llm"
+  #
   #   llm = LLM.openai(ENV["KEY"])
   #   res1 = llm.responses.create "Your task is to help me with math", :developer
   #   res2 = llm.responses.create "5 + 5  = ?", :user, previous_response_id: res1.id
@@ -27,7 +34,7 @@ class LLM::OpenAI
     # @param role (see LLM::Provider#complete)
     # @param model (see LLM::Provider#complete)
     # @param [Hash] params Response params
-    # @raise (see LLM::HTTPClient#request)
+    # @raise (see LLM::Provider#request)
     # @return [LLM::Response::Output]
     def create(prompt, role = :user, model: "gpt-4o-mini", **params)
       params   = {model:}.merge!(params)
@@ -42,7 +49,7 @@ class LLM::OpenAI
     # Get a response
     # @see https://platform.openai.com/docs/api-reference/responses/get OpenAI docs
     # @param [#id, #to_s] response Response ID
-    # @raise (see LLM::HTTPClient#request)
+    # @raise (see LLM::Provider#request)
     # @return [LLM::Response::Output]
     def get(response, **params)
       response_id = response.respond_to?(:id) ? response.id : response
@@ -56,7 +63,7 @@ class LLM::OpenAI
     # Deletes a response
     # @see https://platform.openai.com/docs/api-reference/responses/delete OpenAI docs
     # @param [#id, #to_s] response Response ID
-    # @raise (see LLM::HTTPClient#request)
+    # @raise (see LLM::Provider#request)
     # @return [OpenStruct] Response body
     def delete(response)
       response_id = response.respond_to?(:id) ? response.id : response

data/lib/llm/providers/openai.rb

@@ -28,7 +28,7 @@ module LLM
     # @param input (see LLM::Provider#embed)
     # @param model (see LLM::Provider#embed)
     # @param params (see LLM::Provider#embed)
-    # @raise (see LLM::HTTPClient#request)
+    # @raise (see LLM::Provider#request)
     # @return (see LLM::Provider#embed)
     def embed(input, model: "text-embedding-3-small", **params)
       req = Net::HTTP::Post.new("/v1/embeddings", headers)
@@ -45,7 +45,7 @@ module LLM
     # @param model (see LLM::Provider#complete)
     # @param params (see LLM::Provider#complete)
     # @example (see LLM::Provider#complete)
-    # @raise (see LLM::HTTPClient#request)
+    # @raise (see LLM::Provider#request)
     # @return (see LLM::Provider#complete)
     def complete(prompt, role = :user, model: "gpt-4o-mini", **params)
       params   = {model:}.merge!(params)

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

@@ -25,7 +25,7 @@ class LLM::VoyageAI
       when Net::HTTPTooManyRequests
         raise LLM::Error::RateLimit.new { _1.response = res }, "Too many requests"
       else
-        raise LLM::Error::BadResponse.new { _1.response = res }, "Unexpected response"
+        raise LLM::Error::ResponseError.new { _1.response = res }, "Unexpected response"
       end
     end
   end

data/lib/llm/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module LLM
-  VERSION = "0.3.0"
+  VERSION = "0.3.1"
 end

data/spec/gemini/files_spec.rb

@@ -66,7 +66,7 @@ RSpec.describe "LLM::Gemini::Files" do
     end
 
     it "translates the audio clip" do
-      is_expected.to eq("In the name of God, the Most Gracious, the Most Merciful.\n")
+      is_expected.to eq("In the name of Allah, the Most Gracious, the Most Merciful.\n")
     end
   end
 
@@ -86,7 +86,7 @@ RSpec.describe "LLM::Gemini::Files" do
     end
 
     it "translates the audio clip" do
-      is_expected.to eq("All praise is due to Allah, Lord of the Worlds.\n")
+      is_expected.to eq("All praise is due to Allah, Lord of the worlds.\n")
     end
   end
 

data/spec/llm/conversation_spec.rb

@@ -60,7 +60,12 @@ end
 RSpec.describe "LLM::Chat: lazy" do
   let(:described_class) { LLM::Chat }
   let(:token) { ENV["LLM_SECRET"] || "TOKEN" }
-  let(:prompt) { "Keep your answers short and concise, and provide three answers to the three questions" }
+  let(:prompt) do
+    "Keep your answers short and concise, and provide three answers to the three questions" \
+    "There should be one answer per line" \
+    "An answer should be a number, for example: 5" \
+    "Nothing else"
+  end
 
   context "when given completions" do
     context "with gemini",
@@ -105,7 +110,7 @@ RSpec.describe "LLM::Chat: lazy" do
         it "maintains a conversation" do
           is_expected.to have_attributes(
             role: "assistant",
-            content: "1. 5  \n2. 10  \n3. 12  "
+            content: %r|5\s*\n10\s*\n12\s*|
           )
         end
       end
@@ -167,7 +172,7 @@ RSpec.describe "LLM::Chat: lazy" do
         it "maintains a conversation" do
           is_expected.to have_attributes(
             role: "assistant",
-            content: "1. 3 + 2 = 5  \n2. 5 + 5 = 10  \n3. 5 + 7 = 12"
+            content: %r|5\s*\n10\s*\n12\s*|
           )
         end
       end

data/spec/openai/completion_spec.rb

@@ -47,7 +47,8 @@ RSpec.describe "LLM::OpenAI: completions" do
     subject(:response) do
       openai.complete "What is your name? What age are you?", :user, messages: [
         {role: "system", content: "Answer all of my questions"},
-        {role: "system", content: "Your name is Pablo, you are 25 years old and you are my amigo"}
+        {role: "system", content: "Answer in the format: My name is <name> and I am <age> years old"},
+        {role: "system", content: "Your name is Pablo and you are 25 years old"},
       ]
     end
 
@@ -56,7 +57,7 @@ RSpec.describe "LLM::OpenAI: completions" do
         choices: [
           have_attributes(
             role: "assistant",
-            content: "My name is Pablo, and I'm 25 years old! How can I help you today, amigo?"
+            content: %r|\AMy name is Pablo and I am 25 years old|
           )
         ]
       )
@@ -68,7 +69,7 @@ RSpec.describe "LLM::OpenAI: completions" do
     subject(:response) { openai.complete(URI("/foobar.exe"), :user) }
 
     it "raises an error" do
-      expect { response }.to raise_error(LLM::Error::BadResponse)
+      expect { response }.to raise_error(LLM::Error::ResponseError)
     end
 
     it "includes the response" do

data/spec/openai/files_spec.rb

@@ -9,10 +9,11 @@ RSpec.describe "LLM::OpenAI::Files" do
   context "when given a successful create operation (haiku1.txt)",
           vcr: {cassette_name: "openai/files/successful_create_haiku1"} do
     subject(:file) { provider.files.create(file: LLM::File("spec/fixtures/documents/haiku1.txt")) }
-    after { provider.files.delete(file:) }
 
     it "is successful" do
       expect(file).to be_instance_of(LLM::Response::File)
+    ensure
+      provider.files.delete(file:)
     end
 
     it "returns a file object" do
@@ -21,16 +22,19 @@ RSpec.describe "LLM::OpenAI::Files" do
         filename: "haiku1.txt",
         purpose: "assistants"
       )
+    ensure
+      provider.files.delete(file:)
     end
   end
 
   context "when given a successful create operation (haiku2.txt)",
           vcr: {cassette_name: "openai/files/successful_create_haiku2"} do
     subject(:file) { provider.files.create(file: LLM::File("spec/fixtures/documents/haiku2.txt")) }
-    after { provider.files.delete(file:) }
 
     it "is successful" do
       expect(file).to be_instance_of(LLM::Response::File)
+    ensure
+      provider.files.delete(file:)
     end
 
     it "returns a file object" do
@@ -39,6 +43,8 @@ RSpec.describe "LLM::OpenAI::Files" do
         filename: "haiku2.txt",
         purpose: "assistants"
       )
+    ensure
+      provider.files.delete(file:)
     end
   end
 
@@ -62,10 +68,11 @@ RSpec.describe "LLM::OpenAI::Files" do
           vcr: {cassette_name: "openai/files/successful_get_haiku4"} do
     let(:file) { provider.files.create(file: LLM::File("spec/fixtures/documents/haiku4.txt")) }
     subject { provider.files.get(file:) }
-    after { provider.files.delete(file:) }
 
     it "is successful" do
       is_expected.to be_instance_of(LLM::Response::File)
+    ensure
+      provider.files.delete(file:)
     end
 
     it "returns a file object" do
@@ -74,6 +81,8 @@ RSpec.describe "LLM::OpenAI::Files" do
         filename: "haiku4.txt",
         purpose: "assistants"
       )
+    ensure
+      provider.files.delete(file:)
     end
   end
 
@@ -86,10 +95,11 @@ RSpec.describe "LLM::OpenAI::Files" do
       ]
     end
     subject(:file) { provider.files.all }
-    after { files.each { |file| provider.files.delete(file:) } }
 
     it "is successful" do
       expect(file).to be_instance_of(LLM::Response::FileList)
+    ensure
+      files.each { |file| provider.files.delete(file:) }
     end
 
     it "returns an array of file objects" do
@@ -107,44 +117,88 @@ RSpec.describe "LLM::OpenAI::Files" do
           )
         ]
       )
+    ensure
+      files.each { |file| provider.files.delete(file:) }
     end
   end
 
   context "when asked to describe the contents of a file",
           vcr: {cassette_name: "openai/files/describe_freebsd.sysctl.pdf"} do
-    subject { bot.last_message.content }
+    subject { bot.last_message.content.downcase[0..2] }
     let(:bot) { LLM::Chat.new(provider).lazy }
     let(:file) { provider.files.create(file: LLM::File("spec/fixtures/documents/freebsd.sysctl.pdf")) }
-    after { provider.files.delete(file:) }
 
     before do
       bot.respond(file)
-      bot.respond("Describe the contents of the file to me")
-      bot.respond("Your summary should be no more than ten words")
+      bot.respond("Is this PDF document about FreeBSD?")
+      bot.respond("Answer with yes or no. Nothing else.")
     end
 
     it "describes the document" do
-      is_expected.to eq("FreeBSD system control nodes implementation and usage overview.")
+      is_expected.to eq("yes")
+    ensure
+      provider.files.delete(file:)
     end
   end
 
   context "when asked to describe the contents of a file",
           vcr: {cassette_name: "openai/files/describe_freebsd.sysctl_2.pdf"} do
-    subject { bot.last_message.content }
+    subject { bot.last_message.content.downcase[0..2] }
     let(:bot) { LLM::Chat.new(provider).lazy }
     let(:file) { provider.files.create(file: LLM::File("spec/fixtures/documents/freebsd.sysctl.pdf")) }
-    after { provider.files.delete(file:) }
 
     before do
       bot.respond([
-        "Describe the contents of the file to me",
-        "Your summary should be no more than ten words",
+        "Is this PDF document about FreeBSD?",
+        "Answer with yes or no. Nothing else.",
         file
       ])
     end
 
     it "describes the document" do
-      is_expected.to eq("FreeBSD kernel system control nodes overview and implementation.")
+      is_expected.to eq("yes")
+    ensure
+      provider.files.delete(file:)
+    end
+  end
+
+  context "when asked to describe the contents of a file",
+          vcr: {cassette_name: "openai/files/describe_freebsd.sysctl_3.pdf"} do
+    subject { bot.last_message.content.downcase[0..2] }
+    let(:bot) { LLM::Chat.new(provider).lazy }
+    let(:file) { provider.files.create(file: LLM::File("spec/fixtures/documents/freebsd.sysctl.pdf")) }
+
+    before do
+      bot.chat(file)
+      bot.chat("Is this PDF document about FreeBSD?")
+      bot.chat("Answer with yes or no. Nothing else.")
+    end
+
+    it "describes the document" do
+      is_expected.to eq("yes")
+    ensure
+      provider.files.delete(file:)
+    end
+  end
+
+  context "when asked to describe the contents of a file",
+          vcr: {cassette_name: "openai/files/describe_freebsd.sysctl_4.pdf"} do
+    subject { bot.last_message.content.downcase[0..2] }
+    let(:bot) { LLM::Chat.new(provider).lazy }
+    let(:file) { provider.files.create(file: LLM::File("spec/fixtures/documents/freebsd.sysctl.pdf")) }
+
+    before do
+      bot.chat([
+        "Is this PDF document about FreeBSD?",
+        "Answer with yes or no. Nothing else.",
+        file
+      ])
+    end
+
+    it "describes the document" do
+      is_expected.to eq("yes")
+    ensure
+      provider.files.delete(file:)
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: llm.rb
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Antar Azri
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-04-25 00:00:00.000000000 Z
+date: 2025-04-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: webmock
@@ -154,7 +154,6 @@ files:
 - lib/llm/core_ext/ostruct.rb
 - lib/llm/error.rb
 - lib/llm/file.rb
-- lib/llm/http_client.rb
 - lib/llm/message.rb
 - lib/llm/mime.rb
 - lib/llm/model.rb

data/lib/llm/http_client.rb

@@ -1,34 +0,0 @@
-# frozen_string_literal: true
-
-module LLM
-  ##
-  # @private
-  module HTTPClient
-    require "net/http"
-    ##
-    # Initiates a HTTP request
-    # @param [Net::HTTP] http
-    #  The HTTP object to use for the request
-    # @param [Net::HTTPRequest] req
-    #  The request to send
-    # @param [Proc] b
-    #  A block to yield the response to (optional)
-    # @return [Net::HTTPResponse]
-    #  The response from the server
-    # @raise [LLM::Error::Unauthorized]
-    #  When authentication fails
-    # @raise [LLM::Error::RateLimit]
-    #  When the rate limit is exceeded
-    # @raise [LLM::Error::BadResponse]
-    #  When any other unsuccessful status code is returned
-    # @raise [SystemCallError]
-    #  When there is a network error at the operating system level
-    def request(http, req, &b)
-      res = http.request(req, &b)
-      case res
-      when Net::HTTPOK then res
-      else error_handler.new(res).raise_error!
-      end
-    end
-  end
-end