llm.rb 12.4.0 → 12.5.0

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

@@ -7,9 +7,41 @@ class LLM::Repl
   # 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
-    UNDEFINED = Object.new
+    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.
@@ -26,15 +58,15 @@ class LLM::Repl
     # @param [String] input
     # @param [String] name
     # @return [LLM::Repl::Command, nil]
-    def self.find_by(input: nil, name: nil)
-      if input
+    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
+      elsif name != UNDEFINED
         registry.find { name == _1.name }
       else
-        raise ArgumentError, "provide one of: input, name"
+        raise ArgumentError, "provide either an input or a name"
       end
     end
 
@@ -45,6 +77,8 @@ class LLM::Repl
     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
 
@@ -74,12 +108,94 @@ class LLM::Repl
       @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

data/lib/llm/repl/commands/exit.rb

@@ -16,4 +16,8 @@ class LLM::Repl
       throw(:exit)
     end
   end
+
+  class Command::Quit < Command::Exit
+    name "quit"
+  end
 end

data/lib/llm/repl/commands/help.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+class LLM::Repl
+  class Help < Command
+    name "help"
+    description "show help for a given command"
+    parameter :name, String, "The name of a command"
+
+    ##
+    # @param [String] name
+    # @return [void]
+    def call(name: nil)
+      if name.nil?
+        write("\n#{self.class.help}\n\n")
+      elsif command = LLM::Command.find_by(name:)
+        write("\n#{command.help}\n\n")
+      else
+        write "\nNo help for #{name} was found" \
+              "\nThat command doesn't exist." \
+              "\n\n"
+      end
+    end
+  end
+end

data/lib/llm/repl/input.rb

@@ -19,6 +19,7 @@ class LLM::Repl
     DOWN      = Curses::Key::DOWN
     LEFT      = Curses::Key::LEFT
     RIGHT     = Curses::Key::RIGHT
+    ESC       = 27
     ENTER     = [Curses::Key::ENTER, 10, 13]
     BACKSPACE = [Curses::Key::BACKSPACE, 127]
 
@@ -58,7 +59,9 @@ class LLM::Repl
     # @return [Symbol, nil]
     def on_char(window, char, now)
       is_paste = lambda { @last_char_at and (now - @last_char_at) < PASTE_THRESHOLD }
-      if CTRL[:D] == char
+      if ESC == char
+        @agent.cancel!
+      elsif CTRL[:D] == char
         delete
         :ctrl_d
       elsif CTRL[:A] == char

data/lib/llm/repl/stream.rb

@@ -28,14 +28,9 @@ class LLM::Repl
 
     ##
     # @param [LLM::Function] tool
-    # @param [LLM::Function::Return, nil] error
     # @return [void]
-    def on_tool_call(tool, error)
-      if error
-        @_queue.push [:status, "tool not found: #{tool.name}"]
-      else
-        @_queue.push [:status, "#{tool.name}(#{format_args(tool)})"]
-      end
+    def on_tool_call(tool)
+      @_queue.push [:status, "#{tool.name}(#{format_args(tool)})"]
     end
 
     ##
@@ -43,7 +38,7 @@ class LLM::Repl
     # @param [LLM::Function::Return] result
     # @return [void]
     def on_tool_return(_tool, result)
-      @_queue.push [:status, "Thinking"]
+      @_queue.push [:status, @repl.thinking_text]
     end
 
     ##