llm.rb 0.16.3 → 0.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 696893f9ef5355ed4433b265dc7771e76aa9c96c78036a70e698615a0c4d7bdd
-  data.tar.gz: 02f48b464173823d0696ea8d2d21ab5a147cdf946f1c3287dedddc1760a93c38
+  metadata.gz: fcb896bf97c2b2a07987e7d44088244e79bf35220478dd3ac93fc349a91c5f7c
+  data.tar.gz: e33c4f4c87d72568ac94af0f4494e6a40ade164dbc894de1c772fc1bd6c92705
 SHA512:
-  metadata.gz: 15c5549e9165a854814c853c381b36d3de6409a9260acb7a4bd2adddffd08520e3ea8f3dea999b111c6bd7706d9f241eddbcd2d103122ea64482a12ca8fa6879
-  data.tar.gz: 971c404ada0cf5ac1af10ffbd4aabd8654fa11fe69beceb6ef3e3fd8ae68ed3f9426ebc4af829beff2610aded2a77224ebe2b4f3e4c3ec4e7dfd5fe21e0fb90b
+  metadata.gz: 660dee96aa651f293818492ab74efa92893cf2f39dc43dd04c84841ca13071769cabf5ee03060406295af6759ed005e76594abb0de1b6b4d00b1a0b5f0915284
+  data.tar.gz: 89166bce1fb90718b8b99e2a8b6bea1fbe3cbbeb33c7fdcb0362febc7f969caaaab7e5072514793ebc8e911d7c98ebe9f46ec0b7d29257a299e9e99fca497a15

data/README.md

@@ -155,6 +155,18 @@ res3 = llm.responses.create "message 3", previous_response_id: res2.response_id
 print res3.output_text, "\n"
 ```
 
+#### Thread Safety
+
+The llm.rb library is thread-safe and can be used in a multi-threaded
+environments but it is important to keep in mind that the
+[LLM::Provider](https://0x1eef.github.io/x/llm.rb/LLM/Provider.html)
+and
+[LLM::Bot](https://0x1eef.github.io/x/llm.rb/LLM/Bot.html)
+classes should be instantiated once per thread, and not shared
+between threads. Generally the library tries to avoid global or
+shared state but where it exists reentrant locks are used to
+ensure thread-safety.
+
 ### Conversations
 
 #### Completions
@@ -261,13 +273,22 @@ bot.messages.find(&:assistant?).content! # => {answers: [5, 10, 11]}
 
 ### Tools
 
-#### Functions
+#### Introduction
 
 All providers support a powerful feature known as tool calling, and although
 it is a little complex to understand at first, it can be powerful for building
-agents. The following example demonstrates how we can define a local function
-(which happens to be a tool), and a provider (such as OpenAI) can then detect
-when we should call the function.
+agents. There are three main interfaces to understand: [LLM::Function](https://0x1eef.github.io/x/llm.rb/LLM/Function.html),
+[LLM::Tool](https://0x1eef.github.io/x/llm.rb/LLM/Tool.html), and
+[LLM::ServerTool](https://0x1eef.github.io/x/llm.rb/LLM/ServerTool.html).
+
+
+#### LLM::Function
+
+The following example demonstrates [LLM::Function](https://0x1eef.github.io/x/llm.rb/LLM/Function.html)
+and how it can define a local function (which happens to be a tool), and how
+a provider (such as OpenAI) can then detect when we should call the function.
+Its most notable feature is that it can act as a closure and has access to
+its surrounding scope, which can be useful in some situations.
 
 The
 [LLM::Bot#functions](https://0x1eef.github.io/x/llm.rb/LLM/Bot.html#functions-instance_method)
@@ -276,6 +297,7 @@ it will only be populated if the LLM detects a function should be called. Each f
 corresponds to an element in the "tools" array. The array is emptied after a function call,
 and potentially repopulated on the next message:
 
+
 ```ruby
 #!/usr/bin/env ruby
 require "llm"
