llm.rb 0.2.1 → 0.3.1

data/lib/llm/providers/openai.rb

@@ -5,9 +5,13 @@ module LLM
   # The OpenAI class implements a provider for
   # [OpenAI](https://platform.openai.com/)
   class OpenAI < Provider
+    require_relative "openai/format"
     require_relative "openai/error_handler"
     require_relative "openai/response_parser"
-    require_relative "openai/format"
+    require_relative "openai/responses"
+    require_relative "openai/images"
+    require_relative "openai/audio"
+    require_relative "openai/files"
     include Format
 
     HOST = "api.openai.com"
@@ -19,29 +23,71 @@ module LLM
     end
 
     ##
+    # Provides an embedding
+    # @see https://platform.openai.com/docs/api-reference/embeddings/create OpenAI docs
     # @param input (see LLM::Provider#embed)
+    # @param model (see LLM::Provider#embed)
+    # @param params (see LLM::Provider#embed)
+    # @raise (see LLM::Provider#request)
     # @return (see LLM::Provider#embed)
-    def embed(input, **params)
+    def embed(input, model: "text-embedding-3-small", **params)
       req = Net::HTTP::Post.new("/v1/embeddings", headers)
-      req.body = JSON.dump({input:, model: "text-embedding-3-small"}.merge!(params))
+      req.body = JSON.dump({input:, model:}.merge!(params))
       res = request(@http, req)
       Response::Embedding.new(res).extend(response_parser)
     end
 
     ##
+    # Provides an interface to the chat completions API
     # @see https://platform.openai.com/docs/api-reference/chat/create OpenAI docs
     # @param prompt (see LLM::Provider#complete)
     # @param role (see LLM::Provider#complete)
+    # @param model (see LLM::Provider#complete)
+    # @param params (see LLM::Provider#complete)
+    # @example (see LLM::Provider#complete)
+    # @raise (see LLM::Provider#request)
     # @return (see LLM::Provider#complete)
-    def complete(prompt, role = :user, **params)
-      params   = {model: "gpt-4o-mini"}.merge!(params)
+    def complete(prompt, role = :user, model: "gpt-4o-mini", **params)
+      params   = {model:}.merge!(params)
       req      = Net::HTTP::Post.new("/v1/chat/completions", headers)
       messages = [*(params.delete(:messages) || []), Message.new(role, prompt)]
-      req.body = JSON.dump({messages: format(messages)}.merge!(params))
+      req.body = JSON.dump({messages: format(messages, :complete)}.merge!(params))
       res      = request(@http, req)
       Response::Completion.new(res).extend(response_parser)
     end
 
+    ##
+    # Provides an interface to OpenAI's response API
+    # @see https://platform.openai.com/docs/api-reference/responses/create OpenAI docs
+    # @return [LLM::OpenAI::Responses]
+    def responses
+      LLM::OpenAI::Responses.new(self)
+    end
+
+    ##
+    # Provides an interface to OpenAI's image generation API
+    # @see https://platform.openai.com/docs/api-reference/images/create OpenAI docs
+    # @return [LLM::OpenAI::Images]
+    def images
+      LLM::OpenAI::Images.new(self)
+    end
+
+    ##
+    # Provides an interface to OpenAI's audio generation API
+    # @see https://platform.openai.com/docs/api-reference/audio/createSpeech OpenAI docs
+    # @return [LLM::OpenAI::Audio]
+    def audio
+      LLM::OpenAI::Audio.new(self)
+    end
+
+    ##
+    # Provides an interface to OpenAI's files API
+    # @see https://platform.openai.com/docs/api-reference/files/create OpenAI docs
+    # @return [LLM::OpenAI::Files]
+    def files
+      LLM::OpenAI::Files.new(self)
+    end
+
     ##
     # @return (see LLM::Provider#assistant_role)
     def assistant_role

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/providers/voyageai.rb

@@ -17,9 +17,9 @@ module LLM
     # [Anthropic's recommendation](https://docs.anthropic.com/en/docs/build-with-claude/embeddings)
     # @param input (see LLM::Provider#embed)
     # @return (see LLM::Provider#embed)
