llm.rb 0.3.2 → 0.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3c55653b476d2fe6fe9457c89bc430c698668312ce89660a1d69abd8adf338eb
-  data.tar.gz: fe7d456bbb739eb091e82351839baef4c64d1d108a2c4cd7de3eb1b478982631
+  metadata.gz: c8ce8caa7c769da9197528a864c153071f3c4aca15718efc985e543911c04ce2
+  data.tar.gz: 389ff41e9e2b35782b1484048b7597f5573bf2a86cf9eaff8cfd7c4cb2b19be3
 SHA512:
-  metadata.gz: 8cd55bb28eb92fea745d8b11062b2442bf4b2de88ecfb0b7dc99cfefd293bd45113088dd13ccfe7e251d2e369459da700f15725bae51c3d31d4bf68e19953138
-  data.tar.gz: dab47021b94d00e51e7d0ca3f92e2966170b9fd8ce7138e0728d2be7fb83da03104ff93cd7c54b760acca62dd03adf16462069db9eb5c30185743c25259105aa
+  metadata.gz: 39c8f71eae878b5787ca839138de07ce06cba4fdee0bafb1bd75a71f3b3e59ee08fa05f5d9f280522ec751722c9a8a15430d1b999b05e14052d85c745bf9781c
+  data.tar.gz: fdb5268b0095f09b41481e6c7071a2dae66cf9a3fd21755834b76040e13a236bc18122dfe95230dd49a827e774487a1add1aa35c8976f284a03afad881321b46

data/README.md

@@ -38,7 +38,9 @@ The following example enables lazy mode for a
 object by entering into a "lazy" conversation where messages are buffered and
 sent to the provider only when necessary.  Both lazy and non-lazy conversations
 maintain a message thread that can be reused as context throughout a conversation.
-The example uses the stateless chat completions API that all LLM providers support:
+The example captures the spirit of llm.rb by demonstrating how objects cooperate
+together through composition, and it uses the stateless chat completions API that
+all LLM providers support:
 
 ```ruby
 #!/usr/bin/env ruby
@@ -126,8 +128,7 @@ require "llm"
 
 llm = LLM.openai(ENV["KEY"])
 res = llm.audio.create_speech(input: "Hello world")
-File.binwrite File.join(Dir.home, "hello.mp3"),
-	          res.audio.string
+IO.copy_stream res.audio, File.join(Dir.home, "hello.mp3")
 ```
 
 #### Transcribe
