llm.rb 2.0.1 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 25cfa0f4004670cb739599150aa68cc74123a8d835b4a72a91c80b7e98640a6a
-  data.tar.gz: 1a8e7547baa911c8d03c84f7e4f849f7bd36f574aa709732e0397b033addd617
+  metadata.gz: 8578f727c5a45b243d86f498cf1a3fcc594981f4056234d2376805744b7e7633
+  data.tar.gz: 03aefaa4ebdf15200e0d6999a8b7015e101dcc0d9afff4c205672a6fa94532c4
 SHA512:
-  metadata.gz: aad8b1f2cd63ecb95875cd30e09a2dc514bd332b676653825f08ecc776fffcebe16d47a0a4252dad91dfbb4f27a62bbd75b033b04383591edc87788a15551817
-  data.tar.gz: f894b483b8700ed334e0d499baa0d2f5b3b5fb331356267210de8d0111fd6281c1ae4ed139edb7947d578587567e2d4d9f181352b9bf4a6fc149ed91562ec57f
+  metadata.gz: 1b969f525f44192999bcb3ea45aec1e53283d6bb4347b6852bc0bfe9095ecf4d9a9d21a42f7b04e6c530329bf96deb0fa0508757b9e0c185b8944d1630da1648
+  data.tar.gz: 239ff739c3f9bfdfbe8f574a1045acac9ace3bbb0ddca3a92958fee9319e4834c2f057a61c9b0c418979111050ade4968a01ec73862f70278b75cbe7752c9815

data/README.md

@@ -9,8 +9,7 @@ tool calling, audio, images, files, and structured outputs.
 
 #### REPL
 
-A simple chatbot that maintains a conversation and streams
-responses in real-time:
+A simple chatbot that maintains a conversation and streams responses in real-time:
 
 ```ruby
 #!/usr/bin/env ruby
@@ -20,14 +19,14 @@ llm = LLM.openai(key: ENV["KEY"])
 bot = LLM::Bot.new(llm, stream: $stdout)
 loop do
   print "> "
-  bot.chat($stdin.gets)
+  bot.chat(gets)
   print "\n"
 end
 ```
 
-#### Build
+#### Prompts
 
-We can send multiple messages at once by building a chain of messages:
+A prompt builder that produces a chain of messages that can be sent in one request:
 
 ```ruby
 #!/usr/bin/env ruby
@@ -37,37 +36,65 @@ llm = LLM.openai(key: ENV["KEY"])
 bot = LLM::Bot.new(llm)
 prompt = bot.build_prompt do
   it.system "Your task is to answer all user queries"
-  it.user "What language should I learn next ?"
+  it.user "Was 2024 a leap year?"
+  it.user "How many days in a year?"
 end
-
 bot.chat(prompt)
 bot.messages.each { print "[#{it.role}] ", it.content, "\n" }
 ```
 
-#### Images
+#### Schema
 
-We can generate an image on the fly and estimate how old the person
-in the image is:
+A bot that instructs the LLM to respond in JSON, and according to the given schema:
 
 ```ruby
 #!/usr/bin/env ruby
 require "llm"
 
-llm = LLM.openai(key: ENV["OPENAI_SECRET"])
-schema = llm.schema.object(
-  age: llm.schema.integer.required.description("The age of the person in a photo"),
-  confidence: llm.schema.number.required.description("Model confidence (0.0 to 1.0)"),
-  notes: llm.schema.string.required.description("Model notes or caveats")
-)
+class Estimation < LLM::Schema
+  property :age, Integer, "The age of a person in a photo", required: true
+  property :confidence, Number, "Model confidence (0.0 to 1.0)", required: true
+  property :notes, String, "Model notes or caveats", optional: true
+end
 
+llm = LLM.openai(key: ENV["KEY"])
+bot = LLM::Bot.new(llm, schema: Estimation)
 img = llm.images.create(prompt: "A man in his 30s")
-bot = LLM::Bot.new(llm, schema:)
 res = bot.chat bot.image_url(img.urls[0])
-body = res.choices.find(&:assistant?).content!
+estimation = res.choices.find(&:assistant?).content!
+
+puts "age: #{estimation["age"]}"
+puts "confidence: #{estimation["confidence"]}"
+puts "notes: #{estimation["notes"]}"
+```
+
+#### Tools
+
+A bot equipped with a tool that is capable of running system commands:
+
+```ruby
+#!/usr/bin/env ruby
+require "llm"
+
+class System < LLM::Tool
+  name "system"
+  description "Run a shell command"
+  param :command, String, "The command to execute", required: true
+
+  def call(command:)
+    {success: system(command)}
+  end
+end
 
-print "age: ", body["age"], "\n"
-print "confidence: ", body["confidence"], "\n"
-print "notes: ", body["notes"], "\n"
+llm  = LLM.openai(key: ENV["KEY"])
+bot  = LLM::Bot.new(llm, tools: [System])
+prompt = bot.build_prompt do
+  it.system "Your task is to execute system commands"
+  it.user "mkdir /home/robert/projects"
+end
+bot.chat(prompt)
+bot.chat bot.functions.map(&:call)
+bot.messages.select(&:assistant?).each { print "[#{it.role}] ", it.content, "\n" }
 ```
 
 ## Features
