llm.rb 0.10.1 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 39e538d8185cf5c8c5a36da0e1bf5b0b9e0055945a02570cd00fefc805b288d0
-  data.tar.gz: 7fc0d3a4422fe10bb3058c7b1b5b9bc80693ccc0dbf6b62bda46d42fb7c2830c
+  metadata.gz: ce6a4e56ce25f397337733009249edb930cade1641bd84d7939ef0d349c6e92a
+  data.tar.gz: b9506c346dd19af655f342e9b6a64aed25cd3f4ecffb6bb32cb36e1221e71c6a
 SHA512:
-  metadata.gz: a2b3de69ce317d856ec593074e22883ec2b96ddcdc2637cb2b4c555885c1c771b2ffd447b255cdc16a2c7f1c2b72362ab1b6e29ec0fdf775e977292b03fd3e34
-  data.tar.gz: c2ba0f853b7eaac4ca8fab15f497a3fa375e054b7da928b2f0798e393909baff20d2381afd48e793fd878261a0d838474e4be3be5b5232e480cf162af57dbe2e
+  metadata.gz: a4a53b8e5aeaae2cd26f5303366ce1974ecfdb4176a76c5aa01f46cb9997d10a402de782b0b14f97bf3c65dc4c200b976c1279a037ce29ae44ab64fd1799ffd9
+  data.tar.gz: 96128a756147d8cad13e85f91247fdb43b6bf5c469348318c27f27518670c61b6466546d65bf1f553b086b2a42b15a5225e0ac5355b680ba46214b32bc20d754

data/README.md

@@ -10,7 +10,7 @@ images, files, and JSON Schema generation.
 #### General
 - ✅ A single unified interface for multiple providers
 - 📦 Zero dependencies outside Ruby's standard library
-- 🚀 Efficient API design that minimizes the request count
+- 🚀 Efficient API design that minimizes the number of requests made
 
 #### Chat, Agents
 - 🧠 Stateless and stateful chat via completions and responses API
@@ -27,24 +27,7 @@ images, files, and JSON Schema generation.
 #### Miscellaneous
 - 🧮 Text embeddings and vector support
 - 🔌 Retrieve models dynamically for introspection and selection