@@ -309,13 +331,61 @@ bot.chat bot.functions.map(&:call) # report return value to the LLM
 # {stderr: "", stdout: "FreeBSD"}
 ```
 
-#### Provider
+#### LLM::Tool
+
+The [LLM::Tool](https://0x1eef.github.io/x/llm.rb/LLM/Tool.html) class can be used
+to implement a [LLM::Function](https://0x1eef.github.io/x/llm.rb/LLM/Function.html)
+as a class. Under the hood, a subclass of [LLM::Tool](https://0x1eef.github.io/x/llm.rb/LLM/Tool.html)
+wraps an instance of [LLM::Function](https://0x1eef.github.io/x/llm.rb/LLM/Function.html)
+and delegates to it.
+
+The choice between [LLM::Function](https://0x1eef.github.io/x/llm.rb/LLM/Function.html)
+and [LLM::Tool](https://0x1eef.github.io/x/llm.rb/LLM/Tool.html) is often a matter of
+preference but each carry their own benefits. For example, [LLM::Function](https://0x1eef.github.io/x/llm.rb/LLM/Function.html)
+has the benefit of being a closure that has access to its surrounding context and
+sometimes that is useful:
+
+```ruby
+#!/usr/bin/env ruby
+require "llm"
+
+class System < LLM::Tool
+  name "system"
+  description "Run a shell command"
+  params { |schema| schema.object(command: schema.string.required) }
+
+  def call(command:)
+    ro, wo = IO.pipe
+    re, we = IO.pipe
+    Process.wait Process.spawn(command, out: wo, err: we)
+    [wo,we].each(&:close)
+    {stderr: re.read, stdout: ro.read}
+  end
+end
+
+bot = LLM::Bot.new(llm, tools: [System])
+bot.chat "Your task is to run shell commands via a tool.", role: :system
+
+bot.chat "What is the current date?", role: :user
+bot.chat bot.functions.map(&:call) # report return value to the LLM
+
+bot.chat "What operating system am I running? (short version please!)", role: :user
+bot.chat bot.functions.map(&:call) # report return value to the LLM
+
+##
+# {stderr: "", stdout: "Thu May  1 10:01:02 UTC 2025"}
+# {stderr: "", stdout: "FreeBSD"}
+```
+
+#### Server Tools
 
 The
 [LLM::Function](https://0x1eef.github.io/x/llm.rb/LLM/Function.html)
-class can define a local function that can be called by a provider on your behalf,
-and the
+and
 [LLM::Tool](https://0x1eef.github.io/x/llm.rb/LLM/Tool.html)
+classes can define a local function or tool that can be called by
+a provider on your behalf, and the
+[LLM::ServerTool](https://0x1eef.github.io/x/llm.rb/LLM/ServerTool.html)
 class represents a tool that is defined and implemented by a provider, and we can
 request that the provider call the tool on our behalf. That's the primary difference
 between a function implemented locally and a tool implemented by a provider. The
@@ -327,7 +397,8 @@ OpenAI provider to execute Python code on OpenAI's servers:
 require "llm"
 
 llm = LLM.openai(key: ENV["KEY"])
-res = llm.responses.create "Run: 'print(\"hello world\")'", tools: [llm.tool(:code_interpreter)]
+res = llm.responses.create "Run: 'print(\"hello world\")'",
+                            tools: [llm.server_tool(:code_interpreter)]
 print res.output_text, "\n"
 ```
 

data/lib/llm/buffer.rb

@@ -48,10 +48,16 @@ module LLM
     end
 
     ##
-    # Returns the last message in the buffer
-    # @return [LLM::Message, nil]
-    def last
-      to_a[-1]
+    # Returns the last message(s) in the buffer
+    # @param [Integer, nil] n
+    #  The number of messages to return
+    # @return [LLM::Message, Array<LLM::Message>, nil]
+    def last(n = nil)
+      if @pending.empty?
+        n.nil? ? @completed.last : @completed.last(n)
+      else
+        n.nil? ? to_a.last : to_a.last(n)
+      end
     end
 
     ##
@@ -65,19 +71,20 @@ module LLM
     alias_method :push, :<<
 
     ##
-    # @param [Integer, Range, #to_i] index
+    # @param [Integer, Range] index
     #  The message index
     # @return [LLM::Message, nil]
     #  Returns a message, or nil
     def [](index)
-      if index.respond_to?(:to_i)
-        @completed[index.to_i] || to_a[index.to_i]
-      elsif Range === index
-        slice = @completed[index]
-        invalidate = slice.nil? || slice.size < index.size
-        invalidate ? to_a[index] : slice
+      if @pending.empty?
+        if Range === index
+          slice = @completed[index]
+          (slice.nil? || slice.size < index.size) ? to_a[index] : slice
+        else
+          @completed[index]
+        end
       else
-        raise TypeError, "index must be an Integer or Range"
+        to_a[index]
       end
     end
 

data/lib/llm/client.rb

@@ -9,7 +9,7 @@ module LLM
     ##
     # @api private
     def persistent_client
