llm.rb 0.7.2 → 0.9.0

data/lib/llm/error.rb

@@ -8,26 +8,34 @@ module LLM
       block_given? ? yield(self) : nil
       super
     end
+  end
 
+  ##
+  # The superclass of all HTTP protocol errors
+  class ResponseError < Error
     ##
-    # The superclass of all HTTP protocol errors
-    class ResponseError < Error
-      ##
-      # @return [Net::HTTPResponse]
-      #  Returns the response associated with an error
-      attr_accessor :response
+    # @return [Net::HTTPResponse]
+    #  Returns the response associated with an error
+    attr_accessor :response
+
+    def message
+      [super, response.body].join("\n")
     end
+  end
 
-    ##
-    # When a prompt is given an object that's not understood
-    PromptError = Class.new(Error)
+  ##
+  # HTTPUnauthorized
+  UnauthorizedError = Class.new(ResponseError)
 
-    ##
-    # HTTPUnauthorized
-    Unauthorized = Class.new(ResponseError)
+  ##
+  # HTTPTooManyRequests
+  RateLimitError = Class.new(ResponseError)
 
-    ##
-    # HTTPTooManyRequests
-    RateLimit = Class.new(ResponseError)
-  end
+  ##
+  # When an given an input object that is not understood
+  FormatError = Class.new(Error)
+
+  ##
+  # When given a prompt object that is not understood
+  PromptError = Class.new(FormatError)
 end

data/lib/llm/event_handler.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module LLM
+  ##
+  # @private
+  class EventHandler
+    ##
+    # @param [#parse!] parser
+    # @return [LLM::EventHandler]
+    def initialize(parser)
+      @parser = parser
+    end
+
+    ##
+    # "data:" event callback
+    # @param [LLM::EventStream::Event] event
+    # @return [void]
+    def on_data(event)
+      return if event.end?
+      chunk = JSON.parse(event.value)
+      @parser.parse!(chunk)
+    rescue JSON::ParserError
+    end
+
+    ##
+    # Callback for when *any* of chunk of data
+    # is received, regardless of whether it has
+    # a field name or not. Primarily for ollama,
+    # which does emit Server-Sent Events (SSE).
+    # @param [LLM::EventStream::Event] event
+    # @return [void]
+    def on_chunk(event)
+      return if event.end?
+      chunk = JSON.parse(event.chunk)
+      @parser.parse!(chunk)
+    rescue JSON::ParserError
+    end
+
+    ##
+    # Returns a fully constructed response body
+    # @return [LLM::Object]
+    def body = @parser.body
+  end
+end

data/lib/llm/eventstream/event.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module LLM::EventStream
+  ##
+  # @private
+  class Event
+    FIELD_REGEXP = /[^:]+/
+    VALUE_REGEXP = /(?<=: ).+/
+
+    ##
+    # Returns the field name
+    # @return [Symbol]
+    attr_reader :field
+
+    ##
+    # Returns the field value
+    # @return [String]
+    attr_reader :value
+
+    ##
+    # Returns the full chunk
+    # @return [String]
+    attr_reader :chunk
+
+    ##
+    # @param [String] chunk
+    # @return [LLM::EventStream::Event]
+    def initialize(chunk)
+      @field = chunk[FIELD_REGEXP]
+      @value = chunk[VALUE_REGEXP]
+      @chunk = chunk
+    end
+
+    ##
+    # Returns true when the event represents an "id" chunk
+    # @return [Boolean]
+    def id?
+      @field == "id"
+    end
+
+    ##
+    # Returns true when the event represents a "data" chunk
+    # @return [Boolean]
+    def data?
+      @field == "data"
+    end
+
+    ##
+    # Returns true when the event represents an "event" chunk
+    # @return [Boolean]
+    def event?
+      @field == "event"
+    end
+
+    ##
+    # Returns true when the event represents a "retry" chunk
+    # @return [Boolean]
+    def retry?
+      @field == "retry"
+    end
+
+    ##
+    # Returns true when a chunk represents the end of the stream
+    # @return [Boolean]
+    def end?
+      @value == "[DONE]"
+    end
+  end
+end

