llm.rb 0.4.2 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2ae98573410bfc74a61f0bf15f811c30800b6567c9e5fc9e4cbe50f4994a200f
-  data.tar.gz: 9776839912017f5f3bac8452670c60b3bc9eabecebe11c402458a36b78d958e7
+  metadata.gz: 50bc0de3950bfbc8dd1a9ff3b211915fff5ae510f6fd0f0fc277e5cbf689e5ea
+  data.tar.gz: 3e48e23abefeb652429cb145be5fa1166e78cb24f3ddfb7440daff2e4a461c5d
 SHA512:
-  metadata.gz: 4252d2d861d409428067415340c2d36f2e75f34f3be9905a576a63455902d1faf4100d8c8c7060e683fe922ff095cc00fd56fd135b9589a746d9de716c66e5e5
-  data.tar.gz: 819676961e401aa5e27678e3d36af406362f0a68b0243e1e1f71f5f135286830dd1c009c47c69c26b6789a771da6a1fe72eb023f0f1833c20ffadac37f58ed1b
+  metadata.gz: 8b6ad1955541753ba991a0f9b55e261cb4cc32a3a85470cee7312359cafce7d4689757a2f5efe2f641c9813dca5b7722b47ff8dc12d90f8a600eff1e3c7b5b4d
+  data.tar.gz: b807543c44e12d4a251370a84cda59714a9b62cf3bf031203d723a8740167aab5a4f9348ae29856b6324384f2042d1851c05c272ba3a6510b33d99d6fddf4fdc

data/README.md

@@ -1,11 +1,31 @@
 ## About
 