@@ -210,7 +237,6 @@ prompt = bot.build_prompt do
   it.user ["Tell me about this URL", bot.image_url(url)]
   it.user ["Tell me about this PDF", bot.local_file("handbook.pdf")]
 end
-
 bot.chat(prompt)
 bot.messages.each { print "[#{it.role}] ", it.content, "\n" }
 ```
@@ -237,18 +263,18 @@ prompt = bot.build_prompt do
   it.user ["Tell me about this URL", bot.image_url(url)]
   it.user ["Tell me about the PDF", bot.local_file("handbook.pdf")]
 end
-
 bot.chat(prompt)
 ```
 
 ### Schema
 
-#### Structured
+#### Object
 
 All LLM providers except Anthropic and DeepSeek allow a client to describe
 the structure of a response that a LLM emits according to a schema that is
-described by JSON. The schema lets a client describe what JSON object (or value)
-an LLM should emit, and the LLM will abide by the schema:
+described by JSON. The schema lets a client describe what JSON object
+an LLM should emit, and the LLM will abide by the schema to the best of
+its ability:
 
 ```ruby
 #!/usr/bin/env ruby
@@ -278,6 +304,34 @@ bot.chat "Tell me the answer to ((5 + 5) / 2) * 2 + 1", role: :user
 puts bot.messages.find(&:assistant?).content! # => {answers: [11]}
 ```
 
+#### Class
+
+Other than the object form we saw in the previous example, a class form
+is also supported. Under the hood, it is implemented with the object form
+and the class form primarily exists to provide structure and organization
+that the object form lacks:
+
+```ruby
+#!/usr/bin/env ruby
+require "llm"
+
+class Player < LLM::Schema
+  property :name, String, "The player's name", required: true
+  property :numbers, Array[Integer], "The player's favorite numbers", required: true
+end
+
+llm = LLM.openai(key: ENV["KEY"])
+bot = LLM::Bot.new(llm, schema: Player)
+prompt = bot.build_prompt do
+  it.system "The user's name is Robert and their favorite numbers are 7 and 12"
+  it.user "Tell me about myself"
+end
+
+player = bot.chat(prompt).content!
+puts "name: #{player.name}"
+puts "numbers: #{player.numbers}"
+```
+
 ### Tools
 
 #### Introduction

data/lib/llm/providers/anthropic/response/enumerable.rb

@@ -3,9 +3,29 @@
 module LLM::Anthropic::Response
   module Enumerable
     include ::Enumerable
+
     def each(&)
       return enum_for(:each) unless block_given?
       data.each { yield(_1) }
     end
+
+    ##
+    # Returns an element, or a slice, or nil
+    # @return [Object, Array<Object>, nil]
+    def [](*pos, **kw)
+      data[*pos, **kw]
+    end
+
+    ##
+    # @return [Boolean]
+    def empty?
+      data.empty?
+    end
+
+    ##
+    # @return [Integer]
+    def size
+      data.size
+    end
   end
 end

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

