llm.rb 0.4.2 → 0.6.0

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

data/lib/llm/buffer.rb

@@ -28,6 +28,22 @@ module LLM
       @completed.each { yield(_1) }
     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]
+    def find(...)
+      reverse_each.find(...)
+    end
+
     ##
     # @param [[LLM::Message, Hash]] item
     #  A message and its parameters
@@ -48,7 +64,7 @@ module LLM
     private
 
     def empty!
-      message, params, method = @pending[-1]
+      message, params, method = @pending.pop
       if method == :complete
         complete!(message, params)
       elsif method == :respond
@@ -59,24 +75,27 @@ module LLM
     end
 
     def complete!(message, params)
-      messages = @pending[0..-2].map { _1[0] }
+      pendings = @pending.map { _1[0] }
+      messages = [*@completed, *pendings]
+      role = message.role
       completion = @provider.complete(
         message.content,
-        message.role,
-        **params.merge(messages:)
+        params.merge(role:, messages:)
       )
-      @completed.concat([*messages, message, completion.choices[0]])
+      @completed.concat([*pendings, message, completion.choices[0]])
       @pending.clear
     end
 
     def respond!(message, params)
-      input = @pending[0..-2].map { _1[0] }
-      @response = @provider.responses.create(
-        message.content,
-        message.role,
-        **params.merge(input:).merge(@response ? {previous_response_id: @response.id} : {})
-      )
-      @completed.concat([*input, message, @response.outputs[0]])
+      pendings = @pending.map { _1[0] }
+      input = [*pendings]
+      role = message.role
+      params = [
+        params.merge(input:),
+        @response ? {previous_response_id: @response.id} : {}
+      ].inject({}, &:merge!)
+      @response = @provider.responses.create(message.content, params.merge(role:))
+      @completed.concat([*pendings, message, @response.outputs[0]])
       @pending.clear
     end
   end

data/lib/llm/chat.rb

@@ -13,11 +13,10 @@ module LLM
   #
   #   llm = LLM.openai(ENV["KEY"])
   #   bot = LLM::Chat.new(llm).lazy
-  #   bot.chat("Your task is to answer all of my questions", :system)
-  #   bot.chat("Your answers should be short and concise", :system)
-  #   bot.chat("What is 5 + 7 ?", :user)
-  #   bot.chat("Why is the sky blue ?", :user)
-  #   bot.chat("Why did the chicken cross the road ?", :user)
+  #   bot.chat("Provide short and concise answers", role: :system)
+  #   bot.chat("What is 5 + 7 ?", role: :user)
+  #   bot.chat("Why is the sky blue ?", role: :user)
+  #   bot.chat("Why did the chicken cross the road ?", role: :user)
   #   bot.messages.map { print "[#{_1.role}]", _1.content, "\n" }
   class Chat
     ##
@@ -27,31 +26,34 @@ module LLM
     ##
     # @param [LLM::Provider] provider
     #  A provider
-    # @param [to_json] schema
-    #  The JSON schema to maintain throughout the conversation
-    # @param [String] model
-    #  The model to maintain throughout the conversation
     # @param [Hash] params
-    #  Other parameters to maintain throughout the conversation
-    def initialize(provider, model: provider.default_model, schema: nil, **params)
+    #  The parameters to maintain throughout the conversation.
+    #  Any parameter the provider supports can be included and
+    #  not only those listed here.
+    # @option params [String] :model Defaults to the provider's default model
+    # @option params [#to_json, nil] :schema Defaults to nil
+    # @option params [Array<LLM::Function>, nil] :tools Defaults to nil
+    def initialize(provider, params = {})
       @provider = provider
-      @params = params.merge!(model:, schema:)
+      @params = {model: provider.default_model, schema: nil}.compact.merge!(params)
       @lazy = false
-      @messages = []
+      @messages = [].extend(Array)
     end
 
     ##
     # Maintain a conversation via the chat completions API
-    # @param prompt (see LLM::Provider#prompt)
-    # @param role (see LLM::Provider#prompt)
-    # @param params (see LLM::Provider#prompt)
+    # @param prompt (see LLM::Provider#complete)
+    # @param params (see LLM::Provider#complete)
     # @return [LLM::Chat]
-    def chat(prompt, role = :user, **params)
+    def chat(prompt, params = {})
+      params = {role: :user}.merge!(params)
       if lazy?
+        role = params.delete(:role)
         @messages << [LLM::Message.new(role, prompt), @params.merge(params), :complete]
         self
       else