-    def embed(input, **params)
+    def embed(input, model: "voyage-2", **params)
       req = Net::HTTP::Post.new("/v1/embeddings", headers)
-      req.body = JSON.dump({input:, model: "voyage-2"}.merge!(params))
+      req.body = JSON.dump({input:, model:}.merge!(params))
       res = request(@http, req)
       Response::Embedding.new(res).extend(response_parser)
     end

data/lib/llm/response/audio.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module LLM
+  ##
+  # The {LLM::Response::Audio LLM::Response::Audio} class represents an
+  # audio file that has been returned by a provider. It wraps an IO object
+  # that can be used to read the contents of an audio stream (as binary data).
+  class Response::Audio < Response
+    ##
+    # @return [StringIO]
+    attr_accessor :audio
+  end
+end

data/lib/llm/response/audio_transcription.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module LLM
+  ##
+  # The {LLM::Response::AudioTranscription LLM::Response::AudioTranscription}
+  # class represents an audio transcription that has been returned by
+  # a provider (eg OpenAI, Gemini, etc)
+  class Response::AudioTranscription < Response
+    ##
+    # Returns the text of the transcription
+    # @return [String]
+    attr_accessor :text
+  end
+end

data/lib/llm/response/audio_translation.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module LLM
+  ##
+  # The {LLM::Response::AudioTranslation LLM::Response::AudioTranslation}
+  # class represents an audio translation that has been returned by
+  # a provider (eg OpenAI, Gemini, etc)
+  class Response::AudioTranslation < Response
+    ##
+    # Returns the text of the translation
+    # @return [String]
+    attr_accessor :text
+  end
+end

data/lib/llm/response/download_file.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module LLM
+  ##
+  # The {LLM::Response::DownloadFile LLM::Response::DownloadFile} class
+  # represents the contents of a file that has been returned by a
+  # provider. It wraps an IO object that can be used to read the file
+  # contents.
+  class Response::DownloadFile < Response
+    ##
+    # Returns a StringIO object
+    # @return [StringIO]
+    attr_accessor :file
+  end
+end

data/lib/llm/response/file.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module LLM
+  ##
+  # The {LLM::Response::File LLM::Response::File} class represents a file
+  # that has been uploaded to a provider. Its properties are delegated
+  # to the underlying response body, and vary by provider.
+  class Response::File < Response
+    ##
+    # Returns a normalized response body
+    # @return [Hash]
+    def body
+      @_body ||= if super["file"]
+        super["file"].transform_keys { snakecase(_1) }
+      else
+        super.transform_keys { snakecase(_1) }
+      end
+    end
+
+    ##
+    # @return [String]
+    def inspect
+      "#<#{self.class}:0x#{object_id.to_s(16)} body=#{body}>"
+    end
+
+    private
+
+    include LLM::Utils
+
+    def respond_to_missing?(m, _)
+      body.key?(m.to_s) || super
+    end
+
+    def method_missing(m, *args, &block)
+      if body.key?(m.to_s)
+        body[m.to_s]
+      else
+        super
+      end
+    end
+  end
+end

data/lib/llm/response/filelist.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module LLM
+  ##
+  # The {LLM::Response::FileList LLM::Response::FileList} class represents a
+  # list of file objects that are returned by a provider. It is an Enumerable
+  # object, and can be used to iterate over the file objects in a way that is
+  # similar to an array. Each element is an instance of OpenStruct.
+  class Response::FileList < Response
+    include Enumerable
+
+    attr_accessor :files
+
+    def each(&)
+      @files.each(&)
+    end
+  end
+end

data/lib/llm/response/image.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module LLM
+  ##
+  # The {LLM::Response::Image LLM::Response::Image} class represents
+  # an image response. An image response might encapsulate one or more
+  # URLs, or a base64 encoded image -- depending on the provider.
+  class Response::Image < Response
+    ##
+    # Returns one or more image objects, or nil
+    # @return [Array<OpenStruct>, nil]
+    def images
+      parsed[:images].any? ? parsed[:images] : nil
+    end
+
+    ##
+    # Returns one or more image URLs, or nil
+    # @return [Array<String>, nil]
+    def urls
+      parsed[:urls].any? ? parsed[:urls] : nil
+    end
+
+    private
+
+    def parsed
+      @parsed ||= parse_image(body)
+    end
+  end
+end