-llm.rb is a lightweight library that provides a common interface
-and set of functionality for multiple Large Language Models (LLMs). It
-is designed to be simple, flexible, and easy to use – and it has been
-implemented with zero dependencies outside Ruby's standard library. See the
-[philosophy](#philosophy) section for more information on the design principles
-behind llm.rb.
+llm.rb is a zero-dependency Ruby toolkit for Large Language Models like
+OpenAI, Gemini, Anthropic, and more. It’s fast, clean, and composable –
+with full support for chat, tool calling, audio, images, files, and
+JSON Schema generation.
+
+## Features
+
+#### General
+- ✅ Unified interface for OpenAI, Gemini, Anthropic, Ollama, and more
+- 📦 Zero dependencies outside Ruby's standard library
+- 🔌 Model introspection and selection
+- 🚀 Optimized for performance and low memory usage
+
+#### Chat, Agents
+- 🧠 Stateless and stateful chat via completions and responses API
+- 🤖 Tool calling and function execution
+- 🗂️ JSON Schema support for structured, validated responses
+
+#### Media
+- 🗣️ Text-to-speech, transcription, and translation
+- 🖼️ Image generation, editing, and variation support
+- 📎 File uploads and prompt-aware file interaction
+- 💡 Multimodal prompts (text, URLs, files)
+
+#### Embeddings
+- 🧮 Text embeddings and vector support
 
 ## Examples
 
@@ -150,6 +170,56 @@ bot.chat "Does the earth orbit the sun?", :user
 bot.messages.find(&:assistant?).content! # => {probability: 1}
 ```
 
+### Tools
+
+#### Functions
+
+The OpenAI, Anthropic, Gemini and Ollama providers support a powerful feature known as
+tool calling, and although it is a little complex to understand at first,
+it can be powerful for building agents. The following example demonstrates how we
+can define a local function (which happens to be a tool), and OpenAI can
+then detect when we should call the function.
+
+The
+[LLM::Chat#functions](https://0x1eef.github.io/x/llm.rb/LLM/Chat.html#functions-instance_method)
+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:
+
+```ruby
+#!/usr/bin/env ruby
+require "llm"
+
+llm = LLM.openai(ENV["KEY"])
+tool = LLM.function(:system) do |fn|
+  fn.description "Run a shell command"
+  fn.params do |schema|
+    schema.object(command: schema.string.required)
+  end
+  fn.define do |params|
+    system(params.command)
+  end
+end
+
+bot = LLM::Chat.new(llm, tools: [tool]).lazy
+bot.chat "Your task is to run shell commands via a tool.", :system
+
+bot.chat "What is the current date?", :user
+bot.chat bot.functions.map(&:call) # report return value to the LLM
+
+bot.chat "What operating system am I running? (short version please!)", :user
+bot.chat bot.functions.map(&:call) # report return value to the LLM
+
+##
+# Thu May  1 10:01:02 UTC 2025
+# FreeBSD
+```
+
 ### Audio
 
 #### Speech
@@ -159,8 +229,7 @@ can create speech from text, transcribe audio to text, or translate
 audio to text (usually English). The following example uses the OpenAI provider
 to create an audio file from a text prompt. The audio is then moved to
 `${HOME}/hello.mp3` as the final step. As always, consult the provider's
-documentation (eg [OpenAI docs](https://platform.openai.com/docs/api-reference/audio/create))
-for more information on how to use the audio generation API:
+documentation for more information on how to use the audio generation API:
 
 ```ruby
 #!/usr/bin/env ruby
@@ -177,16 +246,7 @@ The following example transcribes an audio file to text. The audio file
 (`${HOME}/hello.mp3`) was theoretically created in the previous example,
 and the result is printed to the console. The example uses the OpenAI
 provider to transcribe the audio file. As always, consult the provider's
-documentation (eg
-[OpenAI docs](https://platform.openai.com/docs/api-reference/audio/createTranscription),
-[Gemini docs](https://ai.google.dev/gemini-api/docs/audio))
-for more information on how to use the audio transcription API.
-
-Please also see provider-specific documentation for more provider-specific
-examples and documentation
-(eg
-[LLM::Gemini::Audio](https://0x1eef.github.io/x/llm.rb/LLM/Gemini/Audio.html),
-[LLM::OpenAI::Audio](https://0x1eef.github.io/x/llm.rb/LLM/OpenAI/Audio.html)):
+documentation for more information on how to use the audio transcription API:
 
 ```ruby
 #!/usr/bin/env ruby
@@ -194,7 +254,7 @@ require "llm"
 
 llm = LLM.openai(ENV["KEY"])
 res = llm.audio.create_transcription(
-  file: LLM::File(File.join(Dir.home, "hello.mp3"))
+  file: File.join(Dir.home, "hello.mp3")
 )
 print res.text, "\n" # => "Hello world."
 ```
@@ -205,17 +265,8 @@ The following example translates an audio file to text. In this example
 the audio file (`${HOME}/bomdia.mp3`) is theoretically in Portuguese,
 and it is translated to English. The example uses the OpenAI provider,
 and at the time of writing, it can only translate to English. As always,
-consult the provider's documentation (eg
-[OpenAI docs](https://platform.openai.com/docs/api-reference/audio/createTranslation),
-[Gemini docs](https://ai.google.dev/gemini-api/docs/audio))
-for more information on how to use the audio translation API.
-
-Please also see provider-specific documentation for more provider-specific
-examples and documentation
-(eg
-[LLM::Gemini::Audio](https://0x1eef.github.io/x/llm.rb/LLM/Gemini/Audio.html),
-[LLM::OpenAI::Audio](https://0x1eef.github.io/x/llm.rb/LLM/OpenAI/Audio.html)):
-
+consult the provider's documentation for more information on how to use
+the audio translation API:
 
 ```ruby
 #!/usr/bin/env ruby
@@ -223,7 +274,7 @@ require "llm"
 
 llm = LLM.openai(ENV["KEY"])
 res = llm.audio.create_translation(
-  file: LLM::File(File.join(Dir.home, "bomdia.mp3"))
+  file: File.join(Dir.home, "bomdia.mp3")
 )
 print res.text, "\n" # => "Good morning."
 ```
@@ -236,13 +287,7 @@ Some but not all LLM providers implement image generation capabilities that
 can create new images from a prompt, or edit an existing image with a
 prompt. The following example uses the OpenAI provider to create an
 image of a dog on a rocket to the moon. The image is then moved to
-`${HOME}/dogonrocket.png` as the final step.
-
-Please also see provider-specific documentation for more provider-specific
-examples and documentation
-(eg
-[LLM::Gemini::Images](https://0x1eef.github.io/x/llm.rb/LLM/Gemini/Images.html),
-[LLM::OpenAI::Images](https://0x1eef.github.io/x/llm.rb/LLM/OpenAI/Images.html)):
+`${HOME}/dogonrocket.png` as the final step:
 
 ```ruby
 #!/usr/bin/env ruby
@@ -266,17 +311,8 @@ now wearing a hat. The image is then moved to `${HOME}/catwithhat.png` as
 the final step.
 
 Results and quality may vary, consider prompt adjustments if the results
-are not satisfactory, and consult the provider's documentation
-(eg
-[OpenAI docs](https://platform.openai.com/docs/api-reference/images/createEdit),
-[Gemini docs](https://ai.google.dev/gemini-api/docs/image-generation))
-for more information on how to use the image editing API.
-
-Please also see provider-specific documentation for more provider-specific
-examples and documentation
-(eg
-[LLM::Gemini::Images](https://0x1eef.github.io/x/llm.rb/LLM/Gemini/Images.html),
-[LLM::OpenAI::Images](https://0x1eef.github.io/x/llm.rb/LLM/OpenAI/Images.html)):
+are not as expected, and consult the provider's documentation
+for more information on how to use the image editing API:
 
 ```ruby
 #!/usr/bin/env ruby
@@ -286,7 +322,7 @@ require "fileutils"
 
 llm = LLM.openai(ENV["KEY"])
 res = llm.images.edit(
-  image: LLM::File("/images/cat.png"),
+  image: "/images/cat.png",
   prompt: "a cat with a hat",
 )
 res.urls.each do |url|
@@ -300,9 +336,8 @@ end
 The following example is focused on creating variations of a local image.
 The image (`/images/cat.png`) is returned to us with five different variations.
 The images are then moved to `${HOME}/catvariation0.png`, `${HOME}/catvariation1.png`
-and so on as the final step. Consult the provider's documentation
-(eg [OpenAI docs](https://platform.openai.com/docs/api-reference/images/createVariation))
-for more information on how to use the image variations API:
+and so on as the final step. Consult the provider's documentation for more information
+on how to use the image variations API:
 
 ```ruby
 #!/usr/bin/env ruby
@@ -312,7 +347,7 @@ require "fileutils"
 
 llm = LLM.openai(ENV["KEY"])
 res = llm.images.create_variation(
-  image: LLM::File("/images/cat.png"),
+  image: "/images/cat.png",
   n: 5
 )
 res.urls.each.with_index do |url, index|
@@ -331,13 +366,8 @@ 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.
+can be given to the chat method:
 
-Please also see provider-specific documentation for more provider-specific
-examples and documentation
-(eg
-[LLM::Gemini::Files](https://0x1eef.github.io/x/llm.rb/LLM/Gemini/Files.html),
-[LLM::OpenAI::Files](https://0x1eef.github.io/x/llm.rb/LLM/OpenAI/Files.html)):
 
 ```ruby
 #!/usr/bin/env ruby
@@ -345,7 +375,7 @@ require "llm"
 
 llm = LLM.openai(ENV["KEY"])
 bot = LLM::Chat.new(llm).lazy
-file = llm.files.create(file: LLM::File("/documents/openbsd_is_awesome.pdf"))
+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" }
@@ -368,11 +398,7 @@ 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.
-
-For more depth and examples on how to use the multimodal API, please see
-the [provider-specific documentation](https://0x1eef.github.io/x/llm.rb/)
-for more provider-specific examples:
+to a prompt:
 
 ```ruby
 #!/usr/bin/env ruby
@@ -381,19 +407,17 @@ require "llm"
 llm = LLM.openai(ENV["KEY"])
 bot = LLM::Chat.new(llm).lazy
 
-bot.chat URI("https://example.com/path/to/image.png")
-bot.chat "Describe the above image"
+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 = bot.files.create(file: LLM::File("/documents/openbsd_is_awesome.pdf"))
-bot.chat file
-bot.chat "What is this file about?"
+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.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.chat [LLM.File("/images/beastie.png"), "What is this image about?"]
 bot.messages.select(&:assistant?).each { print "[#{_1.role}] ", _1.content, "\n" }
 ```
 
@@ -495,6 +519,26 @@ over or doesn't cover at all. The API reference is available at
 [0x1eef.github.io/x/llm.rb](https://0x1eef.github.io/x/llm.rb).
 
 
+### See also
+
+#### Gemini
+
+* [LLM::Gemini](https://0x1eef.github.io/x/llm.rb/LLM/Gemini.html)
+* [LLM::Gemini::Images](https://0x1eef.github.io/x/llm.rb/LLM/Gemini/Images.html)
+* [LLM::Gemini::Audio](https://0x1eef.github.io/x/llm.rb/LLM/Gemini/Audio.html)
+
+#### OpenAI
+
+* [LLM::OpenAI](https://0x1eef.github.io/x/llm.rb/LLM/OpenAI.html)
+* [LLM::OpenAI::Images](https://0x1eef.github.io/x/llm.rb/LLM/OpenAI/Images.html)
+* [LLM::OpenAI::Audio](https://0x1eef.github.io/x/llm.rb/LLM/OpenAI/Audio.html)
+
+#### Anthropic
+* [LLM::Anthropic](https://0x1eef.github.io/x/llm.rb/LLM/Anthropic.html)
+
+#### Ollama
+* [LLM::Ollama](https://0x1eef.github.io/x/llm.rb/LLM/Ollama.html)
+
 ## Install
 
 llm.rb can be installed via rubygems.org:
@@ -503,17 +547,21 @@ llm.rb can be installed via rubygems.org:
 
 ## Philosophy
 
-llm.rb was built for developers who believe that simplicity can be challenging
-but it is always worth it. It provides a clean, dependency-free interface to
-Large Language Models, treating Ruby itself as the primary platform –
-not Rails or any other specific framework or library. There is no hidden
-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, 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.
+llm.rb provides a clean, dependency-free interface to Large Language Models,
+treating Ruby itself — not Rails or any specific framework — as the primary platform.
+It avoids hidden magic, complex metaprogramming, and heavy DSLs. It is intentionally
+simple and won't compromise on being a simple library, even if that means saying no to
+certain features.
+
+Instead, it embraces a general-purpose, object-oriented design that prioritizes
+explicitness, composability, and clarity. Code should be easy to follow, test, and adapt.
+For that reason we favor small, cooperating objects over deeply nested blocks — a pattern
+that often emerges in DSL-heavy libraries.
+
+Each part of llm.rb is designed to be conscious of memory, ready for production, and free
+from global state or non-standard dependencies. While inspired by ideas from other ecosystems
+(especially Python) it is not a port of any other library — it is a Ruby library written
+by Rubyists who value borrowing good ideas from other languages and ecosystems.
 
 ## License
 

data/lib/json/schema/array.rb

@@ -1,6 +1,11 @@
 # frozen_string_literal: true
 
 class JSON::Schema
+  ##
+  # The {JSON::Schema::Array JSON::Schema::Array} class represents an
+  # array value in a JSON schema. It is a subclass of
+  # {JSON::Schema::Leaf JSON::Schema::Leaf} and provides methods that
+  # can act as constraints.
   class Array < Leaf
     def initialize(*items)
       @items = items

data/lib/json/schema/boolean.rb

@@ -1,6 +1,10 @@
 # frozen_string_literal: true
 
 class JSON::Schema
+  ##
+  # The {JSON::Schema::Boolean JSON::Schema::Boolean} class represents a
+  # boolean value in a JSON schema. It is a subclass of
+  # {JSON::Schema::Leaf JSON::Schema::Leaf}.
   class Booelean < Leaf
     def to_h
       super.merge!({type: "boolean"})

data/lib/json/schema/integer.rb

@@ -1,20 +1,42 @@
 # frozen_string_literal: true
 
 class JSON::Schema
+  ##
+  # The {JSON::Schema::Integer JSON::Schema::Integer} class represents a
+  # whole number value in a JSON schema. It is a subclass of
+  # {JSON::Schema::Leaf JSON::Schema::Leaf} and provides methods that
+  # can act as constraints.
   class Integer < Leaf
+    ##
+    # Constrain the number to a minimum value
+    # @param [Integer] i The minimum value
+    # @return [JSON::Schema::Number] Returns self
     def min(i)
       tap { @minimum = i }
     end
 
+    ##
+    # Constrain the number to a maximum value
+    # @param [Integer] i The maximum value
+    # @return [JSON::Schema::Number] Returns self
     def max(i)
       tap { @maximum = i }
     end
 
+    ##
+    # Constrain the number to a multiple of a given value
+    # @param [Integer] i The multiple
+    # @return [JSON::Schema::Number] Returns self
+    def multiple_of(i)
+      tap { @multiple_of = i }
+    end
+
     def to_h
       super.merge!({
         type: "integer",
         minimum: @minimum,
-        maximum: @maximum
+        maximum: @maximum,
+        multipleOf: @multiple_of
       }).compact
     end
   end

data/lib/json/schema/leaf.rb

@@ -13,6 +13,7 @@ class JSON::Schema
       @default = nil
       @enum = nil
       @required = nil
+      @const = nil
     end
 
     ##
@@ -33,12 +34,22 @@ class JSON::Schema
 
     ##
     # Set the allowed values of a leaf
+    # @see https://tour.json-schema.org/content/02-Primitive-Types/07-Enumerated-Values-II Enumerated Values
     # @param [Array] values The allowed values
     # @return [JSON::Schema::Leaf]
     def enum(*values)
       tap { @enum = values }
     end
 
+    ##
+    # Set the value of a leaf to be a constant value
+    # @see https://tour.json-schema.org/content/02-Primitive-Types/08-Defining-Constant-Values Constant Values
+    # @param [Object] value The constant value
+    # @return [JSON::Schema::Leaf]
+    def const(value)
+      tap { @const = value }
+    end
+
     ##
     # Denote a leaf as required
     # @return [JSON::Schema::Leaf]

data/lib/json/schema/null.rb

@@ -1,6 +1,10 @@
 # frozen_string_literal: true
 
 class JSON::Schema
+  ##
+  # The {JSON::Schema::Null JSON::Schema::Null} class represents a
+  # null value in a JSON schema. It is a subclass of
+  # {JSON::Schema::Leaf JSON::Schema::Leaf}.
   class Null < Leaf
     def to_h
       super.merge!({type: "null"})

data/lib/json/schema/number.rb

@@ -1,20 +1,42 @@
 # frozen_string_literal: true
 
 class JSON::Schema
+  ##
+  # The {JSON::Schema::Number JSON::Schema::Number} class represents a
+  # a number (either whole or decimal) value in a JSON schema. It is a
+  # subclass of {JSON::Schema::Leaf JSON::Schema::Leaf} and provides
+  # methods that can act as constraints.
   class Number < Leaf
+    ##
+    # Constrain the number to a minimum value
+    # @param [Integer, Float] i The minimum value
+    # @return [JSON::Schema::Number] Returns self
     def min(i)
       tap { @minimum = i }
     end
 
+    ##
+    # Constrain the number to a maximum value
+    # @param [Integer, Float] i The maximum value
+    # @return [JSON::Schema::Number] Returns self
     def max(i)
       tap { @maximum = i }
     end
 
+    ##
+    # Constrain the number to a multiple of a given value
+    # @param [Integer, Float] i The multiple
+    # @return [JSON::Schema::Number] Returns self
+    def multiple_of(i)
+      tap { @multiple_of = i }
+    end
+
     def to_h
       super.merge!({
         type: "number",
         minimum: @minimum,
-        maximum: @maximum
+        maximum: @maximum,
+        multipleOf: @multiple_of
       }).compact
     end
   end

data/lib/json/schema/object.rb

@@ -1,10 +1,14 @@
 # frozen_string_literal: true
 
 class JSON::Schema
+  ##
+  # The {JSON::Schema::Object JSON::Schema::Object} class represents an
+  # object value in a JSON schema. It is a subclass of
+  # {JSON::Schema::Leaf JSON::Schema::Leaf} and provides methods that
+  # can act as constraints.
   class Object < Leaf
-    def initialize(properties, **rest)
+    def initialize(properties)
       @properties = properties
-      super(**rest)
     end
 
     def to_h

data/lib/json/schema/string.rb

@@ -1,9 +1,34 @@
 # frozen_string_literal: true
 
 class JSON::Schema
+  ##
+  # The {JSON::Schema::String JSON::Schema::String} class represents a
+  # string value in a JSON schema. It is a subclass of
+  # {JSON::Schema::Leaf JSON::Schema::Leaf} and provides methods that
+  # can act as constraints.
   class String < Leaf
+    ##
+    # Constrain the string to a minimum length
+    # @param [Integer] i The minimum length
+    # @return [JSON::Schema::String] Returns self
+    def min(i)
+      tap { @minimum = i }
+    end
+
+    ##
+    # Constrain the string to a maximum length
+    # @param [Integer] i The maximum length
+    # @return [JSON::Schema::String] Returns self
+    def max(i)
+      tap { @maximum = i }
+    end
+
     def to_h
-      super.merge!({type: "string"})
+      super.merge!({
+        type: "string",
+        minLength: @minimum,
+        maxLength: @maximum
+      }).compact
     end
   end
 end

data/lib/json/schema/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module JSON
 end unless defined?(JSON)
 

data/lib/json/schema.rb

@@ -50,35 +50,35 @@ class JSON::Schema
   ##
   # Returns a string
   # @return [JSON::Schema::String]
-  def string(...)
-    String.new(...)
+  def string
+    String.new
   end
 
   ##
   # Returns a number
   # @return [JSON::Schema::Number] a number
-  def number(...)
-    Number.new(...)
+  def number
+    Number.new
   end
 
   ##
   # Returns an integer
   # @return [JSON::Schema::Integer]
-  def integer(...)
-    Integer.new(...)
+  def integer
+    Integer.new
   end
 
   ##
   # Returns a boolean
   # @return [JSON::Schema::Boolean]
-  def boolean(...)
-    Boolean.new(...)
+  def boolean
+    Boolean.new
   end
 
   ##
   # Returns null
   # @return [JSON::Schema::Null]
-  def null(...)
-    Null.new(...)
+  def null
+    Null.new
   end
 end