-      mutex.synchronize do
+      LLM.lock(:clients) do
         if clients[client_id]
           clients[client_id]
         else

data/lib/llm/function.rb

@@ -6,6 +6,7 @@
 #
 # @example example #1
 #   LLM.function(:system) do |fn|
+#     fn.name "system"
 #     fn.description "Runs system commands"
 #     fn.params do |schema|
 #       schema.object(command: schema.string.required)
@@ -16,18 +17,16 @@
 #   end
 #
 # @example example #2
-#   class System
-#     def call(command:)
-#       {success: Kernel.system(command)}
+#   class System < LLM::Tool
+#     name "system"
+#     description "Runs system commands"
+#     params do |schema|
+#       schema.object(command: schema.string.required)
 #     end
-#   end
 #
-#   LLM.function(:system) do |fn|
-#     fn.description "Runs system commands"
-#     fn.params do |schema|
-#       schema.object(command: schema.string.required)
+#     def call(command:)
+#       {success: Kernel.system(command)}
 #     end
-#     fn.register(System)
 #   end
 class LLM::Function
   class Return < Struct.new(:id, :name, :value)
@@ -38,11 +37,6 @@ class LLM::Function
   # @return [String, nil]
   attr_accessor :id
 
-  ##
-  # Returns the function name
-  # @return [String]
-  attr_reader :name
-
   ##
   # Returns function arguments
   # @return [Array, nil]
@@ -56,11 +50,23 @@ class LLM::Function
     @schema = LLM::Schema.new
     @called = false
     @cancelled = false
-    yield(self)
+    yield(self) if block_given?
+  end
+
+  ##
+  # Set (or get) the function name
+  # @param [String] name The function name
+  # @return [void]
+  def name(name = nil)
+    if name
+      @name = name.to_s
+    else
+      @name
+    end
   end
 
   ##
-  # Set the function description
+  # Set (or get) the function description
   # @param [String] desc The function description
   # @return [void]
   def description(desc = nil)
@@ -72,10 +78,15 @@ class LLM::Function
   end
 
   ##
+  # Set (or get) the function parameters
   # @yieldparam [LLM::Schema] schema The schema object
   # @return [void]
   def params
-    @params = yield(@schema)
+    if block_given?
+      @params = yield(@schema)
+    else
+      @params
+    end
   end
 
   ##

data/lib/llm/message.rb

@@ -61,7 +61,7 @@ module LLM
     # @return [Array<LLM::Function>]
     def functions
       @functions ||= tool_calls.map do |fn|
-        function = LLM.functions[fn.name].dup
+        function = tools.find { _1.name.to_s == fn["name"] }.dup
         function.tap { _1.id = fn.id }
         function.tap { _1.arguments = fn.arguments }
       end
@@ -170,5 +170,9 @@ module LLM
     def tool_calls
       @tool_calls ||= LLM::Object.from_hash(@extra[:tool_calls] || [])
     end
+
+    def tools
+      response&.__tools__ || []
+    end
   end
 end

data/lib/llm/provider.rb

@@ -11,16 +11,11 @@ class LLM::Provider
   include LLM::Client
 
   @@clients = {}
-  @@mutex = Mutex.new
 
   ##
   # @api private
   def self.clients = @@clients
 
-  ##
-  # @api private
-  def self.mutex = @@mutex
-
   ##
   # @param [String, nil] key
   #  The secret key for authentication
@@ -238,11 +233,11 @@ class LLM::Provider
 
   ##
   # @note
-  #  This method might be outdated, and the {LLM::Provider#tool LLM::Provider#tool}
+  #  This method might be outdated, and the {LLM::Provider#server_tool LLM::Provider#server_tool}
   #  method can be used if a tool is not found here.
   # Returns all known tools provided by a provider.
-  # @return [String => LLM::Tool]
-  def tools
+  # @return [String => LLM::ServerTool]
+  def server_tools
     {}
   end
 
@@ -253,14 +248,14 @@ class LLM::Provider
   # Returns a tool provided by a provider.
   # @example
   #   llm   = LLM.openai(key: ENV["KEY"])
-  #   tools = [llm.tool(:web_search)]
+  #   tools = [llm.server_tool(:web_search)]
   #   res   = llm.responses.create("Summarize today's news", tools:)
   #   print res.output_text, "\n"
   # @param [String, Symbol] name The name of the tool
   # @param [Hash] options Configuration options for the tool