data/lib/llm/response/output.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module LLM
+  class Response::Output < Response
+    ##
+    # @return [String]
+    #  Returns the id of the response
+    def id
+      parsed[:id]
+    end
+
+    ##
+    # @return [String]
+    #  Returns the model name
+    def model
+      parsed[:model]
+    end
+
+    ##
+    # @return [Array<LLM::Message>]
+    def outputs
+      parsed[:outputs]
+    end
+
+    ##
+    # @return [Integer]
+    #  Returns the input token count
+    def input_tokens
+      parsed[:input_tokens]
+    end
+
+    ##
+    # @return [Integer]
+    #  Returns the output token count
+    def output_tokens
+      parsed[:output_tokens]
+    end
+
+    ##
+    # @return [Integer]
+    #  Returns the total count of tokens
+    def total_tokens
+      parsed[:total_tokens]
+    end
+
+    private
+
+    ##
+    # @private
+    # @return [Hash]
+    #  Returns the parsed response from the provider
+    def parsed
+      @parsed ||= parse_output_response(body)
+    end
+  end
+end

data/lib/llm/response.rb

@@ -5,11 +5,14 @@ module LLM
     require "json"
     require_relative "response/completion"
     require_relative "response/embedding"
-
-    ##
-    # @return [Hash]
-    #  Returns the response body
-    attr_reader :body
+    require_relative "response/output"
+    require_relative "response/image"
+    require_relative "response/audio"
+    require_relative "response/audio_transcription"
+    require_relative "response/audio_translation"
+    require_relative "response/file"
+    require_relative "response/filelist"
+    require_relative "response/download_file"
 
     ##
     # @param [Net::HTTPResponse] res
@@ -18,7 +21,16 @@ module LLM
     #  Returns an instance of LLM::Response
     def initialize(res)
       @res = res
-      @body = JSON.parse(res.body)
+    end
+
+    ##
+    # Returns the response body
+    # @return [Hash, String]
+    def body
+      @body ||= case @res["content-type"]
+      when %r|\Aapplication/json\s*| then JSON.parse(@res.body)
+      else @res.body
+      end
     end
   end
 end

data/lib/llm/utils.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+##
+# @private
+module LLM::Utils
+  def camelcase(key)
+    key.to_s
+      .split("_")
+      .map.with_index { (_2 > 0) ? _1.capitalize : _1 }
+      .join
+  end
+
+  def snakecase(key)
+    key
+      .split(/([A-Z])/)
+      .map { (_1.size == 1) ? "_#{_1.downcase}" : _1 }
+      .join
+  end
+end

data/lib/llm/version.rb

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

data/lib/llm.rb

@@ -2,14 +2,17 @@
 
 module LLM
   require_relative "llm/version"
+  require_relative "llm/utils"
   require_relative "llm/error"
   require_relative "llm/message"
   require_relative "llm/response"
+  require_relative "llm/mime"
+  require_relative "llm/multipart"
   require_relative "llm/file"
   require_relative "llm/model"
   require_relative "llm/provider"
-  require_relative "llm/conversation"
-  require_relative "llm/message_queue"
+  require_relative "llm/chat"
+  require_relative "llm/buffer"
   require_relative "llm/core_ext/ostruct"
 
   module_function

data/llm.gemspec

@@ -14,12 +14,11 @@ Gem::Specification.new do |spec|
                  "flexible, and easy to use."
   spec.description = spec.summary
   spec.homepage = "https://github.com/llmrb/llm"
-  spec.license = "MIT"
+  spec.license = "0BSDL"
   spec.required_ruby_version = ">= 3.0.0"
 
   spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["source_code_uri"] = "https://github.com/llmrb/llm"
