llm.rb 2.0.1 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 25cfa0f4004670cb739599150aa68cc74123a8d835b4a72a91c80b7e98640a6a
-  data.tar.gz: 1a8e7547baa911c8d03c84f7e4f849f7bd36f574aa709732e0397b033addd617
+  metadata.gz: 2e60be1fa699baabf9a1df129d0263d0c2b6fecc3ce2b818128eed319aa7bb18
+  data.tar.gz: a39d32cd9cfcfb7fa4152ba3e02960522b6ae4b5d6e22705b846f5b9dcd2972b
 SHA512:
-  metadata.gz: aad8b1f2cd63ecb95875cd30e09a2dc514bd332b676653825f08ecc776fffcebe16d47a0a4252dad91dfbb4f27a62bbd75b033b04383591edc87788a15551817
-  data.tar.gz: f894b483b8700ed334e0d499baa0d2f5b3b5fb331356267210de8d0111fd6281c1ae4ed139edb7947d578587567e2d4d9f181352b9bf4a6fc149ed91562ec57f
+  metadata.gz: 4d434afe1a6acaeef6036178c5914500e047450ee7d92999dedd80f66a6be22c73f4d788f86739842ee283c579b68476c0a114f50e25e7db7bbfa6e6cdf1a5bc
+  data.tar.gz: e818753b0b06cf4053652d11b2e3c79d7ef58de0b0acc5fb7fa147e55c693eee583f1c9e1f80b08096de95247c03644fad9e596f4511d57a99d2abd5339087c2

data/README.md

@@ -1,3 +1,7 @@
+> **Minimal footprint** <br>
+> Zero dependencies outside Ruby’s standard library. <br>
+> Zero runtime dependencies.
+
 ## About
 
 llm.rb is a zero-dependency Ruby toolkit for Large Language Models that
@@ -9,8 +13,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 +23,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 +40,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!
 
-print "age: ", body["age"], "\n"
-print "confidence: ", body["confidence"], "\n"
-print "notes: ", body["notes"], "\n"
+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
+
+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
@@ -75,6 +106,7 @@ print "notes: ", body["notes"], "\n"
 #### General
 - ✅ A single unified interface for multiple providers
 - 📦 Zero dependencies outside Ruby's standard library
+- 🧩 Choose your own JSON parser (JSON stdlib, Oj, Yajl, etc)
 - 🚀 Simple, composable API
 - ♻️ Optional: per-provider, process-wide connection pool via net-http-persistent
 
@@ -88,6 +120,7 @@ print "notes: ", body["notes"], "\n"
 - 🗣️ Text-to-speech, transcription, and translation
 - 🖼️ Image generation, editing, and variation support
 - 📎 File uploads and prompt-aware file interaction
+- 📦 Streams multipart uploads and avoids buffering large files in memory
 - 💡 Multimodal prompts (text, documents, audio, images, videos, URLs, etc)
 
 #### Embeddings
@@ -210,7 +243,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 +269,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 +310,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/bot.rb

@@ -119,7 +119,7 @@ module LLM
     # if there are no assistant messages
     # @return [LLM::Object]
     def usage
-      @messages.find(&:assistant?)&.usage || LLM::Object.from_hash({})
+      @messages.find(&:assistant?)&.usage || LLM::Object.from({})
     end
 
     ##
@@ -141,7 +141,7 @@ module LLM
     # @return [LLM::Object]
     #  Returns a tagged object
     def image_url(url)
-      LLM::Object.from_hash(value: url, kind: :image_url)
+      LLM::Object.from(value: url, kind: :image_url)
     end
 
     ##
@@ -151,7 +151,7 @@ module LLM
     # @return [LLM::Object]
     #  Returns a tagged object
     def local_file(path)
-      LLM::Object.from_hash(value: LLM.File(path), kind: :local_file)
+      LLM::Object.from(value: LLM.File(path), kind: :local_file)
     end
 
     ##