-  # @return [LLM::Tool]
-  def tool(name, options = {})
-    LLM::Tool.new(name, options, self)
+  # @return [LLM::ServerTool]
+  def server_tool(name, options = {})
+    LLM::ServerTool.new(name, options, self)
   end
 
   ##
@@ -369,4 +364,23 @@ class LLM::Provider
     req.body_stream = io
     req["transfer-encoding"] = "chunked" unless req["content-length"]
   end
+
+  ##
+  # Resolves tools to their function representations
+  # @param [Array<LLM::Function, LLM::Tool>] tools
+  #  The tools to map
+  # @raise [TypeError]
+  #  When a tool is not recognized
+  # @return [Array<LLM::Function>]
+  def resolve_tools(tools)
+    (tools || []).map do |tool|
+      if tool.respond_to?(:function)
+        tool.function
+      elsif [LLM::Function, LLM::ServerTool, Hash].any? { _1 === tool }
+        tool
+      else
+        raise TypeError, "#{tool.class} given as a tool but it is not recognized"
+      end
+    end
+  end
 end

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

@@ -21,9 +21,8 @@ class LLM::Anthropic
     ##
     # @param [Hash] params
     # @return [Hash]
-    def format_tools(params)
-      return {} unless params and params[:tools]&.any?
-      tools = params[:tools]
+    def format_tools(tools)
+      return {} unless tools&.any?
       {tools: tools.map { _1.respond_to?(:format) ? _1.format(self) : _1 }}
     end
   end

data/lib/llm/providers/anthropic.rb

@@ -43,7 +43,8 @@ module LLM
     # @return (see LLM::Provider#complete)
     def complete(prompt, params = {})
       params = {role: :user, model: default_model, max_tokens: 1024}.merge!(params)
-      params = [params, format_tools(params)].inject({}, &:merge!).compact
+      tools  = resolve_tools(params.delete(:tools))
+      params = [params, format_tools(tools)].inject({}, &:merge!).compact
       role, stream = params.delete(:role), params.delete(:stream)
       params[:stream] = true if stream.respond_to?(:<<) || stream == true
       req = Net::HTTP::Post.new("/v1/messages", headers)
@@ -51,7 +52,9 @@ module LLM
       body = JSON.dump({messages: [format(messages)].flatten}.merge!(params))
       set_body_stream(req, StringIO.new(body))
       res = execute(request: req, stream:)
-      LLM::Response.new(res).extend(LLM::Anthropic::Response::Completion)
+      LLM::Response.new(res)
+        .extend(LLM::Anthropic::Response::Completion)
+        .extend(Module.new { define_method(:__tools__) { tools } })
     end
 
     ##
@@ -88,14 +91,14 @@ module LLM
     # @note
     #  This method includes certain tools that require configuration
     #  through a set of options that are easier to set through the
-    #  {LLM::Provider#tool LLM::Provider#tool} method.
+    #  {LLM::Provider#server_tool LLM::Provider#server_tool} method.
     # @see https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/web-search-tool Anthropic docs
-    # @return (see LLM::Provider#tools)
-    def tools
+    # @return (see LLM::Provider#server_tools)
+    def server_tools
       {
-        bash: tool(:bash, type: "bash_20250124"),
-        web_search: tool(:web_search, type: "web_search_20250305", max_uses: 5),
-        text_editor: tool(:str_replace_based_edit_tool, type: "text_editor_20250728", max_characters: 10_000)
+        bash: server_tool(:bash, type: "bash_20250124"),
+        web_search: server_tool(:web_search, type: "web_search_20250305", max_uses: 5),
+        text_editor: server_tool(:str_replace_based_edit_tool, type: "text_editor_20250728", max_characters: 10_000)
       }
     end
 
@@ -109,7 +112,7 @@ module LLM
     # @param query [String] The search query.
     # @return [LLM::Response] The response from the LLM provider.
     def web_search(query:)
-      complete(query, tools: [tools[:web_search]])
+      complete(query, tools: [server_tools[:web_search]])
         .extend(LLM::Anthropic::Response::WebSearch)
     end
 

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

@@ -20,8 +20,7 @@ class LLM::DeepSeek
     ##
     # @param [Hash] params
     # @return [Hash]
-    def format_tools(params)
-      tools = params.delete(:tools)
+    def format_tools(tools)
       (tools.nil? || tools.empty?) ? {} : {tools: tools.map { _1.format(self) }}
     end
   end

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

@@ -30,10 +30,9 @@ class LLM::Gemini
     ##
     # @param [Hash] params
     # @return [Hash]