-  spec.metadata["changelog_uri"] = "https://github.com/llmrb/llm/blob/main/CHANGELOG.md"
 
   spec.files = Dir[
     "README.md", "LICENSE.txt",
@@ -29,10 +28,6 @@ Gem::Specification.new do |spec|
   ]
   spec.require_paths = ["lib"]
 
-  spec.add_runtime_dependency "net-http", "~> 0.6.0"
-  spec.add_runtime_dependency "json"
-  spec.add_runtime_dependency "yaml"
-
   spec.add_development_dependency "webmock", "~> 3.24.0"
   spec.add_development_dependency "yard", "~> 0.9.37"
   spec.add_development_dependency "kramdown", "~> 2.4"

data/spec/anthropic/completion_spec.rb

@@ -37,7 +37,7 @@ RSpec.describe "LLM::Anthropic: completions" do
       end
 
       it "includes the response" do
-        expect(choice.extra[:completion]).to eq(response)
+        expect(choice.extra[:response]).to eq(response)
       end
     end
   end

data/spec/gemini/completion_spec.rb

@@ -41,7 +41,7 @@ RSpec.describe "LLM::Gemini: completions" do
       end
 
       it "includes the response" do
-        expect(choice.extra[:completion]).to eq(response)
+        expect(choice.extra[:response]).to eq(response)
       end
     end
   end

data/spec/gemini/conversation_spec.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "setup"
+
+RSpec.describe "LLM::Chat: gemini" do
+  let(:described_class) { LLM::Chat }
+  let(:provider) { LLM.gemini(token) }
+  let(:token) { ENV["LLM_SECRET"] || "TOKEN" }
+  let(:conversation) { described_class.new(provider, **params).lazy }
+
+  context "when asked to describe an image",
+          vcr: {cassette_name: "gemini/conversations/multimodal_response"} do
+    subject { conversation.last_message }
+
+    let(:params) { {} }
+    let(:image) { LLM::File("spec/fixtures/images/bluebook.png") }
+
+    before do
+      conversation.chat(image, :user)
+      conversation.chat("Describe the image with a short sentance", :user)
+    end
+
+    it "describes the image" do
+      is_expected.to have_attributes(
+        role: "model",
+        content: "That's a simple illustration of a book " \
+                 "resting on a blue, X-shaped book stand.\n"
+      )
+    end
+  end
+end