@@ -161,7 +161,7 @@ module LLM
     # @return [LLM::Object]
     #  Returns a tagged object
     def remote_file(res)
-      LLM::Object.from_hash(value: res, kind: :remote_file)
+      LLM::Object.from(value: res, kind: :remote_file)
     end
 
     private

data/lib/llm/buffer.rb

@@ -35,15 +35,6 @@ module LLM
       end
     end
 
-    ##
-    # Returns an array of unread messages
-    # @see LLM::Message#read?
-    # @see LLM::Message#read!
-    # @return [Array<LLM::Message>]
-    def unread
-      reject(&:read?)
-    end
-
     ##
     # Find a message (in descending order)
     # @return [LLM::Message, nil]

data/lib/llm/contract/completion.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module LLM::Contract
+  ##
+  # Defines the interface all completion responses must implement
+  # @abstract
+  module Completion
+    extend LLM::Contract
+
+    ##
+    # @return [Array<LLM::Messsage>]
+    #  Returns one or more messages
+    def messages
+      raise NotImplementedError, "#{self.class} does not implement '#{__method__}'"
+    end
+    alias_method :choices, :messages
+
+    ##
+    # @return [Integer]
+    #  Returns the number of input tokens
+    def input_tokens
+      raise NotImplementedError, "#{self.class} does not implement '#{__method__}'"
+    end
+
+    ##
+    # @return [Integer]
+    #  Returns the number of output tokens
+    def output_tokens
+      raise NotImplementedError, "#{self.class} does not implement '#{__method__}'"
+    end
+
+    ##
+    # @return [Integer]
+    #  Returns the total number of tokens
+    def total_tokens
+      raise NotImplementedError, "#{self.class} does not implement '#{__method__}'"
+    end
+
+    ##
+    # @return [LLM::Usage]
+    #  Returns usage information
+    def usage
+      LLM::Usage.new(
+        input_tokens:,
+        output_tokens:,
+        total_tokens:
+      )
+    end
+
+    ##
+    # @return [String]
+    #  Returns the model name
+    def model
+      raise NotImplementedError, "#{self.class} does not implement '#{__method__}'"
+    end
+  end
+end

data/lib/llm/contract.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module LLM
+  ##
+  # The `LLM::Contract` module provides the ability for modules
+  # who are extended by it to implement contracts which must be
+  # implemented by other modules who include a given contract.
+  #
+  # @example
+  #   module LLM::Contract
+  #      # ..
+  #   end
+  #
+  #   module LLM::Contract
+  #     module Completion
+  #       extend LLM::Contract
+  #       # inheriting modules must implement these methods
+  #       # otherwise an error is raised on include
+  #       def foo = nil
+  #       def bar = nil
+  #     end
+  #   end
+  #
+  #   module LLM::OpenAI::ResponseAdapter
+  #     module Completion
+  #       def foo = nil
+  #       def bar = nil
+  #       include LLM::Contract::Completion
+  #     end
+  #   end
+  module Contract
+    ContractError = Class.new(LLM::Error)
+    require_relative "contract/completion"
+
+    ##
+    # @api private
+    def included(mod)
+      meths = mod.instance_methods(false)
+      if meths.empty?
+        raise ContractError, "#{mod} does not implement any methods required by #{self}"
+      end
+      missing = instance_methods - meths
+      if missing.any?
+        raise ContractError, "#{mod} does not implement methods (#{missing.join(", ")}) required by #{self}"
+      end
+    end
+  end
+end

data/lib/llm/error.rb

@@ -4,40 +4,40 @@ module LLM
   ##
   # The superclass of all LLM errors
   class Error < RuntimeError
+    ##
+    # @return [Net::HTTPResponse, nil]
+    #  Returns the response associated with an error, or nil
+    attr_accessor :response
+
     def initialize(...)
       block_given? ? yield(self) : nil
       super
     end
