llm.rb 12.3.1 → 12.5.0

data/lib/llm/function.rb

@@ -117,7 +117,7 @@ class LLM::Function
   # @param [Hash, LLM::Object] other
   # @return [void]
   def arguments=(other)
-    @arguments = LLM::Object.from(other)
+    @arguments = other.nil? ? nil : LLM::Object.from(other)
   end
 
   ##
@@ -358,18 +358,7 @@ class LLM::Function
   ##
   # @return [Hash]
   def adapt(provider)
-    case provider.class.to_s
-    when "LLM::Google"
-      {name: @name, description: @description, parameters: @params}.compact
-    when "LLM::Anthropic"
-      {
-        name: @name,
-        description: @description,
-        input_schema: @params || {type: "object", properties: {}}
-      }.compact
-    else
-      format_openai(provider)
-    end
+    provider.adapt_function(self)
   end
 
   ##
@@ -383,28 +372,6 @@ class LLM::Function
 
   private
 
-  def format_openai(provider)
-    case provider.class.to_s
-    when "LLM::OpenAI::Responses"
-      {
-        type: "function", name: @name, description: @description,
-        parameters: (@params || {type: "object", properties: {}}).to_h.merge(additionalProperties: false), strict: false
-      }.compact
-    when "LLM::Mistral"
-      params = @params || {type: "object", properties: {}}
-      {
-        type: "function",
-        function: {name: @name, description: @description, parameters: params}
-      }.compact
-    else
-      params = @params || {type: "object", properties: {}}
-      {
-        type: "function", name: @name,
-        function: {name: @name, description: @description, parameters: params}
-      }.compact
-    end
-  end
-
   ##
   # Internal method that calls the function and returns a Return object.
   # Handles both class-based and proc-based runners, and rescues exceptions.

data/lib/llm/message.rb

@@ -120,7 +120,9 @@ module LLM
     # @return [Array<LLM::Function>]
     def functions
       @functions ||= tool_calls.filter_map do |fn|
-        function = available_tools.find { _1.name.to_s == fn["name"] } || next
+        function = available_tools.find { _1.name.to_s == fn.name } ||
+                   LLM::Function.find_by_name(fn.name) ||
+                   function_missing(fn.name)
         function = function.dup
         function.tap { _1.id = fn.id }
         function.tap { _1.arguments = fn.arguments }
@@ -222,10 +224,18 @@ module LLM
     end
 
     def available_tools
-      tools = extra.tools || response&.__tools__ || []
+      tools = extra.tools || []
+      tools = nil if tools.empty?
+      tools = tools || response&.__tools__ || []
       tools.map { _1.respond_to?(:function) ? _1.function : _1 }
     end
 
+    def function_missing(name)
+      LLM.function(name) do |fn|
+        fn.define { raise LLM::NoSuchToolError, "tool not found" }
+      end
+    end
+
     def content_items
       Array(content)
     end

data/lib/llm/provider.rb

@@ -26,7 +26,7 @@ class LLM::Provider
   #  Requires the net-http-persistent gem.
   # @param [LLM::Transport, Class, nil] transport
   #  Optional override with any {LLM::Transport} instance or subclass.
-  def initialize(key:, host:, port: 443, timeout: 180, ssl: true, base_path: "", persistent: false, transport: nil)
+  def initialize(key:, host:, port: 443, timeout: 900, ssl: true, base_path: "", persistent: false, transport: nil)
     @key = key
     @host = host
     @port = port
@@ -349,6 +349,16 @@ class LLM::Provider
     @key != nil && @key.to_s.strip.size > 0
   end
 
+  ##
+  # Adapt a {LLM::Function} to the provider-specific tool schema.
+  # @abstract
+  # @param [LLM::Function] fn
+  # @raise [NotImplementedError]
+  # @return [Hash]
+  def adapt_function(fn)
+    raise NotImplementedError
+  end
+
   private
 
   def path(suffix, base_path: true)

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

@@ -10,15 +10,11 @@ class LLM::Anthropic
     attr_reader :body
 
     ##