-        completion = complete!(prompt, role, params)
+        role = params[:role]
+        completion = complete!(prompt, params)
         @messages.concat [Message.new(role, prompt), completion.choices[0]]
         self
       end
@@ -60,16 +62,18 @@ module LLM
     ##
     # Maintain a conversation via the responses API
     # @note Not all LLM providers support this API
-    # @param prompt (see LLM::Provider#prompt)
-    # @param role (see LLM::Provider#prompt)
-    # @param params (see LLM::Provider#prompt)
+    # @param prompt (see LLM::Provider#complete)
+    # @param params (see LLM::Provider#complete)
     # @return [LLM::Chat]
-    def respond(prompt, role = :user, **params)
+    def respond(prompt, params = {})
+      params = {role: :user}.merge!(params)
       if lazy?
+        role = params.delete(:role)
         @messages << [LLM::Message.new(role, prompt), @params.merge(params), :respond]
         self
       else
-        @response = respond!(prompt, role, params)
+        role = params[:role]
+        @response = respond!(prompt, params)
         @messages.concat [Message.new(role, prompt), @response.outputs[0]]
         self
       end
@@ -108,27 +112,50 @@ module LLM
       @lazy
     end
 
+    ##
+    # @return [String]
     def inspect
       "#<#{self.class.name}:0x#{object_id.to_s(16)} " \
       "@provider=#{@provider.class}, @params=#{@params.inspect}, " \
       "@messages=#{@messages.inspect}, @lazy=#{@lazy.inspect}>"
     end
 
+    ##
+    # Returns an array of functions that have yet to be called
+    # @return [Array<LLM::Function>]
+    def functions
+      messages
+        .select(&:assistant?)
+        .flat_map(&:functions)
+        .reject(&:called?)
+    end
+
     private
 
-    def respond!(prompt, role, params)
+    ##
+    # @private
+    module Array
+      def find(...)
+        reverse_each.find(...)
+      end
+
+      def unread
+        reject(&:read?)
+      end
+    end
+    private_constant :Array
+
+    def respond!(prompt, params)
       @provider.responses.create(
         prompt,
-        role,
-        **@params.merge(params.merge(@response ? {previous_response_id: @response.id} : {}))
+        @params.merge(params.merge(@response ? {previous_response_id: @response.id} : {}))
       )
     end
 
-    def complete!(prompt, role, params)
+    def complete!(prompt, params)
       @provider.complete(
         prompt,
-        role,
-        **@params.merge(params.merge(messages:))
+        @params.merge(params.merge(messages:))
       )
     end
   end

data/lib/llm/core_ext/ostruct.rb

@@ -8,17 +8,19 @@ class OpenStruct
     #   obj = OpenStruct.from_hash(person: {name: 'John'})
     #   obj.person.name  # => 'John'
     #   obj.person.class # => OpenStruct
-    # @param [Hash] hash_obj
+    # @param [Hash, Array] obj
     #   A Hash object
     # @return [OpenStruct]
-    #   An OpenStruct object initialized by visiting `hash_obj` with
-    #   recursion
-    def from_hash(hash_obj)
-      visited_object = {}
-      hash_obj.each do |key, value|
-        visited_object[key] = walk(value)
+    #   An OpenStruct 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] = walk(_2) }
+        new(visited)
       end
-      new(visited_object)
     end
 
     private
@@ -34,4 +36,8 @@ class OpenStruct
     end
   end
   extend FromHash
+
+  def to_json(...)
+    to_h.to_json(...)
+  end
 end

data/lib/llm/file.rb

@@ -72,5 +72,10 @@ end
 #  The path to a file
 # @return [LLM::File]
 def LLM.File(path)
-  LLM::File.new(path)
+  case path
+  when LLM::File, LLM::Response::File
+    path
+  else
+    LLM::File.new(path)
+  end
 end