-  end
-
-  ##
-  # The superclass of all HTTP protocol errors
-  class ResponseError < Error
-    ##
-    # @return [Net::HTTPResponse]
-    #  Returns the response associated with an error
-    attr_accessor :response
 
     def message
-      [super, response.body].join("\n")
+      if response
+        [super, response.body].join("\n")
+      else
+        super
+      end
     end
   end
 
   ##
   # HTTPUnauthorized
-  UnauthorizedError = Class.new(ResponseError)
+  UnauthorizedError = Class.new(Error)
 
   ##
   # HTTPTooManyRequests
-  RateLimitError = Class.new(ResponseError)
+  RateLimitError = Class.new(Error)
 
   ##
   # HTTPServerError
-  ServerError = Class.new(ResponseError)
+  ServerError = Class.new(Error)
 
   ##
   # When no images are found in a response
-  NoImageError = Class.new(ResponseError)
+  NoImageError = Class.new(Error)
 
   ##
   # When an given an input object that is not understood
@@ -46,4 +46,12 @@ module LLM
   ##
   # When given a prompt object that is not understood
   PromptError = Class.new(FormatError)
+
+  ##
+  # When given an invalid request
+  InvalidRequestError = Class.new(Error)
+
+  ##
+  # When the context window is exceeded
+  ContextWindowError = Class.new(InvalidRequestError)
 end

data/lib/llm/eventhandler.rb

@@ -17,9 +17,10 @@ module LLM
     # @return [void]
     def on_data(event)
       return if event.end?
-      chunk = JSON.parse(event.value)
+      chunk = LLM.json.load(event.value)
+      return unless chunk
       @parser.parse!(chunk)
-    rescue JSON::ParserError
+    rescue *LLM.json.parser_error
     end
 
     ##
@@ -31,9 +32,10 @@ module LLM
     # @return [void]
     def on_chunk(event)
       return if event.end?
-      chunk = JSON.parse(event.chunk)
+      chunk = LLM.json.load(event.chunk)
+      return unless chunk
       @parser.parse!(chunk)
-    rescue JSON::ParserError
+    rescue *LLM.json.parser_error
     end
 
     ##

data/lib/llm/eventstream/parser.rb

@@ -7,9 +7,9 @@ module LLM::EventStream
     ##
     # @return [LLM::EventStream::Parser]
     def initialize
-      @buffer = StringIO.new
+      @buffer = +""
       @events = Hash.new { |h, k| h[k] = [] }
-      @offset = 0
+      @cursor = 0
       @visitors = []
     end
 
@@ -34,8 +34,7 @@ module LLM::EventStream
     # Append an event to the internal buffer
     # @return [void]
     def <<(event)
-      io = StringIO.new(event)
-      IO.copy_stream io, @buffer
+      @buffer << event
       each_line { parse!(_1) }
     end
 
@@ -43,15 +42,15 @@ module LLM::EventStream
     # Returns the internal buffer
     # @return [String]
     def body
-      @buffer.string
+      @buffer.dup
     end
 
     ##
     # Free the internal buffer
     # @return [void]
     def free
-      @buffer.truncate(0)
-      @buffer.rewind
+      @buffer.clear
+      @cursor = 0
     end
 
     private
@@ -76,13 +75,19 @@ module LLM::EventStream
     end
 
     def each_line
-      string.each_line.with_index do
-        next if _2 < @offset
-        yield(_1)
-        @offset += 1
+      while (newline = @buffer.index("\n", @cursor))
+        line = @buffer[@cursor..newline]
+        @cursor = newline + 1
+        yield(line)
       end
+      if @cursor < @buffer.length
+        line = @buffer[@cursor..]
+        @cursor = @buffer.length
+        yield(line)
+      end
+      return if @cursor.zero?
+      @buffer = @buffer[@cursor..] || +""
+      @cursor = 0
     end
-
-    def string = @buffer.string
   end
 end

