llm.rb 0.11.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ce6a4e56ce25f397337733009249edb930cade1641bd84d7939ef0d349c6e92a
-  data.tar.gz: b9506c346dd19af655f342e9b6a64aed25cd3f4ecffb6bb32cb36e1221e71c6a
+  metadata.gz: 2cd935a4ccd3b911e92b5ff54335cfc143247cbb5fe55214fd563551f7349da4
+  data.tar.gz: c76b36f2877c0cec7fdde54471a81ae19a4ec044158077742eba9acd26cd1483
 SHA512:
-  metadata.gz: a4a53b8e5aeaae2cd26f5303366ce1974ecfdb4176a76c5aa01f46cb9997d10a402de782b0b14f97bf3c65dc4c200b976c1279a037ce29ae44ab64fd1799ffd9
-  data.tar.gz: 96128a756147d8cad13e85f91247fdb43b6bf5c469348318c27f27518670c61b6466546d65bf1f553b086b2a42b15a5225e0ac5355b680ba46214b32bc20d754
+  metadata.gz: f654d042a6f44cba15b2dc0049d3933aa442f631293be446486e524773ff01bfc0f13f89ecbf09659a175c3ff9f7c6512ae8bde5716f6935c8d3d05528d3e4e9
+  data.tar.gz: 73945113e01d89188301a1a7db921c8c07ac19a847fa71528bc2e62eb5162ac656aca02a5f17e02bc4918dc973c298f0021afbb14a4cb38e7f81705950c4ed5b

data/README.md

@@ -1,9 +1,9 @@
 ## About
 
 llm.rb is a zero-dependency Ruby toolkit for Large Language Models that
-includes OpenAI, Gemini, Anthropic, DeepSeek, Ollama, and LlamaCpp. The
-toolkit includes full support for chat, streaming, tool calling, audio,
-images, files, and JSON Schema generation.
+includes OpenAI, Gemini, Anthropic, xAI (grok), DeepSeek, Ollama, and
+LlamaCpp. The toolkit includes full support for chat, streaming, tool calling,
+audio, images, files, and JSON Schema generation.
 
 ## Features
 
@@ -24,10 +24,39 @@ images, files, and JSON Schema generation.
 - 📎 File uploads and prompt-aware file interaction
 - 💡 Multimodal prompts (text, images, PDFs, URLs, files)
 
-#### Miscellaneous
+#### Embeddings
 - 🧮 Text embeddings and vector support
-- 🔌 Retrieve models dynamically for introspection and selection
-- 🧱 Includes support for OpenAI's responses, moderations, and vector stores APIs
+- 🧱 Includes support for OpenAI's vector stores API
+
+#### Miscellaneous
+- 📜 Model management and selection
+- 🔧 Includes support for OpenAI's responses, moderations, and vector stores APIs
+
+## Matrix
+
+While the Features section above gives you the high-level picture, the table below
+breaks things down by provider, so you can see exactly what’s supported where.
+
+
+| Feature / Provider                  | OpenAI | Anthropic | Gemini | DeepSeek | xAI (Grok) | Ollama | LlamaCpp |
+|--------------------------------------|:------:|:---------:|:------:|:--------:|:----------:|:------:|:--------:|
+| **Chat Completions**                 | ✅     | ✅        | ✅     | ✅       | ✅         | ✅     | ✅       |
+| **Streaming**                        | ✅     | ✅        | ✅     | ✅       | ✅         | ✅     | ✅       |
+| **Tool Calling**                     | ✅     | ✅        | ✅     | ✅       | ✅         | ✅     | ✅       |
+| **JSON Schema / Structured Output**  | ✅     | ❌        | ✅     | ❌       | ✅         | ✅*    | ✅*      |
+| **Audio (TTS / Transcribe / Translate)** | ✅  | ❌        | ✅     | ❌       | ❌         | ❌     | ❌       |
+| **Image Generation & Editing**       | ✅     | ❌        | ✅     | ❌       | ✅         | ❌     | ❌       |
+| **File Uploads**                     | ✅     | ❌        | ✅     | ❌       | ❌         | ❌     | ❌       |
+| **Multimodal Prompts** *(text+image)* | ✅     | ✅        | ✅     | ✅       | ✅         | ✅     | ✅       |
+| **Embeddings**                       | ✅     | ✅        | ✅     | ✅       | ❌         | ✅     | ✅       |
+| **Models API**                       g| ✅     | ✅        | ✅     | ✅       | ✅         | ✅     | ✅       |
+| **Local Model Support**              | ❌     | ❌        | ❌     | ❌       | ❌         | ✅     | ✅       |
+| **Vector Stores (RAG)**               | ✅     | ❌        | ❌     | ❌       | ❌         | ❌     | ❌       |
+| **Responses**                        | ✅     | ❌        | ❌     | ❌       | ❌         | ❌     | ❌       |
+| **Moderations**                      | ✅     | ❌        | ❌     | ❌       | ❌         | ❌     | ❌       |
+
+\* JSON Schema support in Ollama/LlamaCpp depends on the model, not the API.
+
 
 ## Examples
 