data/spec/gemini/files_spec.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require "setup"
+
+RSpec.describe "LLM::Gemini::Files" do
+  let(:token) { ENV["LLM_SECRET"] || "TOKEN" }
+  let(:provider) { LLM.gemini(token) }
+
+  context "when given a successful create operation (bismillah.mp3)",
+          vcr: {cassette_name: "gemini/files/successful_create_bismillah"} do
+    subject(:file) { provider.files.create(file: LLM::File("spec/fixtures/audio/bismillah.mp3")) }
+    after { provider.files.delete(file:) }
+
+    it "is successful" do
+      expect(file).to be_instance_of(LLM::Response::File)
+    end
+
+    it "returns a file object" do
+      expect(file).to have_attributes(
+        name: instance_of(String),
+        display_name: "bismillah.mp3"
+      )
+    end
+  end
+
+  context "when given a successful delete operation (bismillah.mp3)",
+          vcr: {cassette_name: "gemini/files/successful_delete_bismillah"} do
+    let(:file) { provider.files.create(file: LLM::File("spec/fixtures/audio/bismillah.mp3")) }
+    subject { provider.files.delete(file:) }
+
+    it "is successful" do
+      is_expected.to be_instance_of(Net::HTTPOK)
+    end
+  end
+
+  context "when given a successful get operation (bismillah.mp3)",
+          vcr: {cassette_name: "gemini/files/successful_get_bismillah"} do
+    let(:file) { provider.files.create(file: LLM::File("spec/fixtures/audio/bismillah.mp3")) }
+    subject { provider.files.get(file:) }
+    after { provider.files.delete(file:) }
+
+    it "is successful" do
+      is_expected.to be_instance_of(LLM::Response::File)
+    end
+
+    it "returns a file object" do
+      is_expected.to have_attributes(
+        name: instance_of(String),
+        display_name: "bismillah.mp3"
+      )
+    end
+  end
+
+  context "when given a successful translation operation (bismillah.mp3)",
+          vcr: {cassette_name: "gemini/files/successful_translation_bismillah"} do
+    subject { bot.last_message.content }
+    let(:file) { provider.files.create(file: LLM::File("spec/fixtures/audio/bismillah.mp3")) }
+    let(:bot) { LLM::Chat.new(provider).lazy }
+    after { provider.files.delete(file:) }
+
+    before do
+      bot.chat file
+      bot.chat "Translate the contents of the audio file into English"
+      bot.chat "The audio is referenced in the first message I sent to you"
+      bot.chat "Provide no other content except the translation"
+    end
+
+    it "translates the audio clip" do
+      is_expected.to eq("In the name of Allah, the Most Gracious, the Most Merciful.\n")
+    end
+  end
+
+  context "when given a successful translation operation (alhamdullilah.mp3)",
+          vcr: {cassette_name: "gemini/files/successful_translation_alhamdullilah"} do
+    subject { bot.last_message.content }
+    let(:file) { provider.files.create(file: LLM::File("spec/fixtures/audio/alhamdullilah.mp3")) }
+    let(:bot) { LLM::Chat.new(provider).lazy }
+    after { provider.files.delete(file:) }
+
+    before do
+      bot.chat [
+        "Translate the contents of the audio file into English",
+        "Provide no other content except the translation",
+        file
+      ]
+    end
+
+    it "translates the audio clip" do
+      is_expected.to eq("All praise is due to Allah, Lord of the worlds.\n")
+    end
+  end
+
+  context "when given a successful all operation",
+          vcr: {cassette_name: "gemini/files/successful_all"} do
+    let!(:files) do
+      [
+        provider.files.create(file: LLM::File("spec/fixtures/audio/bismillah.mp3")),
+        provider.files.create(file: LLM::File("spec/fixtures/audio/alhamdullilah.mp3"))
+      ]
+    end
+
+    subject(:response) { provider.files.all }
+    after { files.each { |file| provider.files.delete(file:) } }
+
+    it "is successful" do
+      expect(response).to be_instance_of(LLM::Response::FileList)
+    end
+
+    it "returns an array of file objects" do
+      expect(response).to match_array(
+        [
+          have_attributes(
+            name: instance_of(String),
+            display_name: "bismillah.mp3"
+          ),
+          have_attributes(
+            name: instance_of(String),
+            display_name: "alhamdullilah.mp3"
+          )
+        ]
+      )
+    end
+  end
+end

data/spec/gemini/images_spec.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "setup"
+
+RSpec.describe "LLM::Gemini::Images" do
+  let(:token) { ENV["LLM_SECRET"] || "TOKEN" }
+  let(:provider) { LLM.gemini(token) }
+
+  context "when given a successful create operation",
+        vcr: {cassette_name: "gemini/images/successful_create"} do
+    subject(:response) { provider.images.create(prompt: "A dog on a rocket to the moon") }
+
+    it "is successful" do
+      expect(response).to be_instance_of(LLM::Response::Image)
+    end
+
+    it "returns an encoded string" do
+      expect(response.images[0].encoded).to be_instance_of(String)
+    end
+
+    it "returns a binary string" do
+      expect(response.images[0].binary).to be_instance_of(String)
+    end
+  end
+
+  context "when given a successful edit operation",
+        vcr: {cassette_name: "gemini/images/successful_edit"} do
+    subject(:response) do
+      provider.images.edit(
+        image: LLM::File("spec/fixtures/images/bluebook.png"),
+        prompt: "Book is floating in the clouds"
+      )
+    end
+
+    it "is successful" do
+      expect(response).to be_instance_of(LLM::Response::Image)
+    end
+
+    it "returns data" do
+      expect(response.images[0].encoded).to be_instance_of(String)
+    end
+
+    it "returns a url" do
+      expect(response.images[0].binary).to be_instance_of(String)
+    end
+  end
+end