data/lib/llm/function.rb

@@ -149,7 +149,7 @@ class LLM::Function
 
   ##
   # @return [Hash]
-  def format(provider)
+  def adapt(provider)
     case provider.class.to_s
     when "LLM::Gemini"
       {name: @name, description: @description, parameters: @params}.compact

data/lib/llm/json_adapter.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module LLM
+  ##
+  # The JSONAdapter class defines the interface for JSON parsers
+  # that can be used by the library when dealing with JSON. The
+  # following parsers are supported:
+  # * {LLM::JSONAdapter::JSON LLM::JSONAdapter::JSON} (default)
+  # * {LLM::JSONAdapter::Oj LLM::JSONAdapter::Oj}
+  # * {LLM::JSONAdapter::Yajl LLM::JSONAdapter::Yajl}
+  #
+  # @example Change parser
+  #   LLM.json = LLM::JSONAdapter::Oj
+  class JSONAdapter
+    ##
+    # @return [String]
+    #  Returns a JSON string representation of the given object
+    def self.dump(*) = raise NotImplementedError
+
+    ##
+    # @return [Object]
+    #  Returns a Ruby object parsed from the given JSON string
+    def self.load(*) = raise NotImplementedError
+
+    ##
+    # @return [Exception]
+    #  Returns the error raised when parsing fails
+    def self.parser_error = [StandardError]
+  end
+
+  ##
+  # The {LLM::JSONAdapter::JSON LLM::JSONAdapter::JSON} class
+  # provides a JSON adapter backed by the standard library
+  # JSON module.
+  class JSONAdapter::JSON < JSONAdapter
+    ##
+    # @return (see JSONAdapter#dump)
+    def self.dump(obj)
+      require "json" unless defined?(::JSON)
+      ::JSON.dump(obj)
+    end
+
+    ##
+    # @return (see JSONAdapter#load)
+    def self.load(string)
+      require "json" unless defined?(::JSON)
+      ::JSON.parse(string)
+    end
+
+    ##
+    # @return (see JSONAdapter#parser_error)
+    def self.parser_error
+      require "json" unless defined?(::JSON)
+      [::JSON::ParserError]
+    end
+  end
+
+  ##
+  # The {LLM::JSONAdapter::Oj LLM::JSONAdapter::Oj} class
+  # provides a JSON adapter backed by the Oj gem.
+  class JSONAdapter::Oj < JSONAdapter
+    ##
+    # @return (see JSONAdapter#dump)
+    def self.dump(obj)
+      require "oj" unless defined?(::Oj)
+      ::Oj.dump(obj)
+    end
+
+    ##
+    # @return (see JSONAdapter#load)
+    def self.load(string)
+      require "oj" unless defined?(::Oj)
+      ::Oj.load(string, mode: :compat, symbol_keys: false, symbolize_names: false)
+    end
+
+    ##
+    # @return (see JSONAdapter#parser_error)
+    def self.parser_error
+      require "oj" unless defined?(::Oj)
+      [::Oj::ParseError, ::EncodingError]
+    end
+  end
+
+  ##
+  # The {LLM::JSONAdapter::Yajl LLM::JSONAdapter::Yajl} class
+  # provides a JSON adapter backed by the Yajl gem.
+  class JSONAdapter::Yajl < JSONAdapter
+    ##
+    # @return (see JSONAdapter#dump)
+    def self.dump(obj)
+      require "yajl" unless defined?(::Yajl)
+      ::Yajl::Encoder.encode(obj)
+    end
+
+    ##
+    # @return (see JSONAdapter#load)
+    def self.load(string)
+      require "yajl" unless defined?(::Yajl)
+      ::Yajl::Parser.parse(string)
+    end
+
+    ##
+    # @return (see JSONAdapter#parser_error)
+    def self.parser_error
+      require "yajl" unless defined?(::Yajl)
+      [::Yajl::ParseError]
+    end
+  end
+end