@@ -49,6 +78,7 @@ require "llm"
 llm = LLM.openai(key: "yourapikey")
 llm = LLM.gemini(key: "yourapikey")
 llm = LLM.anthropic(key: "yourapikey")
+llm = LLM.xai(key: "yourapikey")
 llm = LLM.deepseek(key: "yourapikey")
 
 ##
@@ -78,13 +108,13 @@ is made before sending a request to the LLM:
 #!/usr/bin/env ruby
 require "llm"
 
-llm  = LLM.openai(key: ENV["OPENAI_SECRET"])
+llm  = LLM.openai(key: ENV["KEY"])
 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 "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 ["Tell me about this pdf", File.open("spec/fixtures/documents/freebsd.sysctl.pdf", "rb")]
   prompt.user "Is the URL and PDF similar to each other?"
 end
 
@@ -110,13 +140,13 @@ to process a response in the same way:
 #!/usr/bin/env ruby
 require "llm"
 
-llm = LLM.openai(key: ENV["OPENAI_SECRET"])
+llm = LLM.openai(key: ENV["KEY"])
 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 "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 ["Tell me about this pdf", File.open("spec/fixtures/documents/freebsd.sysctl.pdf", "rb")]
   prompt.user "Is the URL and PDF similar to each other?"
 end.to_a
 ```
@@ -137,7 +167,7 @@ require "llm"
 ##
 # Objects
 llm = LLM.openai(key: ENV["KEY"])
-schema = llm.schema.object(answer: llm.schema.integer.required)
+schema = llm.schema.object(probability: llm.schema.integer.required)
 bot = LLM::Bot.new(llm, schema:)
 bot.chat "Does the earth orbit the sun?", role: :user
 bot.messages.find(&:assistant?).content! # => {probability: 1}
@@ -245,7 +275,7 @@ 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:
+as a prompt. Each element is considered to be part of the prompt:
 
 ```ruby
 #!/usr/bin/env ruby
@@ -463,8 +493,15 @@ over or doesn't cover at all. The API reference is available at
 
 ### Guides
 