data/lib/llm/function.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+class LLM::Function
+  class Return < Struct.new(:id, :value)
+  end
+
+  ##
+  # Returns the function name
+  # @return [String]
+  attr_reader :name
+
+  ##
+  # Returns function arguments
+  # @return [Array, nil]
+  attr_accessor :arguments
+
+  ##
+  # Returns the function ID
+  # @return [String, nil]
+  attr_accessor :id
+
+  ##
+  # @param [String] name The function name
+  # @yieldparam [LLM::Function] self The function object
+  def initialize(name, &b)
+    @name = name
+    @schema = JSON::Schema.new
+    yield(self)
+  end
+
+  ##
+  # Set the function description
+  # @param [String] str The function description
+  # @return [void]
+  def description(str)
+    @description = str
+  end
+
+  ##
+  # @yieldparam [JSON::Schema] schema The schema object
+  # @return [void]
+  def params
+    @params = yield(@schema)
+  end
+
+  ##
+  # Set the function implementation
+  # @param [Proc] b The function implementation
+  # @return [void]
+  def define(&b)
+    @runner = b
+  end
+
+  ##
+  # Call the function
+  # @param [Array] args The arguments to pass to the function
+  # @return [Object] The result of the function call
+  def call
+    Return.new id, @runner.call(arguments)
+  ensure
+    @called = true
+  end
+
+  ##
+  # Returns true when a function has been called
+  # @return [Boolean]
+  def called?
+    @called
+  end
+
+  ##
+  # @return [Hash]
+  def format(provider)
+    case provider.class.to_s
+    when "LLM::Gemini"
+      {name: @name, description: @description, parameters: @params}.compact
+    when "LLM::Anthropic"
+      {name: @name, description: @description, input_schema: @params}.compact
+    else
+      {
+        type: "function", name: @name,
+        function: {name: @name, description: @description, parameters: @params}
+      }.compact
+    end
+  end
+end

data/lib/llm/message.rb

@@ -58,18 +58,70 @@ module LLM
     end
 
     ##
-    # Returns true when the message is from the LLM
+    # @return [Array<LLM::Function>]
+    def functions
+      @functions ||= tool_calls.map do |fn|
+        function = LLM.functions[fn.name].dup
+        function.tap { _1.id = fn.id }
+        function.tap { _1.arguments = fn.arguments }
+      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]
     def assistant?
       role == "assistant" || role == "model"
     end
 
+    ##
+    # Returns true when the message is a system message
+    # @return [Boolean]
+    def system?
+      role == "system"
+    end
+
+    ##
+    # Returns true when the message is a user message
+    # @return [Boolean]
+    def user?
+      role == "user"
+    end
+
+    ##
+    # @return [Boolean]
+    #  Returns true when the message requests a function call
+    def tool_call?
+      tool_calls.any?
+    end
+
     ##
     # Returns a string representation of the message
     # @return [String]
     def inspect
       "#<#{self.class.name}:0x#{object_id.to_s(16)} " \
-      "role=#{role.inspect} content=#{content.inspect}>"
+      "tool_call=#{tool_calls.any?} role=#{role.inspect} " \
+      "content=#{content.inspect}>"
+    end
+
+    private
+
+    def tool_calls
+      @tool_calls ||= OpenStruct.from_hash(@extra[:tool_calls] || [])
     end
   end
 end

data/lib/llm/provider.rb

@@ -9,7 +9,7 @@ class LLM::Provider
   require "net/http"
 
   ##
-  # @param [String] secret
+  # @param [String, nil] key
   #  The secret key for authentication
   # @param [String] host
   #  The host address of the LLM provider
@@ -17,8 +17,10 @@ class LLM::Provider
   #  The port number
   # @param [Integer] timeout
   #  The number of seconds to wait for a response
-  def initialize(secret, host:, port: 443, timeout: 60, ssl: true)
-    @secret = secret
+  # @param [Boolean] ssl
+  #  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
@@ -30,7 +32,7 @@ class LLM::Provider
   # @return [String]
   # @note The secret key is redacted in inspect for security reasons
   def inspect
-    "#<#{self.class.name}:0x#{object_id.to_s(16)} @secret=[REDACTED] @http=#{@http.inspect}>"
+    "#<#{self.class.name}:0x#{object_id.to_s(16)} @key=[REDACTED] @http=#{@http.inspect}>"
   end
 
   ##
@@ -52,26 +54,23 @@ class LLM::Provider
   # Provides an interface to the chat completions API
   # @example
   #   llm = LLM.openai(ENV["KEY"])
-  #   messages = [
-  #     {role: "system", content: "Your task is to answer all of my questions"},
-  #     {role: "system", content: "Your answers should be short and concise"},
-  #   ]
-  #   res = llm.complete("Hello. What is the answer to 5 + 2 ?", :user, messages:)
+  #   messages = [{role: "system", content: "Your task is to answer all of my questions"}]
+  #   res = llm.complete("5 + 2 ?", messages:)
   #   print "[#{res.choices[0].role}]", res.choices[0].content, "\n"
   # @param [String] prompt
   #  The input prompt to be completed
-  # @param [Symbol] role
-  #  The role of the prompt (e.g. :user, :system)
-  # @param [String] model
-  #  The model to use for the completion
-  # @param [#to_json, nil] schema
-  #  The schema that describes the expected response format
   # @param [Hash] params