data/lib/llm/eventstream/parser.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module LLM::EventStream
+  ##
+  # @private
+  class Parser
+    ##
+    # @return [LLM::EventStream::Parser]
+    def initialize
+      @buffer = StringIO.new
+      @events = Hash.new { |h, k| h[k] = [] }
+      @offset = 0
+      @visitors = []
+    end
+
+    ##
+    # Register a visitor
+    # @param [#on_data] visitor
+    # @return [void]
+    def register(visitor)
+      @visitors << visitor
+    end
+
+    ##
+    # Subscribe to an event
+    # @param [Symbol] evtname
+    # @param [Proc] block
+    # @return [void]
+    def on(evtname, &block)
+      @events[evtname.to_s] << block
+    end
+
+    ##
+    # Append an event to the internal buffer
+    # @return [void]
+    def <<(event)
+      io = StringIO.new(event)
+      IO.copy_stream io, @buffer
+      each_line { parse!(_1) }
+    end
+
+    ##
+    # Returns the internal buffer
+    # @return [String]
+    def body
+      @buffer.string
+    end
+
+    ##
+    # Free the internal buffer
+    # @return [void]
+    def free
+      @buffer.truncate(0)
+      @buffer.rewind
+    end
+
+    private
+
+    def parse!(event)
+      event = Event.new(event)
+      dispatch(event)
+    end
+
+    def dispatch(event)
+      @visitors.each { dispatch_visitor(_1, event) }
+      @events[event.field].each { _1.call(event) }
+    end
+
+    def dispatch_visitor(visitor, event)
+      method = "on_#{event.field}"
+      if visitor.respond_to?(method)
+        visitor.public_send(method, event)
+      elsif visitor.respond_to?("on_chunk")
+        visitor.on_chunk(event)
+      end
+    end
+
+    def each_line
+      string.each_line.with_index do
+        next if _2 < @offset
+        yield(_1)
+        @offset += 1
+      end
+    end
+
+    def string = @buffer.string
+  end
+end

data/lib/llm/eventstream.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+##
+# @private
+module LLM::EventStream
+  require_relative "eventstream/parser"
+  require_relative "eventstream/event"
+end

data/lib/llm/function.rb

@@ -1,32 +1,29 @@
 # frozen_string_literal: true
 
 ##
-# The {LLM::Function LLM::Function} class represents a function that can
-# be called by an LLM. It comes in two forms: a Proc-based function,
-# or a Class-based function.
+# The {LLM::Function LLM::Function} class represents a
+# local function that can be called by an LLM.
 #
-# @example
-#   # Proc-based
+# @example example #1
 #   LLM.function(:system) do |fn|
-#     fn.description "Runs system commands, emits their output"
+#     fn.description "Runs system commands"
 #     fn.params do |schema|
 #       schema.object(command: schema.string.required)
 #     end
 #     fn.define do |params|
-#       Kernel.system(params.command)
+#       {success: Kernel.system(params.command)}
 #     end
 #   end
 #
-# @example
-#   # Class-based
+# @example example #2
 #   class System
 #     def call(params)
-#       Kernel.system(params.command)
+#       {success: Kernel.system(params.command)}
 #     end
 #   end
 #
 #   LLM.function(:system) do |fn|
-#     fn.description "Runs system commands, emits their output"
+#     fn.description "Runs system commands"
 #     fn.params do |schema|
 #       schema.object(command: schema.string.required)
 #     end
@@ -99,7 +96,7 @@ class LLM::Function
   # Returns a value that communicates that the function call was cancelled
   # @example
   #   llm = LLM.openai(key: ENV["KEY"])
-  #   bot = LLM::Chat.new(llm, tools: [fn1, fn2])
+  #   bot = LLM::Bot.new(llm, tools: [fn1, fn2])
   #   bot.chat "I want to run the functions"
   #   bot.chat bot.functions.map(&:cancel)
   # @return [LLM::Function::Return]