@@ -24,6 +24,7 @@ class LLM::Gemini
     def format_schema(params)
       return {} unless params and params[:schema]
       schema = params.delete(:schema)
+      schema = schema.respond_to?(:object) ? schema.object : schema
       {generationConfig: {response_mime_type: "application/json", response_schema: schema}}
     end
 

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

@@ -42,7 +42,7 @@ class LLM::Gemini
     #  might unexpectedly receive a purely textual response. This is due to how
     #  Gemini implements image generation under the hood.
     # @return [LLM::Response]
-    def create(prompt:, model: "gemini-2.5-flash-image-preview", **params)
+    def create(prompt:, model: "gemini-2.5-flash-image", **params)
       req  = Net::HTTP::Post.new("/v1beta/models/#{model}:generateContent?key=#{key}", headers)
       body = JSON.dump({
         contents: [{parts: [{text: create_prompt}, {text: prompt}]}],
@@ -67,7 +67,7 @@ class LLM::Gemini
     # @raise [LLM::NoImageError] when no images are returned
     # @note (see LLM::Gemini::Images#create)
     # @return [LLM::Response]
-    def edit(image:, prompt:, model: "gemini-2.5-flash-image-preview", **params)
+    def edit(image:, prompt:, model: "gemini-2.5-flash-image", **params)
       req   = Net::HTTP::Post.new("/v1beta/models/#{model}:generateContent?key=#{key}", headers)
       image = LLM::Object.from_hash(value: LLM.File(image), kind: :local_file)
       body  = JSON.dump({

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

@@ -32,6 +32,7 @@ class LLM::OpenAI
     def format_schema(params)
       return {} unless params and params[:schema]
       schema = params.delete(:schema)
+      schema = schema.respond_to?(:object) ? schema.object : schema
       {
         response_format: {
           type: "json_schema",

data/lib/llm/providers/openai/response/enumerable.rb

@@ -3,11 +3,19 @@
 module LLM::OpenAI::Response
   module Enumerable
     include ::Enumerable
+
     def each(&)
       return enum_for(:each) unless block_given?
       data.each { yield(_1) }
     end
 
+    ##
+    # Returns an element, or a slice, or nil
+    # @return [Object, Array<Object>, nil]
+    def [](*pos, **kw)
+      data[*pos, **kw]
+    end
+
     ##
     # @return [Boolean]
     def empty?

data/lib/llm/providers/openai/vector_stores.rb

@@ -16,6 +16,9 @@ class LLM::OpenAI
     require_relative "response/enumerable"
     PollError = Class.new(LLM::Error)
 
+    INTERVAL = 0.01
+    private_constant :INTERVAL
+
     ##
     # @param [LLM::Provider] provider
     #  An OpenAI provider
@@ -51,10 +54,11 @@ class LLM::OpenAI
 
     ##
     # Create a vector store and poll until its status is "completed"
+    # @param interval [Float] The interval between polling attempts (seconds)
     # @param (see LLM::OpenAI::VectorStores#create)
     # @return (see LLM::OpenAI::VectorStores#poll)
-    def create_and_poll(...)
-      poll(vector: create(...))
+    def create_and_poll(interval: INTERVAL, **rest)
+      poll(interval:, vector: create(**rest))
     end
 
     ##
@@ -149,6 +153,16 @@ class LLM::OpenAI
     end
     alias_method :create_file, :add_file
 
+    ##
+    # Add a file to a vector store and poll until its status is "completed"
+    # @param interval [Float] The interval between polling attempts (seconds)
+    # @param (see LLM::OpenAI::VectorStores#add_file)
+    # @return (see LLM::OpenAI::VectorStores#poll)
+    def add_file_and_poll(vector:, file:, interval: INTERVAL, **rest)
+      poll(vector:, interval:, file: add_file(vector:, file:, **rest))
+    end
+    alias_method :create_file_and_poll, :add_file_and_poll
+
     ##
     # Update a file in a vector store
     # @param [String, #id] vector The ID of the vector store
@@ -199,23 +213,26 @@ class LLM::OpenAI
     end
 
     ##
-    # Poll a vector store until its status is "completed"
+    # Poll a vector store or file until its status is "completed"
     # @param [String, #id] vector The ID of the vector store
+    # @param [String, #id] file The file to poll (optional)
     # @param [Integer] attempts The current number of attempts (default: 0)
     # @param [Integer] max The maximum number of iterations (default: 50)
+    # @param [Float] interval The interval between polling attempts (seconds)
     # @raise [LLM::PollError] When the maximum number of iterations is reached
     # @return [LLM::Response]
-    def poll(vector:, attempts: 0, max: 50)
+    def poll(vector:, file: nil, attempts: 0, max: 50, interval: INTERVAL)
+      target = file || vector
       if attempts == max
-        raise LLM::PollError, "vector store '#{vector.id}' has status '#{vector.status}' after #{max} attempts"
-      elsif vector.status == "expired"
-        raise LLM::PollError, "vector store '#{vector.id}' has expired"
-      elsif vector.status != "completed"
-        vector = get(vector:)
-        sleep(0.1 * (2**attempts))
-        poll(vector:, attempts: attempts + 1, max:)
+        raise LLM::PollError, "'#{target.id}' has status '#{target.status}' after #{max} attempts"
+      elsif target.status == "expired"
+        raise LLM::PollError, "#{target.id}' has expired"
+      elsif target.status != "completed"
+        file ? (file = get_file(vector:, file:)) : (vector = get(vector:))
+        sleep(interval * (2**attempts)) unless interval.zero?
+        poll(vector:, file:, attempts: attempts + 1, max:, interval:)
       else
-        vector
+        target
       end
     end
 

data/lib/llm/schema/array.rb

@@ -7,6 +7,13 @@ class LLM::Schema
   # {LLM::Schema::Leaf LLM::Schema::Leaf} and provides methods that
   # can act as constraints.
   class Array < Leaf
+    ##
+    # Returns an array for the given type
+    # @return [LLM::Schema::Array]
+    def self.[](type)
+      new(type.new)
+    end
+
     def initialize(items)
       @items = items
     end

data/lib/llm/schema/leaf.rb

@@ -20,16 +20,24 @@ class LLM::Schema
     # Set the description of a leaf
     # @param [String] str The description
     # @return [LLM::Schema::Leaf]
-    def description(str)
-      tap { @description = str }
+    def description(str = nil)
+      if str.nil?
+        @description
+      else
+        tap { @description = str }
+      end
     end
 
     ##
     # Set the default value of a leaf
     # @param [Object] value The default value
     # @return [LLM::Schema::Leaf]
-    def default(value)
-      tap { @default = value }
+    def default(value = nil)
+      if value.nil?
+        @default
+      else
+        tap { @default = value }
+      end
     end
 
     ##
@@ -38,7 +46,11 @@ class LLM::Schema
     # @param [Array] values The allowed values
     # @return [LLM::Schema::Leaf]
     def enum(*values)
-      tap { @enum = values }
+      if values.empty?
+        @enum
+      else
+        tap { @enum = values }
+      end
     end
 
     ##
@@ -46,17 +58,40 @@ class LLM::Schema
     # @see https://tour.json-schema.org/content/02-Primitive-Types/08-Defining-Constant-Values Constant Values
     # @param [Object] value The constant value
     # @return [LLM::Schema::Leaf]
-    def const(value)
-      tap { @const = value }
+    def const(value = nil)
+      if value.nil?
+        @const
+      else
+        tap { @const = value }
+      end
     end
 
     ##
-    # Denote a leaf as required
+    # Mark a leaf as required
     # @return [LLM::Schema::Leaf]
     def required
       tap { @required = true }
     end
 
+    ##
+    # @return [Boolean]
+    def required?
+      @required
+    end
+
+    ##
+    # Mark a leaf as optional
+    # @return [LLM::Schema::Leaf]
+    def optional
+      tap { @required = false }
+    end
+
+    ##
+    # @return [Boolean]
+    def optional?
+      !@required
+    end
+
     ##
     # @return [Hash]
     def to_h
@@ -70,9 +105,13 @@ class LLM::Schema
     end
 
     ##
+    # @param [LLM::Schema::Leaf] other
+    #  An object to compare
     # @return [Boolean]
-    def required?
-      @required
+    def ==(other)
+      return false unless self.class === other
+      to_h == other.to_h
     end
+    alias_method :eql?, :==
   end
 end

data/lib/llm/schema/object.rb

@@ -19,6 +19,20 @@ class LLM::Schema
       @properties = properties
     end
 
+    ##
+    # Get a property
+    # @return [LLM::Schema::Leaf]
+    def [](key)
+      properties[key.to_s]
+    end
+
+    ##
+    # Set a property
+    # @return [void]
+    def []=(key, val)
+      properties[key.to_s] = val
+    end
+
     ##
     # @return [Hash]
     def to_h
@@ -42,6 +56,12 @@ class LLM::Schema
       to_h.to_json(options)
     end
 
+    ##
+    # @return [Array<String>]
+    def keys
+      @properties.keys
+    end
+
     private
 
     def required

data/lib/llm/schema.rb

@@ -28,6 +28,63 @@ class LLM::Schema
   require_relative "schema/boolean"
   require_relative "schema/null"
 
+  ##
+  # Configures a monitor for a subclass
+  # @return [void]
+  def self.inherited(klass)
+    LLM.lock(:inherited) do
+      klass.instance_eval { @__monitor = Monitor.new }
+    end
+  end
+
+  ##
+  # @param [String] name
+  #  The property name
+  # @param [Class] type
+  #  The property type
+  # @param [String] description
+  #  The property description
+  # @param [Hash] options
+  #  A hash of options
+  def self.property(name, type, description, options = {})
+    lock do
+      if LLM::Schema::Leaf === type
+        prop = type
+      else
+        target = type.name.split("::").last.downcase
+        prop = schema.public_send(target)
+      end
+      options = {description:}.merge(options)
+      options.each { (_2 == true) ? prop.public_send(_1) : prop.public_send(_1, *_2) }
+      object[name] = prop
+    end
+  end
+
+  ##
+  # @api private
+  # @return [LLM::Schema]
+  def self.schema
+    lock do
+      @schema ||= LLM::Schema.new
+    end
+  end
+
+  ##
+  # @api private
+  # @return [LLM::Schema::Object]
+  def self.object
+    lock do
+      @object ||= schema.object({})
+    end
+  end
+
+  ##
+  # @api private
+  def self.lock(&)
+    @__monitor.synchronize(&)
+  end
+  private_class_method :lock
+
   ##
   # Returns an object
   # @param [Hash] properties A hash of properties

data/lib/llm/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module LLM
-  VERSION = "2.0.1"
+  VERSION = "2.1.0"
 end

data/llm.gemspec

@@ -12,7 +12,7 @@ Gem::Specification.new do |spec|
   llm.rb is a zero-dependency Ruby toolkit for Large Language Models that
   includes OpenAI, Gemini, Anthropic, xAI (grok), zAI, DeepSeek, Ollama, and
   LlamaCpp. The toolkit includes full support for chat, streaming, tool calling,
-  audio, images, files, and structured outputs (JSON Schema).
+  audio, images, files, and structured outputs.
   SUMMARY
 
   spec.description = spec.summary

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: llm.rb
 version: !ruby/object:Gem::Version
-  version: 2.0.1
+  version: 2.1.0
 platform: ruby
 authors:
 - Antar Azri
@@ -167,7 +167,7 @@ dependencies:
 description: llm.rb is a zero-dependency Ruby toolkit for Large Language Models that
   includes OpenAI, Gemini, Anthropic, xAI (grok), zAI, DeepSeek, Ollama, and LlamaCpp.
   The toolkit includes full support for chat, streaming, tool calling, audio, images,
-  files, and structured outputs (JSON Schema).
+  files, and structured outputs.
 email:
 - azantar@proton.me
 - 0x1eef@proton.me
@@ -304,5 +304,5 @@ specification_version: 4
 summary: llm.rb is a zero-dependency Ruby toolkit for Large Language Models that includes
   OpenAI, Gemini, Anthropic, xAI (grok), zAI, DeepSeek, Ollama, and LlamaCpp. The
   toolkit includes full support for chat, streaming, tool calling, audio, images,
-  files, and structured outputs (JSON Schema).
+  files, and structured outputs.
 test_files: []