llm.rb 0.10.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 15ddbff68b600d6a8926e872ed687edaff585ed075136415c8b8921438c5d32f
-  data.tar.gz: bf498f154df07de201f1529253559db03e850182afdf84eb6b99efb527920a2f
+  metadata.gz: ce6a4e56ce25f397337733009249edb930cade1641bd84d7939ef0d349c6e92a
+  data.tar.gz: b9506c346dd19af655f342e9b6a64aed25cd3f4ecffb6bb32cb36e1221e71c6a
 SHA512:
-  metadata.gz: 6256cf08682c5f9bf5aff9a6065aec57e23e8f68bc54acd302eee4f6c08628feddf438043e58898611be6ffa0d61c07f437da3c6cd16007d256c6fd4adee4218
-  data.tar.gz: a7c0510691a9aa08447dc65146a763a37ca1aefb59de9ee10c2eca691d725a971d9dcdc35dc1316ff473b3ff002ef1b5c2963601a8044ec70b2c2302132e4627
+  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,29 +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. Tools: "system" function</b></summary>
-  <img src="https://github.com/llmrb/llm/raw/main/share/llm-shell/examples/toolcalls.gif">
-</details>
-
-<details>
-  <summary><b>2. Files: import at runtime</b></summary>
-  <img src="https://github.com/llmrb/llm/raw/main/share/llm-shell/examples/files-runtime.gif">
-</details>
-
-<details>
-  <summary><b>3. Files: import at boot time</b></summary>
-  <img src="https://github.com/llmrb/llm/raw/main/share/llm-shell/examples/files-boottime.gif">
-</details>
+- 🧱 Includes support for OpenAI's responses, moderations, and vector stores APIs
 
 ## Examples
 
@@ -72,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
@@ -91,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
@@ -123,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
 ```
 
@@ -202,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
@@ -218,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
@@ -241,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
@@ -368,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
@@ -458,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
 #
@@ -33,6 +33,11 @@ class LLM::Function
   class Return < Struct.new(:id, :value)
   end
 
+  ##
+  # Returns the function ID
+  # @return [String, nil]
+  attr_accessor :id
+
   ##
   # Returns the function name
   # @return [String]
@@ -43,11 +48,6 @@ class LLM::Function
   # @return [Array, nil]
   attr_accessor :arguments
 
-  ##
-  # Returns the function ID
-  # @return [String, nil]
-  attr_accessor :id
-
   ##
   # @param [String] name The function name
   # @yieldparam [LLM::Function] self The function object
@@ -61,10 +61,14 @@ class LLM::Function
 
   ##
   # Set the function description
-  # @param [String] str The function description
+  # @param [String] desc The function description
   # @return [void]
-  def description(str)
-    @description = str
+  def description(desc = nil)
+    if desc
+      @description = desc
+    else
+      @description
+    end
   end
 
   ##
@@ -87,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