data/lib/{json → llm/json}/schema/array.rb

@@ -7,7 +7,7 @@ class JSON::Schema
   # {JSON::Schema::Leaf JSON::Schema::Leaf} and provides methods that
   # can act as constraints.
   class Array < Leaf
-    def initialize(*items)
+    def initialize(items)
       @items = items
     end
 

data/lib/llm/message.rb

@@ -121,7 +121,7 @@ module LLM
     private
 
     def tool_calls
-      @tool_calls ||= OpenStruct.from_hash(@extra[:tool_calls] || [])
+      @tool_calls ||= LLM::Object.from_hash(@extra[:tool_calls] || [])
     end
   end
 end

data/lib/llm/model.rb

@@ -4,7 +4,7 @@
 # The {LLM::Model LLM::Model} class represents an LLM model that
 # is available to use. Its properties are delegated to the underlying
 # response body, and vary by provider.
-class LLM::Model < OpenStruct
+class LLM::Model < LLM::Object
   ##
   # Returns a subclass of {LLM::Provider LLM::Provider}
   # @return [LLM::Provider]

data/lib/llm/object/builder.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+class LLM::Object
+  ##
+  # @private
+  module Builder
+    ##
+    # @example
+    #   obj = LLM::Object.from_hash(person: {name: 'John'})
+    #   obj.person.name  # => 'John'
+    #   obj.person.class # => LLM::Object
+    # @param [Hash, LLM::Object, Array] obj
+    #   A Hash object
+    # @return [LLM::Object]
+    #   An LLM::Object object initialized by visiting `obj` with recursion
+    def from_hash(obj)
+      case obj
+      when self then from_hash(obj.to_h)
+      when Array then obj.map { |v| from_hash(v) }
+      else
+        visited = {}
+        obj.each { visited[_1] = visit(_2) }
+        new(visited)
+      end
+    end
+
+    private
+
+    def visit(value)
+      case value
+      when self then from_hash(value.to_h)
+      when Hash then from_hash(value)
+      when Array then value.map { |v| visit(v) }
+      else value
+      end
+    end
+  end
+end

data/lib/llm/object/kernel.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+class LLM::Object
+  ##
+  # @private
+  module Kernel
+    def tap(...)
+      ::Kernel.instance_method(:tap).bind(self).call(...)
+    end
+
+    def instance_of?(...)
+      ::Kernel.instance_method(:instance_of?).bind(self).call(...)
+    end
+
+    def method(...)
+      ::Kernel.instance_method(:method).bind(self).call(...)
+    end
+
+    def kind_of?(...)
+      ::Kernel.instance_method(:kind_of?).bind(self).call(...)
+    end
+    alias_method :is_a?, :kind_of?
+
+    def respond_to?(m, include_private = false)
+      @h.key?(m.to_sym) || self.class.instance_methods.include?(m) || super
+    end
+
+    def respond_to_missing?(m, include_private = false)
+      @h.key?(m.to_sym) || super
+    end
+
+    def object_id
+      ::Kernel.instance_method(:object_id).bind(self).call
+    end
+
+    def class
+      ::Kernel.instance_method(:class).bind(self).call
+    end
+
+    def inspect
+      "#<#{self.class}:0x#{object_id.to_s(16)} properties=#{to_h.inspect}>"
+    end
+    alias_method :to_s, :inspect
+  end
+end

data/lib/llm/object.rb