-    def format_tools(params)
-      return {} unless params and params[:tools]&.any?
-      tools = params.delete(:tools)
-      platform, functions = [tools.grep(LLM::Tool), tools.grep(LLM::Function)]
+    def format_tools(tools)
+      return {} unless tools&.any?
+      platform, functions = [tools.grep(LLM::ServerTool), tools.grep(LLM::Function)]
       {tools: [*platform, {functionDeclarations: functions.map { _1.format(self) }}]}
     end
   end

data/lib/llm/providers/gemini.rb

@@ -67,7 +67,8 @@ module LLM
     # @return [LLM::Response]
     def complete(prompt, params = {})
       params = {role: :user, model: default_model}.merge!(params)
-      params = [params, format_schema(params), format_tools(params)].inject({}, &:merge!).compact
+      tools  = resolve_tools(params.delete(:tools))
+      params = [params, format_schema(params), format_tools(tools)].inject({}, &:merge!).compact
       role, model, stream = [:role, :model, :stream].map { params.delete(_1) }
       action = stream ? "streamGenerateContent?key=#{@key}&alt=sse" : "generateContent?key=#{@key}"
       model.respond_to?(:id) ? model.id : model
@@ -77,7 +78,9 @@ module LLM
       body = JSON.dump({contents: format(messages)}.merge!(params))
       set_body_stream(req, StringIO.new(body))
       res = execute(request: req, stream:)
-      LLM::Response.new(res).extend(LLM::Gemini::Response::Completion)
+      LLM::Response.new(res)
+        .extend(LLM::Gemini::Response::Completion)
+        .extend(Module.new { define_method(:__tools__) { tools } })
     end
 
     ##
@@ -130,14 +133,14 @@ module LLM
     # @note
     #  This method includes certain tools that require configuration
     #  through a set of options that are easier to set through the
-    #  {LLM::Provider#tool LLM::Provider#tool} method.
+    #  {LLM::Provider#server_tool LLM::Provider#server_tool} method.
     # @see https://ai.google.dev/gemini-api/docs/google-search Gemini docs
-    # @return (see LLM::Provider#tools)
-    def tools
+    # @return (see LLM::Provider#server_tools)
+    def server_tools
       {
-        google_search: tool(:google_search),
-        code_execution: tool(:code_execution),
-        url_context: tool(:url_context)
+        google_search: server_tool(:google_search),
+        code_execution: server_tool(:code_execution),
+        url_context: server_tool(:url_context)
       }
     end
 
@@ -147,7 +150,7 @@ module LLM
     # @param query [String] The search query.
     # @return [LLM::Response] The response from the LLM provider.
     def web_search(query:)
-      complete(query, tools: [tools[:google_search]])
+      complete(query, tools: [server_tools[:google_search]])
         .extend(LLM::Gemini::Response::WebSearch)
     end
 

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

@@ -21,9 +21,8 @@ class LLM::Ollama
     ##
     # @param [Hash] params
     # @return [Hash]
-    def format_tools(params)
-      return {} unless params and params[:tools]&.any?
-      tools = params[:tools]
+    def format_tools(tools)
+      return {} unless tools&.any?
       {tools: tools.map { _1.format(self) }}
     end
   end

data/lib/llm/providers/ollama.rb

@@ -60,7 +60,8 @@ module LLM
     # @return [LLM::Response]
     def complete(prompt, params = {})
       params = {role: :user, model: default_model, stream: true}.merge!(params)
-      params = [params, {format: params[:schema]}, format_tools(params)].inject({}, &:merge!).compact
+      tools  = resolve_tools(params.delete(:tools))
+      params = [params, {format: params[:schema]}, format_tools(tools)].inject({}, &:merge!).compact
       role, stream = params.delete(:role), params.delete(:stream)
       params[:stream] = true if stream.respond_to?(:<<) || stream == true
       req = Net::HTTP::Post.new("/api/chat", headers)
@@ -68,7 +69,9 @@ module LLM
       body = JSON.dump({messages: [format(messages)].flatten}.merge!(params))
       set_body_stream(req, StringIO.new(body))
       res = execute(request: req, stream:)
-      LLM::Response.new(res).extend(LLM::Ollama::Response::Completion)
+      LLM::Response.new(res)
+        .extend(LLM::Ollama::Response::Completion)
+        .extend(Module.new { define_method(:__tools__) { tools } })
     end
 
     ##

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

@@ -43,8 +43,7 @@ class LLM::OpenAI
     ##
     # @param [Hash] params
     # @return [Hash]