-
-## Demos
-
-> The
-> [llmrb/llm-shell](https://github.com/llmrb/llm-shell)
-> project is built with llm.rb and its demos have been
-> included to provide a better idea of what llm.rb
-> is capable of.
-
-<details>
-  <summary><b>1. An introduction to tool calls</b></summary>
-  <img src="https://github.com/llmrb/llm/raw/main/share/llm-shell/examples/toolcalls_v2.gif">
-</details>
-
-<details>
-  <summary><b>2. Add files as conversation context</b></summary>
-  <img src="https://github.com/llmrb/llm/raw/main/share/llm-shell/examples/files-runtime_v2.gif">
-</details>
+- 🧱 Includes support for OpenAI's responses, moderations, and vector stores APIs
 
 ## Examples
 
@@ -67,7 +50,6 @@ llm = LLM.openai(key: "yourapikey")
 llm = LLM.gemini(key: "yourapikey")
 llm = LLM.anthropic(key: "yourapikey")
 llm = LLM.deepseek(key: "yourapikey")
-llm = LLM.voyageai(key: "yourapikey")
 
 ##
 # local providers
@@ -86,24 +68,24 @@ llm = LLM.llamacpp(key: nil)
 
 The following example creates an instance of
 [LLM::Bot](https://0x1eef.github.io/x/llm.rb/LLM/Bot.html)
-by entering into a conversation where messages are buffered and
-sent to the provider on-demand. This is the default behavior
-because it can reduce the number of requests sent to a provider,
-and avoids unneccessary requests until an attempt to iterate over
+and enters into a conversation where messages are buffered and
+sent to the provider on-demand. The implementation is designed to
+buffer messages by waiting until an attempt to iterate over
 [LLM::Bot#messages](https://0x1eef.github.io/x/llm.rb/LLM/Bot.html#messages-instance_method)
-is made:
+is made before sending a request to the LLM:
 
 ```ruby
 #!/usr/bin/env ruby
 require "llm"
 
-llm  = LLM.openai(key: ENV["KEY"])
+llm  = LLM.openai(key: ENV["OPENAI_SECRET"])
 bot  = LLM::Bot.new(llm)
+url  = "https://upload.wikimedia.org/wikipedia/commons/thumb/9/9a/Cognac_glass.jpg/500px-Cognac_glass.jpg"
 msgs = bot.chat do |prompt|
-  prompt.system File.read("./share/llm/prompts/system.txt")
-  prompt.user "Tell me the answer to 5 + 15"
-  prompt.user "Tell me the answer to (5 + 15) * 2"
-  prompt.user "Tell me the answer to ((5 + 15) * 2) / 10"
+  prompt.system "Your task is to answer all user queries"
+  prompt.user ["Tell me about this URL", URI(url)]
+  prompt.user ["Tell me about this pdf", File.open("spec/fixtures/documents/freebsd.sysctl.pdf", "r")]
+  prompt.user "Is the URL and PDF similar to each other?"
 end
 
 # At this point, we execute a single request
@@ -118,27 +100,24 @@ msgs.each { print "[#{_1.role}] ", _1.content, "\n" }
 > [docs/](docs/STREAMING.md#scopes) for more details.
 
 The following example streams the messages in a conversation
-as they are generated in real-time. This feature can be useful
-when you want to stream a conversation in real time, or when you
-want to avoid potential read timeouts during the generation of a
-response.
-
-The `stream` option can be set to an IO object, or the value `true`
-to enable streaming &ndash; and at the end of the request, `bot.chat`
-returns the same response as the non-streaming version which allows
-you to process a response in the same way:
+as they are generated in real-time. The `stream` option can
+be set to an IO object, or the value `true` to enable streaming
+&ndash; and at the end of the request, `bot.chat` returns the
+same response as the non-streaming version which allows you
+to process a response in the same way:
 
 ```ruby
 #!/usr/bin/env ruby
 require "llm"
 
-llm = LLM.openai(key: ENV["KEY"])
+llm = LLM.openai(key: ENV["OPENAI_SECRET"])
 bot = LLM::Bot.new(llm)
+url = "https://upload.wikimedia.org/wikipedia/commons/thumb/9/9a/Cognac_glass.jpg/500px-Cognac_glass.jpg"
 bot.chat(stream: $stdout) do |prompt|
-  prompt.system "You are my math assistant."
-  prompt.user "Tell me the answer to 5 + 15"
-  prompt.user "Tell me the answer to (5 + 15) * 2"
-  prompt.user "Tell me the answer to ((5 + 15) * 2) / 10"
+  prompt.system "Your task is to answer all user queries"
+  prompt.user ["Tell me about this URL", URI(url)]
+  prompt.user ["Tell me about this pdf", File.open("spec/fixtures/documents/freebsd.sysctl.pdf", "r")]
+  prompt.user "Is the URL and PDF similar to each other?"
 end.to_a
 ```
 
@@ -197,11 +176,7 @@ The
 method returns an array of functions that can be called after sending a message and
 it will only be populated if the LLM detects a function should be called. Each function
 corresponds to an element in the "tools" array. The array is emptied after a function call,
-and potentially repopulated on the next message.
-
-The following example defines an agent that can run system commands based on natural language,
-and it is only intended to be a fun demo of tool calling - it is not recommended to run
-arbitrary commands from a LLM without sanitizing the input first :) Without further ado:
+and potentially repopulated on the next message:
 
 ```ruby
 #!/usr/bin/env ruby
@@ -213,10 +188,10 @@ tool = LLM.function(:system) do |fn|
   fn.params do |schema|
     schema.object(command: schema.string.required)
   end
-  fn.define do |params|
+  fn.define do |command:|
     ro, wo = IO.pipe
     re, we = IO.pipe
-    Process.wait Process.spawn(params.command, out: wo, err: we)
+    Process.wait Process.spawn(command, out: wo, err: we)
     [wo,we].each(&:close)
     {stderr: re.read, stdout: ro.read}
   end
@@ -236,6 +211,60 @@ bot.chat bot.functions.map(&:call) # report return value to the LLM
 # {stderr: "", stdout: "FreeBSD"}
 ```
 
+### Files
+
+#### Create
+
+The OpenAI and Gemini providers provide a Files API where a client can upload files
+that can be referenced from a prompt, and with other APIs as well. The following
+example uses the OpenAI provider to describe the contents of a PDF file after
+it has been uploaded. The file (a specialized instance of
+[LLM::Response](https://0x1eef.github.io/x/llm.rb/LLM/Response.html)
+) is given as part of a prompt that is understood by llm.rb:
+
+```ruby
+#!/usr/bin/env ruby
+require "llm"
+
+llm = LLM.openai(key: ENV["KEY"])
+bot = LLM::Bot.new(llm)
+file = llm.files.create(file: "/books/goodread.pdf")
+bot.chat(["Tell me about this file", file])
+bot.messages.select(&:assistant?).each { print "[#{_1.role}] ", _1.content, "\n" }
+```
+
+### Prompts
+
+#### Multimodal
+
+It is generally a given that an LLM will understand text but they can also
+understand and generate other types of media as well: audio, images, video,
+and even URLs. The object given as a prompt in llm.rb can be a string to
+represent text, a URI object to represent a URL, an LLM::Response object
+to represent a file stored with the LLM, and so on. These are objects you
+can throw at the prompt and have them be understood automatically.
+
+A prompt can also have multiple parts, and in that case, an array is given
+as a prompt. Each element is considered to part of the prompt:
+
+```ruby
+#!/usr/bin/env ruby
+require "llm"
+
+llm = LLM.openai(key: ENV["KEY"])
+bot = LLM::Bot.new(llm)
+
+bot.chat ["Tell me about this URL", URI("https://example.com/path/to/image.png")]
+[bot.messages.find(&:assistant?)].each { print "[#{_1.role}] ", _1.content, "\n" }
+
+file = llm.files.create(file: "/books/goodread.pdf")
+bot.chat ["Tell me about this PDF", file]
+[bot.messages.find(&:assistant?)].each { print "[#{_1.role}] ", _1.content, "\n" }
+
+bot.chat ["Tell me about this image", File.open("/images/nemothefish.png", "r")]
+[bot.messages.find(&:assistant?)].each { print "[#{_1.role}] ", _1.content, "\n" }
+```
+
 ### Audio
 
 #### Speech
@@ -363,71 +392,6 @@ 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:
-
-
-```ruby
-#!/usr/bin/env ruby
-require "llm"
-
-llm = LLM.openai(key: ENV["KEY"])
-bot = LLM::Bot.new(llm)
-file = llm.files.create(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.
-```
-
-### 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 aforementioned objects to describe multiple objects in a single
-prompt. Each object is a first class citizen that can be passed directly
-to a prompt:
-
-```ruby
-#!/usr/bin/env ruby
-require "llm"
-
-llm = LLM.openai(key: ENV["KEY"])
-bot = LLM::Bot.new(llm)
-
-bot.chat [URI("https://example.com/path/to/image.png"), "Describe the image in the link"]
-bot.messages.select(&:assistant?).each { print "[#{_1.role}] ", _1.content, "\n" }
-
-file = llm.files.create(file: "/documents/openbsd_is_awesome.pdf")
-bot.chat [file, "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
@@ -453,7 +417,7 @@ print res.embeddings.size, "\n"
 print res.embeddings[0].size, "\n"
 
 ##
-# LLM::Response::Embedding
+# LLM::Response
 # 3
 # 1536
 ```

data/lib/llm/bot/builder.rb

@@ -9,7 +9,7 @@ class LLM::Bot
     ##
     # @param [String] prompt The prompt
     # @param [Hash] params
-    # @return [LLM::Response::Respond]
+    # @return [LLM::Response]
     def create_response!(prompt, params)
       @provider.responses.create(
         prompt,
@@ -20,7 +20,7 @@ class LLM::Bot
     ##
     # @param [String] prompt The prompt
     # @param [Hash] params
-    # @return [LLM::Response::Completion]
+    # @return [LLM::Response]
     def create_completion!(prompt, params)
       @provider.complete(
         prompt,

data/lib/llm/bot.rb

@@ -2,10 +2,10 @@
 
 module LLM
   ##
-  # {LLM::Bot LLM::Bot} provides a bot object that can maintain a
+  # {LLM::Bot LLM::Bot} provides an object that can maintain a
   # a conversation. A conversation can use the chat completions API
-  # that all LLM providers support or the responses API that a select
-  # few LLM providers support.
+  # that all LLM providers support or the responses API that currently
+  # only OpenAI supports.
   #
   # @example example #1
   #   #!/usr/bin/env ruby
@@ -14,10 +14,9 @@ module LLM
   #   llm  = LLM.openai(ENV["KEY"])
   #   bot  = LLM::Bot.new(llm)
   #   msgs = bot.chat do |prompt|
-  #     prompt.system "Answer the following questions."
-  #     prompt.user "What is 5 + 7 ?"
-  #     prompt.user "Why is the sky blue ?"
-  #     prompt.user "Why did the chicken cross the road ?"
+  #     prompt.user "What programming language should I learn next ?"
+  #     prompt.user "Can you recommend a good book ?"
+  #     prompt.user "Can you suggest a fun project to practice ?"
   #   end
   #   msgs.each { print "[#{_1.role}]", _1.content, "\n" }
   #
@@ -27,10 +26,9 @@ module LLM
   #
   #   llm = LLM.openai(ENV["KEY"])
   #   bot = LLM::Bot.new(llm)
-  #   bot.chat "Answer the following questions.", role: :system
-  #   bot.chat "What is 5 + 7 ?", role: :user
-  #   bot.chat "Why is the sky blue ?", role: :user
-  #   bot.chat "Why did the chicken cross the road ?", role: :user
+  #   bot.chat "What programming language should I learn next ?", role: :user
+  #   bot.chat "Can you recommend a good book ?", role: :user
+  #   bot.chat "Can you suggest a fun project to practice ?", role: :user
   #   bot.messages.each { print "[#{_1.role}]", _1.content, "\n" }
   class Bot
     require_relative "bot/prompt/completion"

data/lib/llm/file.rb

@@ -29,12 +29,19 @@ class LLM::File
   end
 
   ##
-  # @return [String]
+  # @return [Boolean]
   #  Returns true if the file is an image
   def image?
     mime_type.start_with?("image/")
   end
 
+  ##
+  # @return [Boolean]
+  #  Returns true if the file is a PDF document
+  def pdf?
+    mime_type == "application/pdf"
+  end
+
   ##
   # @return [Integer]
   #  Returns the size of the file in bytes
@@ -68,14 +75,16 @@ class LLM::File
 end
 
 ##
-# @param [String] path
-#  The path to a file
+# @param [String, File, LLM::Response] obj
+#  The path to the file, or an existing file reference
 # @return [LLM::File]
-def LLM.File(path)
-  case path
-  when LLM::File, LLM::Response::File
-    path
-  else
-    LLM::File.new(path)
+def LLM.File(obj)
+  case obj
+  when File
+    obj.close unless obj.closed?
+    LLM.File(obj.path)
+  when LLM::File, LLM::Response then obj
+  when String then LLM::File.new(obj)
+  else raise TypeError, "don't know how to handle #{obj.class} objects"
   end
 end

data/lib/llm/function.rb

@@ -10,15 +10,15 @@
 #     fn.params do |schema|
 #       schema.object(command: schema.string.required)
 #     end
-#     fn.define do |params|
-#       {success: Kernel.system(params.command)}
+#     fn.define do |command:|
+#       {success: Kernel.system(command)}
 #     end
 #   end
 #
 # @example example #2
 #   class System
-#     def call(params)
-#       {success: Kernel.system(params.command)}
+#     def call(command:)
+#       {success: Kernel.system(command)}
 #     end
 #   end
 #
@@ -91,7 +91,8 @@ class LLM::Function
   # Call the function
   # @return [LLM::Function::Return] The result of the function call
   def call
-    Return.new id, (Class === @runner) ? @runner.new.call(arguments) : @runner.call(arguments)
+    runner = ((Class === @runner) ? @runner.new : @runner)
+    Return.new(id, runner.call(**arguments))
   ensure
     @called = true
   end

data/lib/llm/message.rb

@@ -109,6 +109,14 @@ module LLM
       tool_calls.any?
     end
 
+    ##
+    # @return [Boolean]
+    #  Returns true when the message represents a function return
+    def tool_return?
+      LLM::Function::Return === content ||
+        [*content].grep(LLM::Function::Return).any?
+    end
+
     ##
     # Returns a string representation of the message
     # @return [String]

data/lib/llm/object/kernel.rb

@@ -12,6 +12,10 @@ class LLM::Object
       ::Kernel.instance_method(:instance_of?).bind(self).call(...)
     end
 
+    def extend(...)
+      ::Kernel.instance_method(:extend).bind(self).call(...)
+    end
+
     def method(...)
       ::Kernel.instance_method(:method).bind(self).call(...)
     end
@@ -41,5 +45,9 @@ class LLM::Object
       "#<#{self.class}:0x#{object_id.to_s(16)} properties=#{to_h.inspect}>"
     end
     alias_method :to_s, :inspect
+
+    def pretty_print(q)
+      q.text(inspect)
+    end
   end
 end

data/lib/llm/object.rb

@@ -62,6 +62,13 @@ class LLM::Object < BasicObject
   def to_h
     @h
   end
+  alias_method :to_hash, :to_h
+
+  ##
+  # @return [Object, nil]
+  def dig(...)
+    to_h.dig(...)
+  end
 
   private
 

data/lib/llm/provider.rb

@@ -44,7 +44,7 @@ class LLM::Provider
   #  Other embedding parameters
   # @raise [NotImplementedError]
   #  When the method is not implemented by a subclass
-  # @return [LLM::Response::Embedding]
+  # @return [LLM::Response]
   def embed(input, model: nil, **params)
     raise NotImplementedError
   end
@@ -68,7 +68,7 @@ class LLM::Provider
   # @option params [Array<LLM::Function>, nil] :tools Defaults to nil
   # @raise [NotImplementedError]
   #  When the method is not implemented by a subclass
-  # @return [LLM::Response::Completion]
+  # @return [LLM::Response]
   def complete(prompt, params = {})
     raise NotImplementedError
   end
@@ -174,6 +174,13 @@ class LLM::Provider
     raise NotImplementedError
   end
 
+  ##
+  # @return [LLM::OpenAI::VectorStore]
+  #  Returns an interface to the vector stores API
+  def vector_stores
+    raise NotImplementedError
+  end
+
   ##
   # @return [String]
   #  Returns the role of the assistant in the conversation.
@@ -222,15 +229,6 @@ class LLM::Provider
     raise NotImplementedError
   end
 
-  ##
-  # @return [Module]
-  #  Returns the module responsible for parsing a successful LLM response
-  # @raise [NotImplementedError]
-  #  (see LLM::Provider#complete)
-  def response_parser
-    raise NotImplementedError
-  end
-
   ##
   # @return [Class]
   #  Returns the class responsible for handling an unsuccessful LLM response

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

@@ -47,13 +47,18 @@ module LLM::Anthropic::Format
         content.empty? ? throw(:abort, nil) : content.flat_map { format_content(_1) }
       when URI
         [{type: :image, source: {type: "url", url: content.to_s}}]
+      when File
+        content.close unless content.closed?
+        format_content(LLM.File(content.path))
       when LLM::File
         if content.image?
           [{type: :image, source: {type: "base64", media_type: content.mime_type, data: content.to_b64}}]
+        elsif content.pdf?
+          [{type: :document, 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"
+          raise LLM::PromptError, "The given object (an instance of #{content.class}) " \
+                                  "is not an image or PDF, and therefore not supported by the " \
+                                  "Anthropic API"
         end
       when String
         [{type: :text, text: content}]
@@ -62,8 +67,8 @@ module LLM::Anthropic::Format
       when LLM::Function::Return
         [{type: "tool_result", tool_use_id: content.id, content: [{type: :text, text: JSON.dump(content.value)}]}]
       else
-        raise LLM::Error::PromptError, "The given object (an instance of #{content.class}) " \
-                                       "is not supported by the Anthropic API"
+        raise LLM::PromptError, "The given object (an instance of #{content.class}) " \
+                                "is not supported by the Anthropic API"
       end
     end
 

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

@@ -36,17 +36,12 @@ class LLM::Anthropic
     # @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]
+    # @return [LLM::Response]
     def all(**params)
       query = URI.encode_www_form(params)
       req = Net::HTTP::Get.new("/v1/models?#{query}", headers)
       res = execute(request: 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
-      }
+      LLM::Response.new(res)
     end
 
     private