llm.rb 2.1.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8578f727c5a45b243d86f498cf1a3fcc594981f4056234d2376805744b7e7633
-  data.tar.gz: 03aefaa4ebdf15200e0d6999a8b7015e101dcc0d9afff4c205672a6fa94532c4
+  metadata.gz: 2e60be1fa699baabf9a1df129d0263d0c2b6fecc3ce2b818128eed319aa7bb18
+  data.tar.gz: a39d32cd9cfcfb7fa4152ba3e02960522b6ae4b5d6e22705b846f5b9dcd2972b
 SHA512:
-  metadata.gz: 1b969f525f44192999bcb3ea45aec1e53283d6bb4347b6852bc0bfe9095ecf4d9a9d21a42f7b04e6c530329bf96deb0fa0508757b9e0c185b8944d1630da1648
-  data.tar.gz: 239ff739c3f9bfdfbe8f574a1045acac9ace3bbb0ddca3a92958fee9319e4834c2f057a61c9b0c418979111050ade4968a01ec73862f70278b75cbe7752c9815
+  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
@@ -102,6 +106,7 @@ bot.messages.select(&:assistant?).each { print "[#{it.role}] ", it.content, "\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
 
@@ -115,6 +120,7 @@ bot.messages.select(&:assistant?).each { print "[#{it.role}] ", it.content, "\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

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

data/lib/llm/message.rb

@@ -54,7 +54,7 @@ module LLM
     # Try to parse the content as JSON
     # @return [Hash]
     def content!
-      JSON.parse(content)
+      LLM.json.load(content)
     end
 
     ##
@@ -67,20 +67,6 @@ module LLM
       end
     end
 
-    ##
-    # Marks the message as read
-    # @return [void]
-    def read!
-      @read = true
-    end
-
-    ##
-    # Returns true when the message has been read
-    # @return [Boolean]
-    def read?
-      @read
-    end
-
     ##
     # Returns true when the message is an assistant message
     # @return [Boolean]
@@ -134,25 +120,18 @@ module LLM
     # Returns annotations associated with the message
     # @return [Array<LLM::Object>]
     def annotations
-      @annotations ||= LLM::Object.from_hash(extra["annotations"] || [])
+      @annotations ||= LLM::Object.from(extra["annotations"] || [])
     end
 
     ##
     # @note
     #  This method returns token usage for assistant messages,
-    #  and it returns an empty object for non-assistant messages
+    #  and it returns nil for non-assistant messages
     # Returns token usage statistics
-    # @return [LLM::Object]
+    # @return [LLM::Object, nil]
     def usage
-      @usage ||= if response
-        LLM::Object.from_hash({
-          input_tokens: response.prompt_tokens || 0,
-          output_tokens: response.completion_tokens || 0,
-          total_tokens: response.total_tokens || 0
-        })
-      else
-        LLM::Object.from_hash({})
-      end
+      return nil unless response
+      @usage ||= response.usage
     end
     alias_method :token_usage, :usage
 
@@ -168,7 +147,7 @@ module LLM
     private
 
     def tool_calls
-      @tool_calls ||= LLM::Object.from_hash(@extra[:tool_calls] || [])
+      @tool_calls ||= LLM::Object.from(@extra[:tool_calls] || [])
     end
 
     def tools

data/lib/llm/multipart/enumerator_io.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+class LLM::Multipart
+  ##
+  # @private
+  # Wraps an Enumerator as an IO-like object for streaming bodies.
+  class EnumeratorIO
+    ##
+    # @param [Enumerator] enum
+    #  The enumerator yielding body chunks
+    def initialize(enum)
+      @enum = enum
+      @buffer = +""
+      @eof = false
+    end
+
+    ##
+    # Reads bytes from the stream
+    # @param [Integer, nil] length
+    #  The number of bytes to read (all when nil)
+    # @param [String] outbuf
+    #  The buffer to fill
+    # @return [String, nil]
+    #  Returns the data read, or nil on EOF
+    def read(length = nil, outbuf = +"")
+      outbuf.clear
+      if length.nil?
+        read_all(outbuf)
+      else
+        read_chunk(length, outbuf)
+      end
+    end
+
+    ##
+    # Returns true when no more data is available
+    # @return [Boolean]
+    def eof?
+      @eof && @buffer.empty?
+    end
+
+    ##
+    # Raises when called, the stream is not rewindable
+    # @raise [IOError]
+    def rewind
+      raise IOError, "stream is not rewindable"
+    end
+
+    private
+
+    def read_all(outbuf)
+      fill_buffer
+      return nil if eof?
+      outbuf << @buffer
+      @buffer.clear
+      while (chunk = next_chunk)
+        outbuf << chunk
+      end
+      @eof = true
+      outbuf
+    end
+
+    def read_chunk(length, outbuf)
+      fill_buffer while @buffer.bytesize < length && !@eof
+      return nil if eof?
+      outbuf << @buffer.byteslice(0, length)
+      @buffer = @buffer.byteslice(length..-1) || +""
+      outbuf
+    end
+
+    def fill_buffer
+      return if @eof
+      chunk = next_chunk
+      if chunk
+        @buffer << chunk
+      else
+        @eof = true
+      end
+    end
+
+    def next_chunk
+      @enum.next
+    rescue StopIteration
+      nil
+    end
+  end
+end