-  #  Other completion parameters
+  #  The parameters to maintain throughout the conversation.
+  #  Any parameter the provider supports can be included and
+  #  not only those listed here.
+  # @option params [Symbol] :role Defaults to the provider's default role
+  # @option params [String] :model Defaults to the provider's default model
+  # @option params [#to_json, nil] :schema Defaults to nil
+  # @option params [Array<LLM::Function>, nil] :tools Defaults to nil
   # @raise [NotImplementedError]
   #  When the method is not implemented by a subclass
   # @return [LLM::Response::Completion]
-  def complete(prompt, role = :user, model: default_model, schema: nil, **params)
+  def complete(prompt, params = {})
     raise NotImplementedError
   end
 
@@ -81,15 +80,11 @@ class LLM::Provider
   #  This method creates a lazy version of a
   #  {LLM::Chat LLM::Chat} object.
   # @param prompt (see LLM::Provider#complete)
-  # @param role (see LLM::Provider#complete)
-  # @param model (see LLM::Provider#complete)
-  # @param schema (see LLM::Provider#complete)
-  # @param [Hash] params
-  #  Other completion parameters to maintain throughout a chat
-  # @raise (see LLM::Provider#complete)
+  # @param params (see LLM::Provider#complete)
   # @return [LLM::Chat]
-  def chat(prompt, role = :user, model: default_model, schema: nil, **params)
-    LLM::Chat.new(self, **params.merge(model:, schema:)).lazy.chat(prompt, role)
+  def chat(prompt, params = {})
+    role = params.delete(:role)
+    LLM::Chat.new(self, params).lazy.chat(prompt, role:)
   end
 
   ##
@@ -98,15 +93,12 @@ class LLM::Provider
   #  This method creates a non-lazy version of a
   #  {LLM::Chat LLM::Chat} object.
   # @param prompt (see LLM::Provider#complete)
-  # @param role (see LLM::Provider#complete)
-  # @param model (see LLM::Provider#complete)
-  # @param schema (see LLM::Provider#complete)
-  # @param [Hash] params
-  #  Other completion parameters to maintain throughout a chat
+  # @param params (see LLM::Provider#complete)
   # @raise (see LLM::Provider#complete)
   # @return [LLM::Chat]
-  def chat!(prompt, role = :user, model: default_model, schema: nil, **params)
-    LLM::Chat.new(self, **params.merge(model:, schema:)).chat(prompt, role)
+  def chat!(prompt, params = {})
+    role = params.delete(:role)
+    LLM::Chat.new(self, params).chat(prompt, role:)
   end
 
   ##
@@ -115,15 +107,12 @@ class LLM::Provider
   #  This method creates a lazy variant of a
   #  {LLM::Chat LLM::Chat} object.
   # @param prompt (see LLM::Provider#complete)
-  # @param role (see LLM::Provider#complete)
-  # @param model (see LLM::Provider#complete)
-  # @param schema (see LLM::Provider#complete)
-  # @param [Hash] params
-  #  Other completion parameters to maintain throughout a chat
+  # @param params (see LLM::Provider#complete)
   # @raise (see LLM::Provider#complete)
   # @return [LLM::Chat]
-  def respond(prompt, role = :user, model: default_model, schema: nil, **params)
-    LLM::Chat.new(self, **params.merge(model:, schema:)).lazy.respond(prompt, role)
+  def respond(prompt, params = {})
+    role = params.delete(:role)
+    LLM::Chat.new(self, params).lazy.respond(prompt, role:)
   end
 
   ##
@@ -132,15 +121,12 @@ class LLM::Provider
   #  This method creates a non-lazy variant of a
   #  {LLM::Chat LLM::Chat} object.
   # @param prompt (see LLM::Provider#complete)
-  # @param role (see LLM::Provider#complete)
-  # @param model (see LLM::Provider#complete)
-  # @param schema (see LLM::Provider#complete)
-  # @param [Hash] params
-  #  Other completion parameters to maintain throughout a chat
+  # @param params (see LLM::Provider#complete)
   # @raise (see LLM::Provider#complete)
   # @return [LLM::Chat]
-  def respond!(prompt, role = :user, model: default_model, schema: nil, **params)
-    LLM::Chat.new(self, **params.merge(model:, schema:)).respond(prompt, role)
+  def respond!(prompt, params = {})
+    role = params.delete(:role)
+    LLM::Chat.new(self, params).respond(prompt, role:)
   end
 
   ##