llm.rb 0.3.1 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3939075c064b4abfd8853c3f67b6db7df6111d340d658d4d8ad0c4d1bccc96bc
-  data.tar.gz: 0ca274d3e4b032c25730aef896df903681c28033ebb0907c965339a33aff56d1
+  metadata.gz: 3c55653b476d2fe6fe9457c89bc430c698668312ce89660a1d69abd8adf338eb
+  data.tar.gz: fe7d456bbb739eb091e82351839baef4c64d1d108a2c4cd7de3eb1b478982631
 SHA512:
-  metadata.gz: feaf87457b8fa5b4f756a5fe8cc1f670c8b0286a730fe00273bc99678092fe7f704d58f01ba0a0baf4072a0dcee063bc87cf88bc7cdf53125334476adbce41f6
-  data.tar.gz: 3be8b460d9b483c0e172d9159b2394ea39da7a1475aee3ab47b224303e2a251f3b04f0543402494485040998225f84342be986db8c7b8ea80df92f561d4d6d92
+  metadata.gz: 8cd55bb28eb92fea745d8b11062b2442bf4b2de88ecfb0b7dc99cfefd293bd45113088dd13ccfe7e251d2e369459da700f15725bae51c3d31d4bf68e19953138
+  data.tar.gz: dab47021b94d00e51e7d0ca3f92e2966170b9fd8ce7138e0728d2be7fb83da03104ff93cd7c54b760acca62dd03adf16462069db9eb5c30185743c25259105aa

data/README.md

@@ -26,6 +26,7 @@ llm = LLM.openai("yourapikey")
 llm = LLM.gemini("yourapikey")
 llm = LLM.anthropic("yourapikey")
 llm = LLM.ollama(nil)
+llm = LLM.voyageai("yourapikey")
 ```
 
 ### Conversations
@@ -122,8 +123,6 @@ for more information on how to use the audio generation API:
 ```ruby
 #!/usr/bin/env ruby
 require "llm"
-require "open-uri"
-require "fileutils"
 
 llm = LLM.openai(ENV["KEY"])
 res = llm.audio.create_speech(input: "Hello world")
@@ -151,8 +150,6 @@ examples and documentation
 ```ruby
 #!/usr/bin/env ruby
 require "llm"
-require "open-uri"
-require "fileutils"
 
 llm = LLM.openai(ENV["KEY"])
 res = llm.audio.create_transcription(
@@ -180,9 +177,8 @@ examples and documentation
 
 
 ```ruby
+#!/usr/bin/env ruby
 require "llm"