-    # @param [#<<, LLM::Stream] stream
-    #  A stream sink that implements {#<<} or the {LLM::Stream} interface
+    # @param [LLM::Stream] stream
     # @return [LLM::Anthropic::StreamParser]
     def initialize(stream)
       @body = {"role" => "assistant", "content" => []}
       @stream = stream
-      @can_emit_content = stream.respond_to?(:on_content)
-      @can_emit_tool_call = stream.respond_to?(:on_tool_call)
-      @can_push_content = stream.respond_to?(:<<)
     end
 
     ##
@@ -91,17 +87,12 @@ class LLM::Anthropic
     end
 
     def emit_content(value)
-      if @can_emit_content
-        @stream.on_content(value)
-      elsif @can_push_content
-        @stream << value
-      end
+      @stream.on_content(value)
     end
 
     def emit_tool(tool)
-      return unless @can_emit_tool_call
       function, error = resolve_tool(tool)
-      @stream.on_tool_call(function, error)
+      error ? @stream.queue << error : @stream.on_tool_call(function)
     end
 
     def resolve_tool(tool)

data/lib/llm/providers/anthropic.rb

@@ -81,6 +81,17 @@ module LLM
       "assistant"
     end
 
+    ##
+    # @param [LLM::Function] fn
+    # @return [Hash]
+    def adapt_function(fn)
+      {
+        name: fn.name,
+        description: fn.description,
+        input_schema: fn.params || {type: "object", properties: {}}
+      }.compact
+    end
+
     ##
     # Anthropic expects tool results to be sent as user messages
     # containing `tool_result` content blocks rather than a distinct

data/lib/llm/providers/bedrock/stream_parser.rb

@@ -24,15 +24,11 @@ class LLM::Bedrock
     attr_reader :body
 
     ##
-    # @param [#<<, LLM::Stream] stream
+    # @param [LLM::Stream] stream
     def initialize(stream)
       @body = {"output" => {"message" => {"role" => "assistant", "content" => []}}}
       @stream = stream
       @text_markers = {}
-      @can_emit_content = stream.respond_to?(:on_content)
-      @can_emit_reasoning_content = stream.respond_to?(:on_reasoning_content)
-      @can_emit_tool_call = stream.respond_to?(:on_tool_call)
-      @can_push_content = stream.respond_to?(:<<)
     end
 
     ##
@@ -165,21 +161,16 @@ class LLM::Bedrock
     end
 
     def emit_content(value)
-      if @can_emit_content
-        @stream.on_content(value)
-      elsif @can_push_content
-        @stream << value
-      end
+      @stream.on_content(value)
     end
 
     def emit_reasoning_content(value)
-      @stream.on_reasoning_content(value) if @can_emit_reasoning_content
+      @stream.on_reasoning_content(value)
     end
 
     def emit_tool(tool)
-      return unless @can_emit_tool_call
       function, error = resolve_tool(tool)
-      @stream.on_tool_call(function, error)
+      error ? @stream.queue << error : @stream.on_tool_call(function)
     end
 
     def resolve_tool(tool)

data/lib/llm/providers/google/stream_parser.rb

@@ -10,16 +10,12 @@ class LLM::Google
     attr_reader :body
 
     ##
-    # @param [#<<, LLM::Stream] stream
-    #  A stream sink that implements {#<<} or the {LLM::Stream} interface
+    # @param [LLM::Stream] stream
     # @return [LLM::Google::StreamParser]
     def initialize(stream)
       @body = {"candidates" => []}
       @stream = stream
       @emits = {tools: []}
-      @can_emit_content = stream.respond_to?(:on_content)
-      @can_emit_tool_call = stream.respond_to?(:on_tool_call)
-      @can_push_content = stream.respond_to?(:<<)
     end
 
     ##
@@ -129,21 +125,16 @@ class LLM::Google
     end
 
     def emit_content(value)
-      if @can_emit_content
-        @stream.on_content(value)
-      elsif @can_push_content
-        @stream << value
-      end
+      @stream.on_content(value)
     end
 
     def emit_tool(pindex, cindex, part)