@@ -0,0 +1,77 @@
+# 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
+# similar in spirit to OpenStruct, and it was introduced after OpenStruct
+# became a bundled gem (and not a default gem) in Ruby 3.5.
+class LLM::Object < BasicObject
+  require_relative "object/builder"
+  require_relative "object/kernel"
+
+  extend Builder
+  include Kernel
+  include ::Enumerable
+  defined?(::PP) ? include(::PP::ObjectMixin) : nil
+
+  ##
+  # @param [Hash] h
+  # @return [LLM::Object]
+  def initialize(h = {})
+    @h = h.transform_keys(&:to_sym) || h
+  end
+
+  ##
+  # Yields a key|value pair to a block.
+  # @yieldparam [Symbol] k
+  # @yieldparam [Object] v
+  # @return [void]
+  def each(&)
+    @h.each(&)
+  end
+
+  ##
+  # @param [Symbol, #to_sym] k
+  # @return [Object]
+  def [](k)
+    @h[k.to_sym]
+  end
+
+  ##
+  # @param [Symbol, #to_sym] k
+  # @param [Object] v
+  # @return [void]
+  def []=(k, v)
+    @h[k.to_sym] = v
+  end
+
+  ##
+  # @return [String]
+  def to_json(...)
+    to_h.to_json(...)
+  end
+
+  ##
+  # @return [Boolean]
+  def empty?
+    @h.empty?
+  end
+
+  ##
+  # @return [Hash]
+  def to_h
+    @h
+  end
+
+  private
+
+  def method_missing(m, *args, &b)
+    if m.to_s.end_with?("=")
+      @h[m[0..-2].to_sym] = args.first
+    elsif @h.key?(m)
+      @h[m]
+    else
+      nil
+    end
+  end
+end

data/lib/llm/provider.rb

@@ -21,10 +21,9 @@ class LLM::Provider
   #  Whether to use SSL for the connection
   def initialize(key:, host:, port: 443, timeout: 60, ssl: true)
     @key = key
-    @http = Net::HTTP.new(host, port).tap do |http|
-      http.use_ssl = ssl
-      http.read_timeout = timeout
-    end
+    @client = Net::HTTP.new(host, port)
+    @client.use_ssl = ssl
+    @client.read_timeout = timeout
   end
 
   ##
@@ -78,55 +77,55 @@ class LLM::Provider
   # Starts a new lazy chat powered by the chat completions API
   # @note
   #  This method creates a lazy version of a
-  #  {LLM::Chat LLM::Chat} object.
+  #  {LLM::Bot LLM::Bot} object.
   # @param prompt (see LLM::Provider#complete)
   # @param params (see LLM::Provider#complete)
-  # @return [LLM::Chat]
+  # @return [LLM::Bot]
   def chat(prompt, params = {})
     role = params.delete(:role)
-    LLM::Chat.new(self, params).lazy.chat(prompt, role:)
+    LLM::Bot.new(self, params).chat(prompt, role:)
   end
 
   ##
   # Starts a new chat powered by the chat completions API
   # @note
   #  This method creates a non-lazy version of a
-  #  {LLM::Chat LLM::Chat} object.
+  #  {LLM::Bot LLM::Bot} object.
   # @param prompt (see LLM::Provider#complete)
   # @param params (see LLM::Provider#complete)
   # @raise (see LLM::Provider#complete)
-  # @return [LLM::Chat]
+  # @return [LLM::Bot]
   def chat!(prompt, params = {})
     role = params.delete(:role)
-    LLM::Chat.new(self, params).chat(prompt, role:)
+    LLM::Bot.new(self, params).chat(prompt, role:)
   end
 
   ##
   # Starts a new lazy chat powered by the responses API
   # @note
   #  This method creates a lazy variant of a
-  #  {LLM::Chat LLM::Chat} object.
+  #  {LLM::Bot LLM::Bot} object.
   # @param prompt (see LLM::Provider#complete)
   # @param params (see LLM::Provider#complete)
   # @raise (see LLM::Provider#complete)
-  # @return [LLM::Chat]
+  # @return [LLM::Bot]
   def respond(prompt, params = {})
     role = params.delete(:role)
-    LLM::Chat.new(self, params).lazy.respond(prompt, role:)
+    LLM::Bot.new(self, params).respond(prompt, role:)
   end
 
   ##
   # Starts a new chat powered by the responses API
   # @note
   #  This method creates a non-lazy variant of a