-    def format_tools(params)
-      tools = params.delete(:tools)
+    def format_tools(tools)
       if tools.nil? || tools.empty?
         {}
       else

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

@@ -37,7 +37,8 @@ class LLM::OpenAI
     # @return [LLM::Response]
     def create(prompt, params = {})
       params = {role: :user, model: @provider.default_model}.merge!(params)
-      params = [params, format_schema(params), format_tools(params)].inject({}, &:merge!).compact
+      tools  = resolve_tools(params.delete(:tools))
+      params = [params, format_schema(params), format_tools(tools)].inject({}, &:merge!).compact
       role, stream = params.delete(:role), params.delete(:stream)
       params[:stream] = true if stream.respond_to?(:<<) || stream == true
       req = Net::HTTP::Post.new("/v1/responses", headers)
@@ -45,7 +46,9 @@ class LLM::OpenAI
       body = JSON.dump({input: [format(messages, :response)].flatten}.merge!(params))
       set_body_stream(req, StringIO.new(body))
       res = execute(request: req, stream:, stream_parser:)
-      LLM::Response.new(res).extend(LLM::OpenAI::Response::Responds)
+      LLM::Response.new(res)
+        .extend(LLM::OpenAI::Response::Responds)
+        .extend(Module.new { define_method(:__tools__) { tools } })
     end
 
     ##
@@ -77,7 +80,7 @@ class LLM::OpenAI
 
     private
 
-    [:headers, :execute, :set_body_stream].each do |m|
+    [:headers, :execute, :set_body_stream, :resolve_tools].each do |m|
       define_method(m) { |*args, **kwargs, &b| @provider.send(m, *args, **kwargs, &b) }
     end
 

data/lib/llm/providers/openai.rb

@@ -65,7 +65,8 @@ module LLM
     # @return (see LLM::Provider#complete)
     def complete(prompt, params = {})
       params = {role: :user, model: default_model}.merge!(params)
-      params = [params, format_schema(params), format_tools(params)].inject({}, &:merge!).compact
+      tools  = resolve_tools(params.delete(:tools))
+      params = [params, format_schema(params), format_tools(tools)].inject({}, &:merge!).compact
       role, stream = params.delete(:role), params.delete(:stream)
       params[:stream] = true if stream.respond_to?(:<<) || stream == true
       params[:stream_options] = {include_usage: true}.merge!(params[:stream_options] || {}) if params[:stream]
@@ -74,7 +75,9 @@ module LLM
       body = JSON.dump({messages: format(messages, :complete).flatten}.merge!(params))
       set_body_stream(req, StringIO.new(body))
       res = execute(request: req, stream:)
-      LLM::Response.new(res).extend(LLM::OpenAI::Response::Completion)
+      LLM::Response.new(res)
+        .extend(LLM::OpenAI::Response::Completion)
+        .extend(Module.new { define_method(:__tools__) { tools } })
     end
 
     ##
@@ -152,15 +155,15 @@ module LLM
     # @note
     #  This method includes certain tools that require configuration
     #  through a set of options that are easier to set through the
-    #  {LLM::Provider#tool LLM::Provider#tool} method.
-    # @return (see LLM::Provider#tools)
-    def tools
+    #  {LLM::Provider#server_tool LLM::Provider#server_tool} method.
+    # @return (see LLM::Provider#server_tools)
+    def server_tools
       {
-        web_search: tool(:web_search),
-        file_search: tool(:file_search),
-        image_generation: tool(:image_generation),
-        code_interpreter: tool(:code_interpreter),
-        computer_use: tool(:computer_use)
+        web_search: server_tool(:web_search),
+        file_search: server_tool(:file_search),
+        image_generation: server_tool(:image_generation),
+        code_interpreter: server_tool(:code_interpreter),
+        computer_use: server_tool(:computer_use)
       }
     end
 
@@ -175,7 +178,7 @@ module LLM
     # @return [LLM::Response] The response from the LLM provider.
     def web_search(query:)
       responses
-        .create(query, store: false, tools: [tools[:web_search]])
+        .create(query, store: false, tools: [server_tools[:web_search]])
         .extend(LLM::OpenAI::Response::WebSearch)
     end
 