-      return unless @can_emit_tool_call
       return unless complete_tool?(part)
       key = [cindex, pindex]
       return if @emits[:tools].include?(key)
       function, error = resolve_tool(part, cindex, pindex)
       @emits[:tools] << key
-      @stream.on_tool_call(function, error)
+      error ? @stream.queue << error : @stream.on_tool_call(function)
     end
 
     def complete_tool?(part)

data/lib/llm/providers/google.rb

@@ -175,6 +175,13 @@ module LLM
       "model"
     end
 
+    ##
+    # @param [LLM::Function] fn
+    # @return [Hash]
+    def adapt_function(fn)
+      {name: fn.name, description: fn.description, parameters: fn.params}.compact
+    end
+
     private
 
     def headers

data/lib/llm/providers/mistral.rb

@@ -119,6 +119,17 @@ module LLM
       "mistral-large-latest"
     end
 
+    ##
+    # @param [LLM::Function] fn
+    # @return [Hash]
+    def adapt_function(fn)
+      params = fn.params || {type: "object", properties: {}}
+      {
+        type: "function",
+        function: {name: fn.name, description: fn.description, parameters: params}
+      }.compact
+    end
+
     private
 
     ##

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

@@ -10,11 +10,11 @@ class LLM::Ollama
     attr_reader :body
 
     ##
-    # @return [LLM::OpenAI::Chunk]
+    # @param [LLM::Stream] stream
+    # @return [LLM::Ollama::StreamParser]
     def initialize(stream)
       @body = {}
       @stream = stream
-      @can_push_content = stream.respond_to?(:<<)
     end
 
     ##
@@ -37,10 +37,10 @@ class LLM::Ollama
         if key == "message"
           if @body[key]
             @body[key]["content"] << value["content"]
-            @stream << value["content"] if @can_push_content
+            @stream.on_content(value["content"])
           else
             @body[key] = value
-            @stream << value["content"] if @can_push_content
+            @stream.on_content(value["content"])
           end
         else
           @body[key] = value

data/lib/llm/providers/ollama.rb

@@ -98,6 +98,17 @@ module LLM
       "qwen3:latest"
     end
 
+    ##
+    # @param [LLM::Function] fn
+    # @return [Hash]
+    def adapt_function(fn)
+      params = fn.params || {type: "object", properties: {}}
+      {
+        type: "function", name: fn.name,
+        function: {name: fn.name, description: fn.description, parameters: params}
+      }.compact
+    end
+
     private
 
     def headers

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

@@ -12,17 +12,12 @@ class LLM::OpenAI
     attr_reader :body
 
     ##
-    # @param [#<<, LLM::Stream] stream
-    #  A stream sink that implements {#<<} or the {LLM::Stream} interface
+    # @param [LLM::Stream] stream
     # @return [LLM::OpenAI::Responses::StreamParser]
     def initialize(stream)
       @body = {"output" => []}
       @stream = stream
       @emits = {tools: {}}
-      @can_emit_content = stream.respond_to?(:on_content)
-      @can_emit_reasoning_content = stream.respond_to?(:on_reasoning_content)
-      @can_emit_tool_call = stream.respond_to?(:on_tool_call)
-      @can_push_content = stream.respond_to?(:<<)
       @cached_output_index = nil
       @cached_output_item = nil
       @cached_content_index = nil
@@ -240,26 +235,21 @@ class LLM::OpenAI
     # @group Emitters
 
     def emit_content(value)
-      if @can_emit_content
-        @stream.on_content(value)
-      elsif @can_push_content
-        @stream << value
-      end
+      @stream.on_content(value)
     end
 
     def emit_reasoning_content(value)
-      @stream.on_reasoning_content(value) if @can_emit_reasoning_content
+      @stream.on_reasoning_content(value)
     end
 
     def emit_tool(index, tool)
-      return unless @can_emit_tool_call
       return if @emits[:tools][index]
       return unless tool["call_id"] && tool["name"]
       arguments = parse_arguments(tool["arguments"])
       return unless arguments
       function, error = resolve_tool(tool, arguments)
       @emits[:tools][index] = true