-  #  {LLM::Chat LLM::Chat} object.
+  #  {LLM::Bot LLM::Bot} object.
   # @param prompt (see LLM::Provider#complete)
   # @param params (see LLM::Provider#complete)
   # @raise (see LLM::Provider#complete)
-  # @return [LLM::Chat]
+  # @return [LLM::Bot]
   def respond!(prompt, params = {})
     role = params.delete(:role)
-    LLM::Chat.new(self, params).respond(prompt, role:)
+    LLM::Bot.new(self, params).respond(prompt, role:)
   end
 
   ##
@@ -168,6 +167,13 @@ class LLM::Provider
     raise NotImplementedError
   end
 
+  ##
+  # @return [LLM::OpenAI::Moderations]
+  #  Returns an interface to the moderations API
+  def moderations
+    raise NotImplementedError
+  end
+
   ##
   # @return [String]
   #  Returns the role of the assistant in the conversation.
@@ -187,10 +193,7 @@ class LLM::Provider
   # Returns an object that can generate a JSON schema
   # @return [JSON::Schema]
   def schema
-    @schema ||= begin
-      require_relative "../json/schema"
-      JSON::Schema.new
-    end
+    @schema ||= JSON::Schema.new
   end
 
   ##
@@ -209,6 +212,8 @@ class LLM::Provider
 
   private
 
+  attr_reader :client
+
   ##
   # The headers to include with a request
   # @raise [NotImplementedError]
@@ -236,10 +241,21 @@ class LLM::Provider
   end
 
   ##
-  # Initiates a HTTP request
-  # @param [Net::HTTP] http
-  #  The HTTP object to use for the request
-  # @param [Net::HTTPRequest] req
+  # @return [Class]
+  def event_handler
+    LLM::EventHandler
+  end
+
+  ##
+  # @return [Class]
+  #  Returns the provider-specific Server-Side Events (SSE) parser
+  def stream_parser
+    raise NotImplementedError
+  end
+
+  ##
+  # Executes a HTTP request
+  # @param [Net::HTTPRequest] request
   #  The request to send
   # @param [Proc] b
   #  A block to yield the response to (optional)
@@ -253,8 +269,34 @@ class LLM::Provider
   #  When any other unsuccessful status code is returned
   # @raise [SystemCallError]
   #  When there is a network error at the operating system level
-  def request(http, req, &b)
-    res = http.request(req, &b)
+  # @return [Net::HTTPResponse]
+  def execute(request:, stream: nil, &b)
+    res = if stream
+      client.request(request) do |res|
+        handler = event_handler.new stream_parser.new(stream)
+        parser = LLM::EventStream::Parser.new
+        parser.register(handler)
+        res.read_body(parser)
+        # If the handler body is empty, it means the
+        # response was most likely not streamed or
+        # parsing has failed. In that case, we fallback
+        # on the original response body.
+        res.body = handler.body.empty? ? parser.body.dup : handler.body
+      ensure
+        parser&.free
+      end
+    else
+      client.request(request, &b)
+    end
+    handle_response(res)
+  end
+
+  ##
+  # Handles the response from a request
+  # @param [Net::HTTPResponse] res
+  #  The response to handle
+  # @return [Net::HTTPResponse]
+  def handle_response(res)
     case res
     when Net::HTTPOK then res
     else error_handler.new(res).raise_error!

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

@@ -23,11 +23,11 @@ class LLM::Anthropic
     def raise_error!
       case res
       when Net::HTTPUnauthorized
-        raise LLM::Error::Unauthorized.new { _1.response = res }, "Authentication error"
+        raise LLM::UnauthorizedError.new { _1.response = res }, "Authentication error"
       when Net::HTTPTooManyRequests
-        raise LLM::Error::RateLimit.new { _1.response = res }, "Too many requests"
+        raise LLM::RateLimitError.new { _1.response = res }, "Too many requests"
       else
-        raise LLM::Error::ResponseError.new { _1.response = res }, "Unexpected response"
+        raise LLM::ResponseError.new { _1.response = res }, "Unexpected response"
       end
     end
   end