data/lib/llm/server_tool.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+##
+# The {LLM::ServerTool LLM::ServerTool} class represents a platform-native tool
+# that can be activated by an LLM provider. Unlike {LLM::Function LLM::Function},
+# these tools are pre-defined by the provider and their capabilities
+# are already known to the underlying LLM.
+#
+# @example
+#   #!/usr/bin/env ruby
+#   llm = LLM.gemini ENV["KEY"]
+#   bot = LLM::Bot.new(llm, tools: [LLM::ServerTool.new(:google_search)])
+#   bot.chat("Summarize today's news", role: :user)
+#   print bot.messages.find(&:assistant?).content, "\n"
+class LLM::ServerTool < Struct.new(:name, :options, :provider)
+  ##
+  # @return [String]
+  def to_json(...)
+    to_h.to_json(...)
+  end
+
+  ##
+  # @return [Hash]
+  def to_h
+    case provider.class.to_s
+    when "LLM::Anthropic" then options.merge("name" => name.to_s)
+    when "LLM::Gemini" then {name => options}
+    else options.merge("type" => name.to_s)
+    end
+  end
+  alias_method :to_hash, :to_h
+end

data/lib/llm/tool.rb

@@ -1,32 +1,75 @@
 # frozen_string_literal: true
 
 ##
-# The {LLM::Tool LLM::Tool} class represents a platform-native tool
-# that can be activated by an LLM provider. Unlike {LLM::Function LLM::Function},
-# these tools are pre-defined by the provider and their capabilities
-# are already known to the underlying LLM.
-#
+# The {LLM::Tool LLM::Tool} class represents a local tool
+# that can be called by an LLM. Under the hood, it is a wrapper
+# around {LLM::Function LLM::Function} but allows the definition
+# of a function (also known as a tool) as a class.
 # @example
-#   #!/usr/bin/env ruby
-#   llm = LLM.gemini ENV["KEY"]
-#   bot = LLM::Bot.new(llm, tools: [LLM.tool(:google_search)])
-#   bot.chat("Summarize today's news", role: :user)
-#   print bot.messages.find(&:assistant?).content, "\n"
-class LLM::Tool < Struct.new(:name, :options, :provider)
+#   class System < LLM::Tool
+#     name "system"
+#     description "Runs system commands"
+#     params do |schema|
+#       schema.object(command: schema.string.required)
+#     end
+#
+#     def call(command:)
+#       {success: Kernel.system(command)}
+#     end
+#   end
+class LLM::Tool
+  ##
+  # Registers the tool as a function when inherited
+  # @param [Class] klass The subclass
+  # @return [void]
+  def self.inherited(klass)
+    LLM.lock(:inherited) do
+      klass.instance_eval { @__monitor ||= Monitor.new }
+      klass.function.register(klass)
+    end
+  end
+
   ##
+  # Returns (or sets) the tool name
+  # @param [String, nil] name The tool name
   # @return [String]
-  def to_json(...)
-    to_h.to_json(...)
+  def self.name(name = nil)
+    lock do
+      function.tap { _1.name(name) }
+    end
   end
 
   ##
-  # @return [Hash]
-  def to_h
-    case provider.class.to_s
-    when "LLM::Anthropic" then options.merge("name" => name.to_s)
-    when "LLM::Gemini" then {name => options}
-    else options.merge("type" => name.to_s)
+  # Returns (or sets) the tool description
+  # @param [String, nil] desc The tool description
+  # @return [String]
+  def self.description(desc = nil)
+    lock do
+      function.tap { _1.description(desc) }
     end
   end
-  alias_method :to_hash, :to_h
+
+  ##
+  # Returns (or sets) tool parameters
+  # @yieldparam [LLM::Schema] schema The schema object to define parameters
+  # @return [LLM::Schema]
+  def self.params(&)
+    lock do
+      function.tap { _1.params(&) }
+    end
+  end
+
+  ##
+  # @api private
+  def self.function
+    lock do
+      @function ||= LLM::Function.new(self)
+    end
+  end
+
+  ##
+  # @api private
+  def self.lock(&)
+    @__monitor.synchronize(&)
+  end
 end

data/lib/llm/version.rb

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

data/lib/llm.rb

@@ -19,8 +19,11 @@ module LLM
   require_relative "llm/eventstream"
   require_relative "llm/eventhandler"
   require_relative "llm/tool"
+  require_relative "llm/server_tool"
 
-  @mutex = Mutex.new
+  ##
+  # Thread-safe monitors for different contexts
+  @monitors = { require: Monitor.new, clients: Monitor.new, inherited: Monitor.new }
 
   module_function
 
@@ -28,7 +31,7 @@ module LLM
   # @param (see LLM::Provider#initialize)
   # @return (see LLM::Anthropic#initialize)
   def anthropic(**)