-      @stream.on_tool_call(function, error)
+      error ? @stream.queue << error : @stream.on_tool_call(function)
     end
 
     ##

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

@@ -86,6 +86,16 @@ class LLM::OpenAI
       res
     end
 
+    ##
+    # @param [LLM::Function] fn
+    # @return [Hash]
+    def adapt_function(fn)
+      {
+        type: "function", name: fn.name, description: fn.description,
+        parameters: (fn.params || {type: "object", properties: {}}).to_h.merge(additionalProperties: false), strict: false
+      }.compact
+    end
+
     private
 
     [:path, :headers, :execute, :transport, :resolve_tools].each do |m|

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

@@ -12,15 +12,12 @@ class LLM::OpenAI
     attr_reader :body
 
     ##
-    # @return [LLM::OpenAI::Chunk]
+    # @param [LLM::Stream] stream
+    # @return [LLM::OpenAI::StreamParser]
     def initialize(stream)
       @body = {}
       @stream = stream
       @emits = {tools: {}}
-      @can_emit_content = stream.respond_to?(:on_content)
-      @can_emit_reasoning_content = stream.respond_to?(:on_reasoning_content)
-      @can_emit_tool_call = stream.respond_to?(:on_tool_call)
-      @can_push_content = stream.respond_to?(:<<)
     end
 
     ##
@@ -157,21 +154,14 @@ class LLM::OpenAI
     end
 
     def emit_content(value)
-      if @can_emit_content
-        @stream.on_content(value)
-      elsif @can_push_content
-        @stream << value
-      end
+      @stream.on_content(value)
     end
 
     def emit_reasoning_content(value)
-      if @can_emit_reasoning_content
-        @stream.on_reasoning_content(value)
-      end
+      @stream.on_reasoning_content(value)
     end
 
     def emit_tool(tool, tindex)
-      return unless @can_emit_tool_call
       return if @emits[:tools][tindex]
       function = tool["function"]
       return unless function && tool["id"] && function["name"]
@@ -180,7 +170,7 @@ class LLM::OpenAI
       return unless arguments
       function, error = resolve_tool(tool, function, arguments)
       @emits[:tools][tindex] = true
-      @stream.on_tool_call(function, error)
+      error ? @stream.queue << error : @stream.on_tool_call(function)
     end
 
     def resolve_tool(tool, function, arguments)

data/lib/llm/providers/openai.rb

@@ -152,6 +152,17 @@ module LLM
       "gpt-5.4-mini"
     end
 
+    ##
+    # @param [LLM::Function] fn
+    # @return [Hash]
+    def adapt_function(fn)
+      params = fn.params || {type: "object", properties: {}}
+      {
+        type: "function", name: fn.name,
+        function: {name: fn.name, description: fn.description, parameters: params}
+      }.compact
+    end
+
     ##
     # @note
     #  This method includes certain tools that require configuration