-The [docs/](docs/) directory contains some additional documentation that
-didn't quite make it into the README.
+* [An introduction to RAG with llm.rb](https://0x1eef.github.io/posts/an-introduction-to-rag-with-llm.rb/) –
+  a blog post that implements the RAG pattern in 32 lines of Ruby code
+* [docs/](docs/) – the docs directory contains additional guides
+
+
+## See also
+
+* [llm-shell](https://github.com/llmrb/llm-shell) – a shell that uses llm.rb to
+  provide a command-line interface to LLMs.
 
 ## Install
 

data/lib/llm/bot.rb

@@ -3,33 +3,26 @@
 module LLM
   ##
   # {LLM::Bot LLM::Bot} provides an object that can maintain a
-  # a conversation. A conversation can use the chat completions API
+  # conversation. A conversation can use the chat completions API
   # that all LLM providers support or the responses API that currently
   # only OpenAI supports.
   #
-  # @example example #1
+  # @example
   #   #!/usr/bin/env ruby
   #   require "llm"
   #
-  #   llm  = LLM.openai(ENV["KEY"])
+  #   llm  = LLM.openai(key: ENV["KEY"])
   #   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.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 ?"
+  #     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("freebsd_book.pdf", "rb")]
+  #     prompt.user "Is the URL and PDF similar to each other?"
   #   end
-  #   msgs.each { print "[#{_1.role}]", _1.content, "\n" }
   #
-  # @example example #2
-  #   #!/usr/bin/env ruby
-  #   require "llm"
-  #
-  #   llm = LLM.openai(ENV["KEY"])
-  #   bot = LLM::Bot.new(llm)
-  #   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" }
+  #   # At this point, we execute a single request
+  #   msgs.each { print "[#{_1.role}] ", _1.content, "\n" }
   class Bot
     require_relative "bot/prompt/completion"
     require_relative "bot/prompt/respond"

data/lib/llm/buffer.rb

@@ -47,6 +47,13 @@ module LLM
       reverse_each.find(...)
     end
 
+    ##
+    # Returns the last message in the buffer
+    # @return [LLM::Message, nil]
+    def last
+      to_a[-1]
+    end
+
     ##
     # @param [[LLM::Message, Hash]] item
     #  A message and its parameters

data/lib/llm/file.rb

@@ -1,9 +1,10 @@
 # frozen_string_literal: true
 
 ##
-# The {LLM::File LLM::File} class represents a local file. It can
-# be used as a prompt with certain providers (eg: Ollama, Gemini),
-# and as an input with certain methods
+# {LLM::File LLM::File} represents a local file. It can be used
+# as a prompt with certain providers (eg: Ollama, Gemini),
+# and as an input with certain methods. It is usually not necessary
+# to create an instance of LLM::File directly.
 class LLM::File
   ##
   # @return [String]

data/lib/llm/function.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 ##
-# The {LLM::Function LLM::Function} class represents a
-# local function that can be called by an LLM.
+# The {LLM::Function LLM::Function} class represents a local
+# function that can be called by an LLM.
 #
 # @example example #1
 #   LLM.function(:system) do |fn|

data/lib/llm/multipart.rb

@@ -4,7 +4,6 @@
 ##
 # @private
 class LLM::Multipart
-  require "llm"
   require "securerandom"
 
   ##

data/lib/llm/object.rb

@@ -1,10 +1,9 @@
 # frozen_string_literal: true
 
 ##
-# The {LLM::Object LLM::Object} class encapsulates a Hash object, and it
-# allows a consumer to get and set Hash keys via regular methods. It is
+# The {LLM::Object LLM::Object} class encapsulates a Hash object. It is
 # similar in spirit to OpenStruct, and it was introduced after OpenStruct
-# became a bundled gem (and not a default gem) in Ruby 3.5.
+# became a bundled gem rather than a default gem in Ruby 3.5.
 class LLM::Object < BasicObject
   require_relative "object/builder"
   require_relative "object/kernel"

data/lib/llm/provider.rb

@@ -52,7 +52,7 @@ class LLM::Provider
   ##
   # Provides an interface to the chat completions API
   # @example
-  #   llm = LLM.openai(ENV["KEY"])
+  #   llm = LLM.openai(key: ENV["KEY"])
   #   messages = [{role: "system", content: "Your task is to answer all of my questions"}]
   #   res = llm.complete("5 + 2 ?", messages:)
   #   print "[#{res.choices[0].role}]", res.choices[0].content, "\n"

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

@@ -11,7 +11,7 @@ class LLM::Anthropic
   #   #!/usr/bin/env ruby
   #   require "llm"
   #
-  #   llm = LLM.anthropic(ENV["KEY"])
+  #   llm = LLM.anthropic(key: ENV["KEY"])
   #   res = llm.models.all
   #   res.each do |model|
   #     print "id: ", model.id, "\n"
@@ -28,7 +28,7 @@ class LLM::Anthropic
     ##
     # List all models
     # @example
-    #   llm = LLM.anthropic(ENV["KEY"])
+    #   llm = LLM.anthropic(key: ENV["KEY"])
     #   res = llm.models.all
     #   res.each do |model|
     #     print "id: ", model.id, "\n"

data/lib/llm/providers/anthropic.rb

@@ -3,7 +3,16 @@
 module LLM
   ##
   # The Anthropic class implements a provider for
-  # [Anthropic](https://www.anthropic.com)
+  # [Anthropic](https://www.anthropic.com).
+  #
+  # @example
+  #   #!/usr/bin/env ruby
+  #   require "llm"
+  #
+  #   llm = LLM.anthropic(key: ENV["KEY"])
+  #   bot = LLM::Bot.new(llm)
+  #   bot.chat ["Tell me about this photo", File.open("/images/dog.jpg", "rb")]
+  #   bot.messages.select(&:assistant?).each { print "[#{_1.role}]", _1.content, "\n" }
   class Anthropic < Provider
     require_relative "anthropic/response/completion"
     require_relative "anthropic/format"

data/lib/llm/providers/deepseek.rb

@@ -6,8 +6,17 @@ module LLM
   ##
   # The DeepSeek class implements a provider for
   # [DeepSeek](https://deepseek.com)
-  # through its OpenAI-compatible API provided via
+  # through its OpenAI-compatible API available via
   # their [web platform](https://platform.deepseek.com).
+  #
+  # @example
+  #   #!/usr/bin/env ruby
+  #   require "llm"
+  #
+  #   llm = LLM.deepseek(key: ENV["KEY"])
+  #   bot = LLM::Bot.new(llm)
+  #   bot.chat ["Tell me about this photo", File.open("/images/cat.jpg", "rb")]
+  #   bot.messages.select(&:assistant?).each { print "[#{_1.role}]", _1.content, "\n" }
   class DeepSeek < OpenAI
     require_relative "deepseek/format"
     include DeepSeek::Format

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

@@ -8,7 +8,7 @@ class LLM::Gemini
   #   #!/usr/bin/env ruby
   #   require "llm"
   #
-  #   llm = LLM.gemini(ENV["KEY"])
+  #   llm = LLM.gemini(key: ENV["KEY"])
   #   res = llm.audio.create_transcription(input: "/audio/rocket.mp3")
   #   res.text # => "A dog on a rocket to the moon"
   class Audio
@@ -30,7 +30,7 @@ class LLM::Gemini
     ##
     # Create an audio transcription
     # @example
-    #   llm = LLM.gemini(ENV["KEY"])
+    #   llm = LLM.gemini(key: ENV["KEY"])
     #   res = llm.audio.create_transcription(file: "/audio/rocket.mp3")
     #   res.text # => "A dog on a rocket to the moon"
     # @see https://ai.google.dev/gemini-api/docs/audio Gemini docs
@@ -52,7 +52,7 @@ class LLM::Gemini
     # Create an audio translation (in English)
     # @example
     #   # Arabic => English
-    #   llm = LLM.gemini(ENV["KEY"])
+    #   llm = LLM.gemini(key: ENV["KEY"])
     #   res = llm.audio.create_translation(file: "/audio/bismillah.mp3")
     #   res.text # => "In the name of Allah, the Beneficent, the Merciful."
     # @see https://ai.google.dev/gemini-api/docs/audio Gemini docs

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

@@ -17,22 +17,10 @@ class LLM::Gemini
   #   #!/usr/bin/env ruby
   #   require "llm"
   #
-  #   llm = LLM.gemini(ENV["KEY"])
+  #   llm = LLM.gemini(key: ENV["KEY"])
   #   bot = LLM::Bot.new(llm)
-  #   file = llm.files.create file: "/audio/haiku.mp3"
-  #   bot.chat(file)
-  #   bot.chat("Describe the audio file I sent to you")
-  #   bot.chat("The audio file is the first message I sent to you.")
-  #   bot.messages.select(&:assistant?).each { print "[#{_1.role}]", _1.content, "\n" }
-  #
-  # @example example #2
-  #   #!/usr/bin/env ruby
-  #   require "llm"
-  #
-  #   llm = LLM.gemini(ENV["KEY"])
-  #   bot = LLM::Bot.new(llm)
-  #   file = llm.files.create file: "/audio/haiku.mp3"
-  #   bot.chat(["Describe the audio file I sent to you", file])
+  #   file = llm.files.create(file: "/audio/haiku.mp3")
+  #   bot.chat ["Tell me about this file", file]
   #   bot.messages.select(&:assistant?).each { print "[#{_1.role}]", _1.content, "\n" }
   class Files
     require_relative "response/file"
@@ -48,7 +36,7 @@ class LLM::Gemini
     ##
     # List all files
     # @example
-    #   llm = LLM.gemini(ENV["KEY"])
+    #   llm = LLM.gemini(key: ENV["KEY"])
     #   res = llm.files.all
     #   res.each do |file|
     #     print "name: ", file.name, "\n"
@@ -67,8 +55,8 @@ class LLM::Gemini
     ##
     # Create a file
     # @example
-    #   llm = LLM.gemini(ENV["KEY"])
-    #   res = llm.files.create file: "/audio/haiku.mp3"
+    #   llm = LLM.gemini(key: ENV["KEY"])
+    #   res = llm.files.create(file: "/audio/haiku.mp3")
     # @see https://ai.google.dev/gemini-api/docs/files Gemini docs
     # @param [String, LLM::File] file The file
     # @param [Hash] params Other parameters (see Gemini docs)
@@ -90,7 +78,7 @@ class LLM::Gemini
     ##
     # Get a file
     # @example
-    #   llm = LLM.gemini(ENV["KEY"])
+    #   llm = LLM.gemini(key: ENV["KEY"])
     #   res = llm.files.get(file: "files/1234567890")
     #   print "name: ", res.name, "\n"
     # @see https://ai.google.dev/gemini-api/docs/files Gemini docs
@@ -109,7 +97,7 @@ class LLM::Gemini
     ##
     # Delete a file
     # @example
-    #   llm = LLM.gemini(ENV["KEY"])
+    #   llm = LLM.gemini(key: ENV["KEY"])
     #   res = llm.files.delete(file: "files/1234567890")
     # @see https://ai.google.dev/gemini-api/docs/files Gemini docs
     # @param [#name, String] file The file to delete

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

@@ -59,8 +59,8 @@ module LLM::Gemini::Format
     end
 
     def prompt_error!(object)
-        raise LLM::PromptError, "The given object (an instance of #{object.class}) " \
-                                "is not supported by the Gemini API"
+      raise LLM::PromptError, "The given object (an instance of #{object.class}) " \
+                              "is not supported by the Gemini API"
     end
 
     def message = @message

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

@@ -11,7 +11,7 @@ class LLM::Gemini
   #   #!/usr/bin/env ruby
   #   require "llm"
   #
-  #   llm = LLM.gemini(ENV["KEY"])
+  #   llm = LLM.gemini(key: ENV["KEY"])
   #   res = llm.images.create prompt: "A dog on a rocket to the moon"
   #   IO.copy_stream res.images[0], "rocket.png"
   class Images
@@ -29,7 +29,7 @@ class LLM::Gemini
     ##
     # Create an image
     # @example
-    #   llm = LLM.gemini(ENV["KEY"])
+    #   llm = LLM.gemini(key: ENV["KEY"])
     #   res = llm.images.create prompt: "A dog on a rocket to the moon"
     #   IO.copy_stream res.images[0], "rocket.png"
     # @see https://ai.google.dev/gemini-api/docs/image-generation Gemini docs
@@ -55,8 +55,8 @@ class LLM::Gemini
     ##
     # Edit an image
     # @example
-    #   llm = LLM.gemini(ENV["KEY"])
-    #   res = llm.images.edit image: LLM::File("cat.png"), prompt: "Add a hat to the cat"
+    #   llm = LLM.gemini(key: ENV["KEY"])
+    #   res = llm.images.edit image: "cat.png", prompt: "Add a hat to the cat"
     #   IO.copy_stream res.images[0], "hatoncat.png"
     # @see https://ai.google.dev/gemini-api/docs/image-generation Gemini docs
     # @param [String, LLM::File] image The image to edit

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

@@ -11,7 +11,7 @@ class LLM::Gemini
   #   #!/usr/bin/env ruby
   #   require "llm"
   #
-  #   llm = LLM.gemini(ENV["KEY"])
+  #   llm = LLM.gemini(key: ENV["KEY"])
   #   res = llm.models.all
   #   res.each do |model|
   #     print "id: ", model.id, "\n"
@@ -30,7 +30,7 @@ class LLM::Gemini
     ##
     # List all models
     # @example
-    #   llm = LLM.gemini(ENV["KEY"])
+    #   llm = LLM.gemini(key: ENV["KEY"])
     #   res = llm.models.all
     #   res.each do |model|
     #     print "id: ", model.id, "\n"

data/lib/llm/providers/gemini/response/embedding.rb

@@ -5,4 +5,4 @@ module LLM::Gemini::Response
     def model = "text-embedding-004"
     def embeddings = body.dig("embedding", "values")
   end
-end
+end