-require "open-uri"
-require "fileutils"
 
 llm = LLM.openai(ENV["KEY"])
 res = llm.audio.create_translation(
@@ -320,6 +316,48 @@ bot.messages.select(&:assistant?).each { print "[#{_1.role}] ", _1.content, "\n"
 #             contains information about the features, installation, and usage of OpenBSD.
 ```
 
+### Prompts
+
+#### Multimodal
+
+Generally all providers accept text prompts but some providers can
+also understand URLs, and various file types (eg images, audio, video,
+etc). The llm.rb approach to multimodal prompts is to let you pass `URI`
+objects to describe links, `LLM::File` / `LLM::Response::File` objects
+to describe files, `String` objects to describe text blobs, or an array
+of the forementioned objects to describe multiple objects in a single
+prompt. Each object is a first class citizen that can be passed directly
+to a prompt.
+
+For more depth and examples on how to use the multimodal API, please see
+the [provider-specific documentation](https://0x1eef.github.io/x/llm.rb/)
+for more provider-specific examples – there can be subtle differences
+between providers and even between APIs from the same provider that are
+not covered in the README:
+
+```ruby
+#!/usr/bin/env ruby
+require "llm"
+
+llm = LLM.openai(ENV["KEY"])
+bot = LLM::Chat.new(llm).lazy
+
+bot.chat URI("https://example.com/path/to/image.png")
+bot.chat "Describe the above image"
+bot.messages.select(&:assistant?).each { print "[#{_1.role}] ", _1.content, "\n" }
+
+file = bot.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" }
+
+bot.chat [LLM::File("/images/puffy.png"), "What is this image about?"]
+bot.messages.select(&:assistant?).each { print "[#{_1.role}] ", _1.content, "\n" }
+
+bot.chat [LLM::File("/images/beastie.png"), "What is this image about?"]
+bot.messages.select(&:assistant?).each { print "[#{_1.role}] ", _1.content, "\n" }
+```
+
 ### Embeddings
 
 #### Text
@@ -394,11 +432,11 @@ llm.rb can be installed via rubygems.org:
 
 ## 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.
+llm.rb was built for developers who believe that simplicity can be challenging
+but it is always worth it. 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 complex metaprogramming.
 
 Every part of llm.rb is designed to be explicit, composable, memory-safe,
 and production-ready without compromise. No unnecessary abstractions,
@@ -406,8 +444,6 @@ 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

@@ -4,8 +4,9 @@ module LLM
   ##
   # The superclass of all LLM errors
   class Error < RuntimeError
-    def initialize
+    def initialize(...)
       block_given? ? yield(self) : nil
+      super
     end
 
     ##
@@ -17,6 +18,10 @@ module LLM
       attr_accessor :response
     end
 
+    ##
+    # When a prompt is given an object that's not understood
+    PromptError = Class.new(Error)
+
     ##
     # HTTPUnauthorized
     Unauthorized = Class.new(ResponseError)

data/lib/llm/file.rb

@@ -42,6 +42,13 @@ class LLM::File
     [File.binread(path)].pack("m0")
   end
 
+  ##
+  # @return [String]
+  #  Returns the file contents in base64 URL format
+  def to_data_uri
+    "data:#{mime_type};base64,#{to_b64}"
+  end
+
   ##
   # @return [File]
   #  Yields an IO object suitable to be streamed

data/lib/llm/provider.rb

@@ -4,16 +4,7 @@
 # The Provider class represents an abstract class for
 # LLM (Language Model) providers.
 #
-# @note
-#  This class is not meant to be instantiated directly.
-#  Instead, use one of the subclasses that implement
-#  the methods defined here.
-#
 # @abstract
-# @see LLM::Provider::OpenAI
-# @see LLM::Provider::Anthropic
-# @see LLM::Provider::Gemini
-# @see LLM::Provider::Ollama
 class LLM::Provider
   require "net/http"
 
@@ -78,7 +69,7 @@ class LLM::Provider
   # @raise [NotImplementedError]
   #  When the method is not implemented by a subclass
   # @return [LLM::Response::Completion]
-  def complete(prompt, role = :user, model:, **params)
+  def complete(prompt, role = :user, model: nil, **params)
     raise NotImplementedError
   end
 
@@ -237,6 +228,8 @@ class LLM::Provider
   #  When the rate limit is exceeded
   # @raise [LLM::Error::ResponseError]
   #  When any other unsuccessful status code is returned
+  # @raise [LLM::Error::PromptError]
+  #  When given an object a provider does not understand
   # @raise [SystemCallError]
   #  When there is a network error at the operating system level
   def request(http, req, &b)
@@ -247,6 +240,17 @@ class LLM::Provider
     end
   end
 
+  ##
+  # @param [Net::HTTPRequest] req
+  #  The request to set the body stream for
+  # @param [IO] io
+  #  The IO object to set as the body stream
+  # @return [void]
+  def set_body_stream(req, io)
+    req.body_stream = io
+    req["transfer-encoding"] = "chunked" unless req["content-length"]
+  end
+
   ##
   # @param [String] provider
   #  The name of the provider

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

@@ -83,7 +83,7 @@ class LLM::Gemini
       req["X-Goog-Upload-Offset"] = 0
       req["X-Goog-Upload-Command"] = "upload, finalize"
       file.with_io do |io|
-        req.body_stream = io
+        set_body_stream(req, io)
         res = request(http, req)
         LLM::Response::File.new(res)
       end
@@ -155,7 +155,7 @@ class LLM::Gemini
       @provider.instance_variable_get(:@secret)
     end
 
-    [:headers, :request].each do |m|
+    [:headers, :request, :set_body_stream].each do |m|
       define_method(m) { |*args, &b| @provider.send(m, *args, &b) }
     end
   end

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

@@ -70,7 +70,7 @@ class LLM::Gemini
         contents: [{parts: [{text: prompt}, format_content(image)]}],
         generationConfig: {responseModalities: ["TEXT", "IMAGE"]}
       }.merge!(params)).b
-      req.body_stream = StringIO.new(body)
+      set_body_stream(req, StringIO.new(body))
       res = request(http, req)
       LLM::Response::Image.new(res).extend(response_parser)
     end
@@ -92,7 +92,7 @@ class LLM::Gemini
       @provider.instance_variable_get(:@http)
     end
 
-    [:response_parser, :headers, :request].each do |m|
+    [:response_parser, :headers, :request, :set_body_stream].each do |m|
       define_method(m) { |*args, &b| @provider.send(m, *args, &b) }
     end
   end

data/lib/llm/providers/gemini.rb

@@ -70,11 +70,12 @@ module LLM
     # @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(":")
-      req      = Net::HTTP::Post.new(path, headers)
+      path = ["/v1beta/models/#{model}", "generateContent?key=#{@secret}"].join(":")
+      req  = Net::HTTP::Post.new(path, headers)
       messages = [*(params.delete(:messages) || []), LLM::Message.new(role, prompt)]
-      req.body = JSON.dump({contents: format(messages)})
-      res      = request(@http, req)
+      body = JSON.dump({contents: format(messages)}).b
+      set_body_stream(req, StringIO.new(body))
+      res = request(@http, req)
       Response::Completion.new(res).extend(response_parser)
     end
 

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

@@ -57,7 +57,7 @@ class LLM::OpenAI
       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_stream = multi.body
+      set_body_stream(req, multi.body)
       res = request(http, req)
       LLM::Response::AudioTranscription.new(res).tap { _1.text = _1.body["text"] }
     end
@@ -79,7 +79,7 @@ class LLM::OpenAI
       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_stream = multi.body
+      set_body_stream(req, multi.body)
       res = request(http, req)
       LLM::Response::AudioTranslation.new(res).tap { _1.text = _1.body["text"] }
     end
@@ -90,7 +90,7 @@ class LLM::OpenAI
       @provider.instance_variable_get(:@http)
     end
 
-    [:headers, :request].each do |m|
+    [:headers, :request, :set_body_stream].each do |m|
       define_method(m) { |*args, &b| @provider.send(m, *args, &b) }
     end
   end

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

@@ -73,7 +73,7 @@ class LLM::OpenAI
       multi = LLM::Multipart.new(params.merge!(file:, purpose:))
       req = Net::HTTP::Post.new("/v1/files", headers)
       req["content-type"] = multi.content_type
-      req.body_stream = multi.body
+      set_body_stream(req, multi.body)
       res = request(http, req)
       LLM::Response::File.new(res)
     end
@@ -141,7 +141,7 @@ class LLM::OpenAI
       @provider.instance_variable_get(:@http)
     end
 
-    [:headers, :request].each do |m|
+    [:headers, :request, :set_body_stream].each do |m|
       define_method(m) { |*args, &b| @provider.send(m, *args, &b) }
     end
   end

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

@@ -29,19 +29,50 @@ class LLM::OpenAI
     #  The formatted content
     def format_content(content, mode)
       if mode == :complete
-        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
+        format_complete(content)
       elsif mode == :response
-        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: :input_file, file_id: content.id}]
-        else [{type: :input_text, text: content.to_s}]
+        format_response(content)
+      end
+    end
+
+    def format_complete(content)
+      case content
+      when Array
+        content.flat_map { format_complete(_1) }
+      when URI
+        [{type: :image_url, image_url: {url: content.to_s}}]
+      when LLM::File
+        [{type: :image_url, image_url: {url: content.to_data_uri}}]
+      when LLM::Response::File
+        [{type: :file, file: {file_id: content.id}}]
+      when String
+        [{type: :text, text: content.to_s}]
+      when LLM::Message
+        format_complete(content.content)
+      else
+        raise LLM::Error::PromptError, "The given object (an instance of #{content.class}) " \
+                                       "is not supported by the OpenAI chat completions API"
+      end
+    end
+
+    def format_response(content)
+      case content
+      when Array
+        content.flat_map { format_response(_1) }
+      when LLM::Response::File
+        file = LLM::File(content.filename)
+        if file.image?
+          [{type: :input_image, file_id: content.id}]
+        else
+          [{type: :input_file, file_id: content.id}]
         end
+      when String
+        [{type: :input_text, text: content.to_s}]
+      when LLM::Message
+        format_response(content.content)
+      else
+        raise LLM::Error::PromptError, "The given object (an instance of #{content.class}) " \
+                                       "is not supported by the OpenAI responses API"
       end
     end
   end

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

@@ -69,7 +69,7 @@ class LLM::OpenAI
       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_stream = multi.body
+      set_body_stream(req, multi.body)
       res = request(http, req)
       LLM::Response::Image.new(res).extend(response_parser)
     end
@@ -91,7 +91,7 @@ class LLM::OpenAI
       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_stream = multi.body
+      set_body_stream(req, multi.body)
       res = request(http, req)
       LLM::Response::Image.new(res).extend(response_parser)
     end
@@ -102,7 +102,7 @@ class LLM::OpenAI
       @provider.instance_variable_get(:@http)
     end
 
-    [:response_parser, :headers, :request].each do |m|
+    [:response_parser, :headers, :request, :set_body_stream].each do |m|
       define_method(m) { |*args, &b| @provider.send(m, *args, &b) }
     end
   end

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

@@ -16,6 +16,20 @@ class LLM::OpenAI
   #   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
   #   [res1,res2].each { llm.responses.delete(_1) }
+  # @example
+  #   #!/usr/bin/env ruby
+  #   require "llm"
+  #
+  #   llm  = LLM.openai(ENV["KEY"])
+  #   file = llm.files.create file: LLM::File("/images/hat.png")
+  #   res  = llm.responses.create ["Describe the image", file]
+  # @example
+  #   #!/usr/bin/env ruby
+  #   require "llm"
+  #
+  #   llm  = LLM.openai(ENV["KEY"])
+  #   file = llm.files.create file: LLM::File("/documents/freebsd.pdf")
+  #   res  = llm.responses.create ["Describe the document, file]
   class Responses
     include Format
 

data/lib/llm/version.rb

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

data/spec/openai/completion_spec.rb

@@ -48,7 +48,7 @@ RSpec.describe "LLM::OpenAI: completions" do
       openai.complete "What is your name? What age are you?", :user, messages: [
         {role: "system", content: "Answer all of my questions"},
         {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"},
+        {role: "system", content: "Your name is Pablo and you are 25 years old"}
       ]
     end
 
@@ -81,7 +81,7 @@ RSpec.describe "LLM::OpenAI: completions" do
 
   context "when given an unauthorized response",
           vcr: {cassette_name: "openai/completions/unauthorized_response"} do
-    subject(:response) { openai.complete(LLM::Message.new("Hello!", :user)) }
+    subject(:response) { openai.complete(LLM::Message.new(:user, "Hello!")) }
     let(:token) { "BADTOKEN" }
 
     it "raises an error" do

data/spec/openai/files_spec.rb

@@ -94,16 +94,16 @@ RSpec.describe "LLM::OpenAI::Files" do
         provider.files.create(file: LLM::File("spec/fixtures/documents/haiku2.txt"))
       ]
     end
-    subject(:file) { provider.files.all }
+    subject(:filelist) { provider.files.all }
 
     it "is successful" do
-      expect(file).to be_instance_of(LLM::Response::FileList)
+      expect(filelist).to be_instance_of(LLM::Response::FileList)
     ensure
       files.each { |file| provider.files.delete(file:) }
     end
 
     it "returns an array of file objects" do
-      expect(file).to match_array(
+      expect(filelist.files[0..1]).to match_array(
         [
           have_attributes(
             id: instance_of(String),

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: llm.rb
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.3.2
 platform: ruby
 authors:
 - Antar Azri