data/lib/llm/repl/command.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+class LLM::Repl
+  ##
+  # The {LLM::Repl::Command LLM::Repl::Command} class is the superclass
+  # of all read-eval-print loop commands. A command has a name, and a
+  # description. This basic version does not implement parameters. A
+  # command is accessible via the `/` prefix: eg `/exit`.
+  class Command
+    UNDEFINED = Object.new
+    SINGLETON = self
+    private_constant :UNDEFINED, :SINGLETON
+
+    ##
+    # @api private
+    Parameter = Struct.new(:name, :type, :description, :options, :index, :value) do
+      ##
+      # @return [Boolean]
+      def required?
+        options[:required] == true
+      end
+
+      ##
+      # Mark the parameter as required
+      # @return [void]
+      def required!
+        options[:required] = true
+      end
+
+      ##
+      # @return [Boolean]
+      def optional?
+        !required?
+      end
+
+      ##
+      # Assign a parameter value - with type checks
+      # @param [String] other
+      # @return [void]
+      def value=(other)
+        raise TypeError, "#{other.class} is not a #{type}" unless type === other
+        self[:value] = other
+      end
+    end
+
+    ##
+    # Find a command by a name, or by an input string.
+    # @example find by name
+    #  LLM::Repl::Command.find_by(name: "exit")
+    # @example find by input string
+    #  LLM::Repl::Command.find_by(input: "/exit")
+    # @note
+    #  The input string must be prefixed with "/"
+    #  or it won't be matched. The match is made
+    #  against the string before the first space -
+    #  so "/exit foo" will match the "exit" command
+    #  but "/exitnow" will not.
+    # @param [String] input
+    # @param [String] name
+    # @return [LLM::Repl::Command, nil]
+    def self.find_by(input: UNDEFINED, name: UNDEFINED)
+      if input != UNDEFINED
+        return nil unless input[0] == "/"
+        n, = input.split(" ")
+        registry.find { n[1..] == _1.name }
+      elsif name != UNDEFINED
+        registry.find { name == _1.name }
+      else
+        raise ArgumentError, "provide either an input or a name"
+      end
+    end
+
+    ##
+    # @param [LLM::Repl::Command] command
+    #  A new subclass
+    # @return [void]
+    def self.inherited(command)
+      LLM.lock(:inherited) do
+        registry << command
+        command.instance_variable_set(:@parameters, {})
+        command.define_singleton_method(:inherited) { |command| SINGLETON.inherited(command) }
+      end
+    end
+
+    ##
+    # @return [Array<LLM::Repl::Command]
+    def self.registry
+      @registry ||= []
+    end
+
+    ##
+    # Set or get a command name.
+    # @param [String] name
+    #  The command name.
+    # @return [String]
+    def self.name(name = UNDEFINED)
+      return @name if name == UNDEFINED
+      @name = name
+    end
+
+    ##
+    # Set or get a command description.
+    # @param [String] description
+    #  The command description.
+    # @return [String]
+    def self.description(description = UNDEFINED)
+      return @description if description == UNDEFINED
+      @description = description
+    end
+
+    ##
+    # @param [Symbol] name
+    # @param [Class] type
+    # @param [String] description
+    # @param [Hash] options
+    # @return [void]
+    def self.parameter(name, type, description, options = {})
+      @parameters[name] = Parameter.new(
+        name, type,
+        description, options,
+        @parameters.size, nil
+      )
+    end
+
+    ##
+    # @return [Hash]
+    def self.parameters
+      @parameters
+    end
+
+    ##
+    # @param [Array<Symbol>] names
+    #  One or more required names
+    # @return [void]
+    def self.required(names)
+      names.each do |name|
+        if @parameters.key?(name)
+          @parameters[name].required!
+        else
+          raise LLM::Error, "'#{name}' is not a known parameter"
+        end
+      end
+    end
+
+    ##
+    # @param [LLM::Repl] repl
+    # @return [LLM::Repl::Command]
+    def initialize(repl)
+      @repl = repl
+    end
+
+    ##
+    # Write a string to the transcript
+    # @param [String] str
+    # @return [void]
+    def write(str, who: "command(#{self.class.name}): ")
+      @repl.write(who, Curses::A_BOLD)
+      @repl.write(str)
+    end
+
+    ##
+    # Display a formatted help message for this command.
+    # Uses a single {#write} call to output the command name,
+    # description, and parameter details.
+    # @return [void]
+    def self.help
+      lines = []
+      lines << "Command: #{name}"
+      lines << "Description: #{description}"
+      unless parameters.empty?
+        lines << ""
+        lines << "Parameters:"
+        parameters.each_value do |param|
+          tag = param.required? ? "(required)" : "(optional)"
+          lines << "  #{param.name} [#{param.type}] - #{param.description} #{tag}"
+        end
+      end
+      lines.join("\n")
+    end
+
+    ##
+    # This method should be implemented by subclasses.
+    # @raise [NotImplementedError]
+    def call(...)
+      raise NotImplementedError, "#{self.class}#call is not implemented"
+    end
+
+    ##
+    # @return [Hash<Symbol, Parameter>]
+    def parameters
+      self.class.parameters
+    end
+
+    require_relative "commands/exit"
+    require_relative "commands/help"
+  end
+end
+
+##
+# Convenience constant
+LLM::Command = LLM::Repl::Command