-    @mutex.synchronize { require_relative "llm/providers/anthropic" unless defined?(LLM::Anthropic) }
+    lock(:require) { require_relative "llm/providers/anthropic" unless defined?(LLM::Anthropic) }
     LLM::Anthropic.new(**)
   end
 
@@ -36,7 +39,7 @@ module LLM
   # @param (see LLM::Provider#initialize)
   # @return (see LLM::Gemini#initialize)
   def gemini(**)
-    @mutex.synchronize { require_relative "llm/providers/gemini" unless defined?(LLM::Gemini) }
+    lock(:require) { require_relative "llm/providers/gemini" unless defined?(LLM::Gemini) }
     LLM::Gemini.new(**)
   end
 
@@ -44,7 +47,7 @@ module LLM
   # @param key (see LLM::Provider#initialize)
   # @return (see LLM::Ollama#initialize)
   def ollama(key: nil, **)
-    @mutex.synchronize { require_relative "llm/providers/ollama" unless defined?(LLM::Ollama) }
+    lock(:require) { require_relative "llm/providers/ollama" unless defined?(LLM::Ollama) }
     LLM::Ollama.new(key:, **)
   end
 
@@ -52,7 +55,7 @@ module LLM
   # @param key (see LLM::Provider#initialize)
   # @return (see LLM::LlamaCpp#initialize)
   def llamacpp(key: nil, **)
-    @mutex.synchronize { require_relative "llm/providers/llamacpp" unless defined?(LLM::LlamaCpp) }
+    lock(:require) { require_relative "llm/providers/llamacpp" unless defined?(LLM::LlamaCpp) }
     LLM::LlamaCpp.new(key:, **)
   end
 
@@ -60,7 +63,7 @@ module LLM
   # @param key (see LLM::Provider#initialize)
   # @return (see LLM::DeepSeek#initialize)
   def deepseek(**)
-    @mutex.synchronize { require_relative "llm/providers/deepseek" unless defined?(LLM::DeepSeek) }
+    lock(:require) { require_relative "llm/providers/deepseek" unless defined?(LLM::DeepSeek) }
     LLM::DeepSeek.new(**)
   end
 
@@ -68,7 +71,7 @@ module LLM
   # @param key (see LLM::Provider#initialize)
   # @return (see LLM::OpenAI#initialize)
   def openai(**)
-    @mutex.synchronize { require_relative "llm/providers/openai" unless defined?(LLM::OpenAI) }
+    lock(:require) { require_relative "llm/providers/openai" unless defined?(LLM::OpenAI) }
     LLM::OpenAI.new(**)
   end
 
@@ -77,12 +80,12 @@ module LLM
   # @param host (see LLM::XAI#initialize)
   # @return (see LLM::XAI#initialize)
   def xai(**)
-    @mutex.synchronize { require_relative "llm/providers/xai" unless defined?(LLM::XAI) }
+    lock(:require) { require_relative "llm/providers/xai" unless defined?(LLM::XAI) }
     LLM::XAI.new(**)
   end
 
   ##
-  # Define or get a function
+  # Define a function
   # @example
   #   LLM.function(:system) do |fn|
   #     fn.description "Run system command"
@@ -93,21 +96,17 @@ module LLM
   #       system(command)
   #     end
   #   end
-  # @param [Symbol] name The name of the function
+  # @param [Symbol] key The function name / key
   # @param [Proc] b The block to define the function
   # @return [LLM::Function] The function object
-  def function(name, &b)
-    if block_given?
-      functions[name.to_s] = LLM::Function.new(name, &b)
-    else
-      functions[name.to_s]
-    end
+  def function(key, &b)
+    LLM::Function.new(key, &b)
   end
 
   ##
-  # Returns all known functions
-  # @return [Hash<String,LLM::Function>]
-  def functions
-    @functions ||= {}
-  end
+  # Provides a thread-safe lock
+  # @param [Symbol] name The name of the lock
+  # @param [Proc] & The block to execute within the lock
+  # @return [void]
+  def lock(name, &) = @monitors[name].synchronize(&)
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: llm.rb
 version: !ruby/object:Gem::Version
-  version: 0.16.3
+  version: 0.17.0
 platform: ruby
 authors:
 - Antar Azri
@@ -275,6 +275,7 @@ files:
 - lib/llm/schema/object.rb
 - lib/llm/schema/string.rb
 - lib/llm/schema/version.rb
+- lib/llm/server_tool.rb
 - lib/llm/tool.rb
 - lib/llm/utils.rb
 - lib/llm/version.rb