@@ -388,6 +389,38 @@ print res.embeddings[0].size, "\n"
 # 1536
 ```
 
+### Models
+
+#### List
+
+Almost all LLM providers provide a models endpoint that allows a client to
+query the list of models that are available to use. The list is dynamic,
+maintained by LLM providers, and it is independent of a specific llm.rb release.
+True to the llm.rb spirit of small, composable objects that cooperate with
+each other, a
+[LLM::Model](https://0x1eef.github.io/x/llm.rb/LLM/Model.html)
+object can be used instead of a string that describes a model name (although
+either works). Let's take a look at an example:
+
+```ruby
+#!/usr/bin/env ruby
+require "llm"
+
+##
+# List all models
+llm = LLM.openai(ENV["KEY"])
+llm.models.all.each do |model|
+  print "model: ", model.id, "\n"
+end
+
+##
+# Select a model
+model = llm.models.all.find { |m| m.id == "gpt-3.5-turbo" }
+bot = LLM::Chat.new(llm, model:)
+bot.chat "Hello #{model.id} :)"
+bot.messages.select(&:assistant?).each { print "[#{_1.role}] ", _1.content, "\n" }
+```
+
 ### Memory
 
 #### Child process
@@ -410,7 +443,7 @@ llm = LLM.gemini(ENV["KEY"])
 fork do
   %w[dog cat sheep goat capybara].each do |animal|
     res = llm.images.create(prompt: "a #{animal} on a rocket to the moon")
-    File.binwrite "#{animal}.png", res.images[0].binary
+    IO.copy_stream res.images[0], "#{animal}.png"
   end
 end
 Process.wait
@@ -440,9 +473,9 @@ 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,
-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.
+no global configuration, no global state, 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.
 
 ## License
 

data/lib/llm/chat.rb

@@ -27,11 +27,13 @@ module LLM
     ##
     # @param [LLM::Provider] provider
     #  A provider
+    # @param [String] model
+    #  The model to maintain throughout the conversation
     # @param [Hash] params
-    #  The parameters to maintain throughout the conversation
-    def initialize(provider, params = {})
+    #  Other parameters to maintain throughout the conversation
+    def initialize(provider, model: provider.default_model, **params)
       @provider = provider
-      @params = params
+      @params = params.merge!(model:)
       @lazy = false
       @messages = []
     end

data/lib/llm/core_ext/ostruct.rb

@@ -18,7 +18,7 @@ class OpenStruct
       hash_obj.each do |key, value|
         visited_object[key] = walk(value)
       end
-      OpenStruct.new(visited_object)
+      new(visited_object)
     end
 
     private

data/lib/llm/file.rb

@@ -7,13 +7,20 @@
 class LLM::File
   ##
   # @return [String]
-  #  Returns the path to a file
+  #  Returns the path to the file
   attr_reader :path
 
   def initialize(path)
     @path = path
   end
 
+  ##
+  # @return [String]
+  #  Returns basename of the file
+  def basename
+    File.basename(path)
+  end
+
   ##
   # @return [String]
   #  Returns the MIME type of the file

data/lib/llm/model.rb

@@ -1,7 +1,32 @@
 # frozen_string_literal: true
 
-class LLM::Model < Struct.new(:name, :parameters, :description, :to_param, keyword_init: true)
+##
+# The {LLM::Model LLM::Model} class represents an LLM model that
+# is available to use. Its properties are delegated to the underlying
+# response body, and vary by provider.
+class LLM::Model < OpenStruct
+  ##
+  # Returns a subclass of {LLM::Provider LLM::Provider}
+  # @return [LLM::Provider]
+  attr_accessor :provider
+
+  ##
+  # Returns the model ID
+  # @return [String]
+  def id
+    case @provider.class.to_s
+    when "LLM::Ollama"
+      self["name"]
+    when "LLM::Gemini"
+      self["name"].sub(%r|\Amodels/|, "")
+    else
+      self["id"]
+    end
+  end
+
+  ##
+  # @return [String]
   def to_json(*)
-    to_param.to_json(*)
+    id.to_json(*)
   end
 end

data/lib/llm/provider.rb

@@ -44,7 +44,7 @@ class LLM::Provider
   # @raise [NotImplementedError]
   #  When the method is not implemented by a subclass
   # @return [LLM::Response::Embedding]
-  def embed(input, model:, **params)
+  def embed(input, model: nil, **params)
     raise NotImplementedError
   end
 
@@ -69,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: nil, **params)
+  def complete(prompt, role = :user, model: default_model, **params)
     raise NotImplementedError
   end
 
@@ -85,8 +85,8 @@ class LLM::Provider
   #  Other completion parameters to maintain throughout a chat
   # @raise (see LLM::Provider#complete)
   # @return [LLM::Chat]
-  def chat(prompt, role = :user, model: nil, **params)
-    LLM::Chat.new(self, params).lazy.chat(prompt, role)
+  def chat(prompt, role = :user, model: default_model, **params)
+    LLM::Chat.new(self, **params.merge(model:)).lazy.chat(prompt, role)
   end
 
   ##
@@ -101,8 +101,8 @@ class LLM::Provider
   #  Other completion parameters to maintain throughout a chat
   # @raise (see LLM::Provider#complete)
   # @return [LLM::Chat]
-  def chat!(prompt, role = :user, model: nil, **params)
-    LLM::Chat.new(self, params).chat(prompt, role)
+  def chat!(prompt, role = :user, model: default_model, **params)
+    LLM::Chat.new(self, **params.merge(model:)).chat(prompt, role)
   end
 
   ##
@@ -117,8 +117,8 @@ class LLM::Provider
   #  Other completion parameters to maintain throughout a chat
   # @raise (see LLM::Provider#complete)
   # @return [LLM::Chat]
-  def respond(prompt, role = :user, model: nil, **params)
-    LLM::Chat.new(self, params).lazy.respond(prompt, role)
+  def respond(prompt, role = :user, model: default_model, **params)
+    LLM::Chat.new(self, **params.merge(model:)).lazy.respond(prompt, role)
   end
 
   ##
@@ -133,8 +133,8 @@ class LLM::Provider
   #  Other completion parameters to maintain throughout a chat
   # @raise (see LLM::Provider#complete)
   # @return [LLM::Chat]
-  def respond!(prompt, role = :user, model: nil, **params)
-    LLM::Chat.new(self, params).respond(prompt, role)
+  def respond!(prompt, role = :user, model: default_model, **params)
+    LLM::Chat.new(self, **params.merge(model:)).respond(prompt, role)
   end
 
   ##
@@ -169,6 +169,13 @@ class LLM::Provider
     raise NotImplementedError
   end
 
+  ##
+  # @return [LLM::OpenAI::Models]
+  #  Returns an interface to the models API
+  def models
+    raise NotImplementedError
+  end
+
   ##
   # @return [String]
   #  Returns the role of the assistant in the conversation.
@@ -178,9 +185,9 @@ class LLM::Provider
   end
 
   ##
-  # @return [Hash<String, LLM::Model>]
-  #  Returns a hash of available models
-  def models
+  # @return [String]
+  #  Returns the default model for chat completions
+  def default_model
     raise NotImplementedError
   end
 
@@ -228,8 +235,6 @@ 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)
@@ -250,17 +255,4 @@ class LLM::Provider
     req.body_stream = io
     req["transfer-encoding"] = "chunked" unless req["content-length"]
   end
-
-  ##
-  # @param [String] provider
-  #  The name of the provider
-  # @return [Hash<String, Hash>]
-  def load_models!(provider)
-    require "yaml" unless defined?(YAML)
-    rootdir  = File.realpath File.join(__dir__, "..", "..")
-    sharedir = File.join(rootdir, "share", "llm")
-    provider = provider.gsub(/[^a-z0-9]/i, "")
-    yaml     = File.join(sharedir, "models", "#{provider}.yml")
-    YAML.safe_load_file(yaml).transform_values { LLM::Model.new(_1) }
-  end
 end

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

@@ -26,13 +26,26 @@ class LLM::Anthropic
     # @return [String, Hash]
     #  The formatted content
     def format_content(content)
-      if URI === content
-        [{
-          type: :image,
-          source: {type: :base64, media_type: LLM::File(content.to_s).mime_type, data: [content.to_s].pack("m0")}
-        }]
+      case content
+      when Array
+        content.flat_map { format_content(_1) }
+      when URI
+        [{type: :image, source: {type: "url", url: content.to_s}}]
+      when LLM::File
+        if content.image?
+          [{type: :image, source: {type: "base64", media_type: content.mime_type, data: content.to_b64}}]
+        else
+          raise LLM::Error::PromptError, "The given object (an instance of #{content.class}) " \
+                                          "is not an image, and therefore not supported by the " \
+                                          "Anthropic API"
+        end
+      when String
+        [{type: :text, text: content}]
+      when LLM::Message
+        format_content(content.content)
       else
-        content
+        raise LLM::Error::PromptError, "The given object (an instance of #{content.class}) " \
+                                       "is not supported by the Anthropic API"
       end
     end
   end

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

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+class LLM::Anthropic
+  ##
+  # The {LLM::Anthropic::Models LLM::Anthropic::Models} class provides a model
+  # object for interacting with [Anthropic's models API](https://platform.anthropic.com/docs/api-reference/models/list).
+  # The models API allows a client to query Anthropic for a list of models
+  # that are available for use with the Anthropic API.
+  #
+  # @example
+  #   #!/usr/bin/env ruby
+  #   require "llm"
+  #
+  #   llm = LLM.anthropic(ENV["KEY"])
+  #   res = llm.models.all
+  #   res.each do |model|
+  #     print "id: ", model.id, "\n"
+  #   end
+  class Models
+    ##
+    # Returns a new Models object
+    # @param provider [LLM::Provider]
+    # @return [LLM::Anthropic::Files]
+    def initialize(provider)
+      @provider = provider
+    end
+
+    ##
+    # List all models
+    # @example
+    #   llm = LLM.anthropic(ENV["KEY"])
+    #   res = llm.models.all
+    #   res.each do |model|
+    #     print "id: ", model.id, "\n"
+    #   end
+    # @see https://docs.anthropic.com/en/api/models-list Anthropic docs
+    # @param [Hash] params Other parameters (see Anthropic docs)
+    # @raise (see LLM::Provider#request)
+    # @return [LLM::Response::FileList]
+    def all(**params)
+      query = URI.encode_www_form(params)
+      req = Net::HTTP::Get.new("/v1/models?#{query}", headers)
+      res = request(http, req)
+      LLM::Response::ModelList.new(res).tap { |modellist|
+        models = modellist.body["data"].map do |model|
+          LLM::Model.from_hash(model).tap { _1.provider = @provider }
+        end
+        modellist.models = models
+      }
+    end
+
+    private
+
+    def http
+      @provider.instance_variable_get(:@http)
+    end
+
+    [:headers, :request].each do |m|
+      define_method(m) { |*args, &b| @provider.send(m, *args, &b) }
+    end
+  end
+end

data/lib/llm/providers/anthropic.rb

@@ -8,6 +8,7 @@ module LLM
     require_relative "anthropic/error_handler"
     require_relative "anthropic/response_parser"
     require_relative "anthropic/format"
+    require_relative "anthropic/models"
     include Format
 
     HOST = "api.anthropic.com"
@@ -45,16 +46,28 @@ module LLM
     # @param params (see LLM::Provider#complete)
     # @example (see LLM::Provider#complete)
     # @raise (see LLM::Provider#request)
+    # @raise [LLM::Error::PromptError]
+    #  When given an object a provider does not understand
     # @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)
-      req      = Net::HTTP::Post.new("/v1/messages", headers)
+    def complete(prompt, role = :user, model: default_model, max_tokens: 1024, **params)
+      params = {max_tokens:, model:}.merge!(params)
+      req = Net::HTTP::Post.new("/v1/messages", headers)
       messages = [*(params.delete(:messages) || []), Message.new(role, prompt)]
-      req.body = JSON.dump({messages: format(messages)}.merge!(params))
-      res      = request(@http, req)
+      body = JSON.dump({messages: format(messages)}.merge!(params))
+      set_body_stream(req, StringIO.new(body))
+
+      res = request(@http, req)
       Response::Completion.new(res).extend(response_parser)
     end
 
+    ##
+    # Provides an interface to Anthropic's models API
+    # @see https://docs.anthropic.com/en/api/models-list
+    # @return [LLM::Anthropic::Models]
+    def models
+      LLM::Anthropic::Models.new(self)
+    end
+
     ##
     # @return (see LLM::Provider#assistant_role)
     def assistant_role
@@ -62,9 +75,11 @@ module LLM
     end
 
     ##
-    # @return (see LLM::Provider#models)
-    def models
-      @models ||= load_models!("anthropic")
+    # Returns the default model for chat completions
+    # @see https://docs.anthropic.com/en/docs/about-claude/models/all-models#model-comparison-table claude-3-5-sonnet-20240620
+    # @return [String]
+    def default_model
+      "claude-3-5-sonnet-20240620"
     end
 
     private

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

@@ -35,8 +35,13 @@ class LLM::Gemini
       when LLM::File
         file = content
         {inline_data: {mime_type: file.mime_type, data: file.to_b64}}
-      else
+      when String
         {text: content}
+      when LLM::Message
+        format_content(content.content)
+      else
+        raise LLM::Error::PromptError, "The given object (an instance of #{content.class}) " \
+                                       "is not supported by the Gemini API"
       end
     end
   end

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

@@ -13,7 +13,7 @@ class LLM::Gemini
   #
   #   llm = LLM.gemini(ENV["KEY"])
   #   res = llm.images.create prompt: "A dog on a rocket to the moon"
-  #   File.binwrite "rocket.png", res.images[0].binary
+  #   IO.copy_stream res.images[0], "rocket.png"
   class Images
     include Format
 
@@ -30,7 +30,7 @@ class LLM::Gemini
     # @example
     #   llm = LLM.gemini(ENV["KEY"])
     #   res = llm.images.create prompt: "A dog on a rocket to the moon"
-    #   File.binwrite "rocket.png", res.images[0].binary
+    #   IO.copy_stream res.images[0], "rocket.png"
     # @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)
@@ -56,7 +56,7 @@ class LLM::Gemini
     # @example
     #   llm = LLM.gemini(ENV["KEY"])
     #   res = llm.images.edit image: LLM::File("cat.png"), prompt: "Add a hat to the cat"
-    #   File.binwrite "hatoncat.png", res.images[0].binary
+    #   IO.copy_stream res.images[0], "hatoncat.png"
     # @see https://ai.google.dev/gemini-api/docs/image-generation Gemini docs
     # @param [LLM::File] image The image to edit
     # @param [String] prompt The prompt

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

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+class LLM::Gemini
+  ##
+  # The {LLM::Gemini::Models LLM::Gemini::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.
+  #
+  # @example
+  #   #!/usr/bin/env ruby
+  #   require "llm"
+  #
+  #   llm = LLM.gemini(ENV["KEY"])
+  #   res = llm.models.all
+  #   res.each do |model|
+  #     print "id: ", model.id, "\n"
+  #   end
+  class Models
+    include LLM::Utils
+
+    ##
+    # Returns a new Models object
+    # @param provider [LLM::Provider]
+    # @return [LLM::Gemini::Models]
+    def initialize(provider)
+      @provider = provider
+    end
+
+    ##
+    # List all models
+    # @example
+    #   llm = LLM.gemini(ENV["KEY"])
+    #   res = llm.models.all
+    #   res.each do |model|
+    #     print "id: ", model.id, "\n"
+    #   end
+    # @see https://ai.google.dev/api/models?hl=en#method:-models.list Gemini docs
+    # @param [Hash] params Other parameters (see Gemini docs)
+    # @raise (see LLM::Provider#request)
+    # @return [LLM::Response::ModelList]
+    def all(**params)
+      query = URI.encode_www_form(params.merge!(key: secret))
+      req = Net::HTTP::Get.new("/v1beta/models?#{query}", headers)
+      res = request(http, req)
+      LLM::Response::ModelList.new(res).tap { |modellist|
+        models = modellist.body["models"].map do |model|
+          model = model.transform_keys { snakecase(_1) }
+          LLM::Model.from_hash(model).tap { _1.provider = @provider }
+        end
+        modellist.models = models
+      }
+    end
+
+    private
+
+    def http
+      @provider.instance_variable_get(:@http)
+    end
+
+    def secret
+      @provider.instance_variable_get(:@secret)
+    end
+
+    [:headers, :request].each do |m|
+      define_method(m) { |*args, &b| @provider.send(m, *args, &b) }
+    end
+  end
+end

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

@@ -44,11 +44,7 @@ class LLM::Gemini
         images: body["candidates"].flat_map do |candidate|
           candidate["content"]["parts"].filter_map do
             next unless _1.dig("inlineData", "data")
-            OpenStruct.from_hash(
-              mime_type: _1["inlineData"]["mimeType"],
-              encoded: _1["inlineData"]["data"],
-              binary: _1["inlineData"]["data"].unpack1("m0")
-            )
+            StringIO.new(_1["inlineData"]["data"].unpack1("m0"))
           end
         end
       }

data/lib/llm/providers/gemini.rb

@@ -34,6 +34,7 @@ module LLM
     require_relative "gemini/images"
     require_relative "gemini/files"
     require_relative "gemini/audio"
+    require_relative "gemini/models"
     include Format
 
     HOST = "generativelanguage.googleapis.com"
@@ -52,6 +53,7 @@ module LLM
     # @raise (see LLM::Provider#request)
     # @return (see LLM::Provider#embed)
     def embed(input, model: "text-embedding-004", **params)
+      model = model.respond_to?(:id) ? model.id : model
       path = ["/v1beta/models/#{model}", "embedContent?key=#{@secret}"].join(":")
       req = Net::HTTP::Post.new(path, headers)
       req.body = JSON.dump({content: {parts: [{text: input}]}})
@@ -68,13 +70,17 @@ module LLM
     # @param params (see LLM::Provider#complete)
     # @example (see LLM::Provider#complete)
     # @raise (see LLM::Provider#request)
+    # @raise [LLM::Error::PromptError]
+    #  When given an object a provider does not understand
     # @return (see LLM::Provider#complete)
-    def complete(prompt, role = :user, model: "gemini-1.5-flash", **params)
+    def complete(prompt, role = :user, model: default_model, **params)
+      model.respond_to?(:id) ? model.id : model
       path = ["/v1beta/models/#{model}", "generateContent?key=#{@secret}"].join(":")
       req  = Net::HTTP::Post.new(path, headers)
       messages = [*(params.delete(:messages) || []), LLM::Message.new(role, prompt)]
-      body = JSON.dump({contents: format(messages)}).b
+      body = JSON.dump({contents: format(messages)})
       set_body_stream(req, StringIO.new(body))
+
       res = request(@http, req)
       Response::Completion.new(res).extend(response_parser)
     end
@@ -101,6 +107,13 @@ module LLM
       LLM::Gemini::Files.new(self)
     end
 
+    ##
+    # Provides an interface to Gemini's models API
+    # @see https://ai.google.dev/gemini-api/docs/models Gemini docs
+    def models
+      LLM::Gemini::Models.new(self)
+    end
+
     ##
     # @return (see LLM::Provider#assistant_role)
     def assistant_role
@@ -108,9 +121,11 @@ module LLM
     end
 
     ##
-    # @return (see LLM::Provider#models)
-    def models
-      @models ||= load_models!("gemini")
+    # Returns the default model for chat completions
+    # @see https://ai.google.dev/gemini-api/docs/models#gemini-1.5-flash gemini-1.5-flash
+    # @return [String]
+    def default_model
+      "gemini-1.5-flash"
     end
 
     private

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

@@ -28,14 +28,22 @@ class LLM::Ollama
     # @return [String, Hash]
     #  The formatted content
     def format_content(content)
-      if LLM::File === content
+      case content
+      when LLM::File
         if content.image?
           {content: "This message has an image associated with it", images: [content.to_b64]}
         else
-          raise TypeError, "'#{content.path}' was not recognized as an image file."
+          raise LLM::Error::PromptError, "The given object (an instance of #{content.class}) " \
+                                         "is not an image, and therefore not supported by the " \
+                                         "Ollama API"
         end
-      else
+      when String
         {content:}
+      when LLM::Message
+        format_content(content.content)
+      else
+        raise LLM::Error::PromptError, "The given object (an instance of #{content.class}) " \
+                                       "is not supported by the Ollama API"
       end
     end
   end