llm.rb 4.7.0 → 4.9.0

data/lib/llm/function/array.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+class LLM::Function
+  ##
+  # The {LLM::Function::Array} module extends the array
+  # returned by {LLM::Context#functions} with methods
+  # that can call all pending functions sequentially or
+  # concurrently. The return values can be reported back
+  # to the LLM on the next turn.
+  module Array
+    ##
+    # Calls all functions in a collection sequentially.
+    # @return [Array<LLM::Function::Return>]
+    #  Returns values to be reported back to the LLM.
+    def call
+      map(&:call)
+    end
+
+    ##
+    # Calls all functions in a collection concurrently.
+    # This method returns an {LLM::Function::ThreadGroup},
+    # {LLM::Function::TaskGroup}, or {LLM::Function::FiberGroup}
+    # that can be waited on to access the return values.
+    #
+    # @param [Symbol] strategy
+    #   Controls concurrency strategy:
+    #   - `:thread`: Use threads
+    #   - `:task`: Use async tasks (requires async gem)
+    #   - `:fiber`: Use raw fibers
+    #
+    # @return [LLM::Function::ThreadGroup, LLM::Function::TaskGroup, LLM::Function::FiberGroup]
+    def spawn(strategy)
+      case strategy
+      when :task
+        TaskGroup.new(map { |fn| fn.spawn(:task) })
+      when :thread
+        ThreadGroup.new(map { |fn| fn.spawn(:thread) })
+      when :fiber
+        FiberGroup.new(map { |fn| fn.spawn(:fiber) })
+      else
+        raise ArgumentError, "Unknown strategy: #{strategy.inspect}. Expected :thread, :task, or :fiber"
+      end
+    end
+
+    ##
+    # Calls all functions in a collection concurrently
+    # and waits for the return values.
+    #
+    # @param [Symbol] strategy
+    #   Controls concurrency strategy:
+    #   - `:thread`: Use threads
+    #   - `:task`: Use async tasks (requires async gem)
+    #   - `:fiber`: Use raw fibers
+    #
+    # @return [Array<LLM::Function::Return>]
+    #  Returns values to be reported back to the LLM.
+    def wait(strategy)
+      spawn(strategy).wait
+    end
+  end
+end

data/lib/llm/function/fiber_group.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+class LLM::Function
+  ##
+  # The {LLM::Function::FiberGroup} class wraps an array of
+  # {Fiber} objects that are running {LLM::Function} calls
+  # concurrently using raw fibers.
+  #
+  # This class provides the same interface as {LLM::Function::ThreadGroup}
+  # but uses raw fibers for lightweight concurrency without the async gem.
+  #
+  # @example
+  #   llm = LLM.openai(key: ENV["KEY"])
+  #   ctx = LLM::Context.new(llm, tools: [Weather, News, Stocks])
+  #   ctx.talk "Summarize the weather, headlines, and stock price."
+  #   grp = ctx.functions.spawn(:fiber)
+  #   # do other work while tools run...
+  #   ctx.talk(grp.wait)
+  #
+  # @see LLM::Function::Array#spawn
+  # @see LLM::Function::ThreadGroup
+  # @see LLM::Function::TaskGroup
+  class FiberGroup
+    ##
+    # Creates a new {LLM::Function::FiberGroup} from an array
+    # of fiber objects.
+    #
+    # @param [Array<Fiber>] fibers
+    #   An array of fibers, each running an {LLM::Function#spawn_fiber} call.
+    #
+    # @return [LLM::Function::FiberGroup]
+    #   Returns a new fiber group.
+    def initialize(fibers)
+      @fibers = fibers
+    end
+
+    ##
+    # Returns whether any fiber in the group is still alive.
+    #
+    # This method checks if any of the fibers in the group are
+    # still running. It can be useful for monitoring concurrent
+    # tool execution without blocking.
+    #
+    # @example
+    #   llm = LLM.openai(key: ENV["KEY"])
+    #   ctx = LLM::Context.new(llm, tools: [Weather, News, Stocks])
+    #   ctx.talk "Summarize the weather, headlines, and stock price."
+    #   grp = ctx.functions.spawn(:fiber)
+    #   while grp.alive?
+    #     puts "Tools are still running..."
+    #     sleep 1
+    #   end
+    #   ctx.talk(grp.wait)
+    #
+    # @return [Boolean]
+    #   Returns true if any fiber in the group is still alive,
+    #   false otherwise.
+    def alive?
+      @fibers.any?(&:alive?)
+    end
+
+    ##
+    # Waits for all fibers in the group to finish and returns
+    # their {LLM::Function::Return} values.
+    #
+    # This method blocks until every fiber in the group has
+    # completed. If a fiber raised an exception, the exception
+    # is caught and wrapped in an {LLM::Function::Return} with
+    # error information.
+    #
+    # @example
+    #   llm = LLM.openai(key: ENV["KEY"])
+    #   ctx = LLM::Context.new(llm, tools: [Weather, News, Stocks])
+    #   ctx.talk "Summarize the weather, headlines, and stock price."
+    #   grp = ctx.functions.spawn(:fiber)
+    #   returns = grp.wait
+    #   # returns is now an array of LLM::Function::Return objects
+    #   ctx.talk(returns)
+    #
+    # @return [Array<LLM::Function::Return>]
+    #   Returns an array of function return values, in the same
+    #   order as the original fibers.
+    def wait
+      @fibers.map do |fiber|
+        fiber.resume if fiber.alive?
+        fiber.value
+      end
+    end
+    alias_method :value, :wait
+  end
+end

data/lib/llm/function/task_group.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+class LLM::Function
+  ##
+  # The {LLM::Function::TaskGroup} class wraps an array of
+  # {Async::Task} objects that are running {LLM::Function} calls
+  # concurrently using the async gem.
+  #
+  # This class provides the same interface as {LLM::Function::ThreadGroup}
+  # but uses async tasks for lightweight concurrency with automatic
+  # scheduling and I/O management.
+  #
+  # @example
+  #   llm = LLM.openai(key: ENV["KEY"])
+  #   ctx = LLM::Context.new(llm, tools: [Weather, News, Stocks])
+  #   ctx.talk "Summarize the weather, headlines, and stock price."
+  #   grp = ctx.functions.spawn(:task)
+  #   # do other work while tools run...
+  #   ctx.talk(grp.wait)
+  #
+  # @see LLM::Function::Array#spawn
+  # @see LLM::Function::ThreadGroup
+  # @see LLM::Function::FiberGroup
+  class TaskGroup
+    ##
+    # Creates a new {LLM::Function::TaskGroup} from an array
+    # of async task objects.
+    #
+    # @param [Array<Async::Task>] tasks
+    #   An array of async tasks, each running an {LLM::Function#spawn_async} call.
+    #
+    # @return [LLM::Function::TaskGroup]
+    #   Returns a new task group.
+    def initialize(tasks)
+      @tasks = tasks
+    end
+
+    ##
+    # Returns whether any task in the group is still alive.
+    #
+    # This method checks if any of the tasks in the group are
+    # still running. It can be useful for monitoring concurrent
+    # tool execution without blocking.
+    #
+    # @example
+    #   llm = LLM.openai(key: ENV["KEY"])
+    #   ctx = LLM::Context.new(llm, tools: [Weather, News, Stocks])
+    #   ctx.talk "Summarize the weather, headlines, and stock price."
+    #   grp = ctx.functions.spawn(:task)
+    #   while grp.alive?
+    #     puts "Tools are still running..."
+    #     sleep 1
+    #   end
+    #   ctx.talk(grp.wait)
+    #
+    # @return [Boolean]
+    #   Returns true if any task in the group is still alive,
+    #   false otherwise.
+    def alive?
+      @tasks.any?(&:alive?)
+    end
+
+    ##
+    # Waits for all tasks in the group to finish and returns
+    # their {LLM::Function::Return} values.
+    #
+    # This method blocks until every task in the group has
+    # completed. If a task raised an exception, the exception
+    # is caught and wrapped in an {LLM::Function::Return} with
+    # error information.
+    #
+    # @example
+    #   llm = LLM.openai(key: ENV["KEY"])
+    #   ctx = LLM::Context.new(llm, tools: [Weather, News, Stocks])
+    #   ctx.talk "Summarize the weather, headlines, and stock price."
+    #   grp = ctx.functions.spawn(:task)
+    #   returns = grp.wait
+    #   # returns is now an array of LLM::Function::Return objects
+    #   ctx.talk(returns)
+    #
+    # @return [Array<LLM::Function::Return>]
+    #   Returns an array of function return values, in the same
+    #   order as the original tasks.
+    def wait
+      @tasks.map(&:wait)
+    end
+    alias_method :value, :wait
+  end
+end

data/lib/llm/function/thread_group.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+class LLM::Function
+  ##
+  # The {LLM::Function::ThreadGroup} class wraps an array of
+  # {Thread} objects that are running {LLM::Function} calls
+  # concurrently. It provides a single {#wait} method that
+  # collects the {LLM::Function::Return} values from those
+  # threads.
+  #
+  # This class is returned by {LLM::Function::Array#spawn}
+  # when you call `ctx.functions.spawn` on the collection
+  # returned by {LLM::Context#functions}. It is a lightweight
+  # wrapper that does not inherit from Ruby's built-in
+  # {::ThreadGroup}.
+  #
+  # @example
+  #   llm = LLM.openai(key: ENV["KEY"])
+  #   ctx = LLM::Context.new(llm, tools: [Weather, News, Stocks])
+  #   ctx.talk "Summarize the weather, headlines, and stock price."
+  #   grp = ctx.functions.spawn
+  #   # do other work while tools run...
+  #   ctx.talk(grp.wait)
+  #
+  # @see LLM::Function::Array#spawn
+  # @see LLM::Function::Array#wait
+  class ThreadGroup
+    ##
+    # Creates a new {LLM::Function::ThreadGroup} from an array
+    # of {Thread} objects.
+    #
+    # @param [Array<Thread>] threads
+    #   An array of threads, each running an {LLM::Function#spawn}
+    #   call. The thread's {Thread#value} will be an
+    #   {LLM::Function::Return}.
+    #
+    # @return [LLM::Function::ThreadGroup]
+    #   Returns a new thread group.
+    def initialize(threads)
+      @threads = threads
+    end
+
+    ##
+    # Returns whether any thread in the group is still alive.
+    #
+    # This method checks if any of the threads in the group are
+    # still running. It can be useful for monitoring concurrent
+    # tool execution without blocking.
+    #
+    # @example
+    #   llm = LLM.openai(key: ENV["KEY"])
+    #   ctx = LLM::Context.new(llm, tools: [Weather, News, Stocks])
+    #   ctx.talk "Summarize the weather, headlines, and stock price."
+    #   grp = ctx.functions.spawn
+    #   while grp.alive?
+    #     puts "Tools are still running..."
+    #     sleep 1
+    #   end
+    #   ctx.talk(grp.wait)
+    #
+    # @return [Boolean]
+    #   Returns true if any thread in the group is still alive,
+    #   false otherwise.
+    def alive?
+      @threads.any?(&:alive?)
+    end
+
+    ##
+    # Waits for all threads in the group to finish and returns
+    # their {LLM::Function::Return} values.
+    #
+    # This method blocks until every thread in the group has
+    # completed. If a thread raised an exception, the exception
+    # is caught and wrapped in an {LLM::Function::Return} with
+    # error information.
+    #
+    # @example
+    #   llm = LLM.openai(key: ENV["KEY"])
+    #   ctx = LLM::Context.new(llm, tools: [Weather, News, Stocks])
+    #   ctx.talk "Summarize the weather, headlines, and stock price."
+    #   grp = ctx.functions.spawn
+    #   returns = grp.wait
+    #   # returns is now an array of LLM::Function::Return objects
+    #   ctx.talk(returns)
+    #
+    # @return [Array<LLM::Function::Return>]
+    #   Returns an array of function return values, in the same
+    #   order as the original threads.
+    def wait
+      @threads.map(&:value)
+    end
+    alias_method :value, :wait
+  end
+end

data/lib/llm/function.rb

@@ -30,9 +30,14 @@
 #   end
 class LLM::Function
   require_relative "function/tracing"
+  require_relative "function/array"
+  require_relative "function/thread_group"
+  require_relative "function/fiber_group"
+  require_relative "function/task_group"
+
   prepend LLM::Function::Tracing
 
-  class Return < Struct.new(:id, :name, :value)
+  Return = Struct.new(:id, :name, :value) do
     ##
     # Returns a Hash representation of {LLM::Function::Return}
     # @return [Hash]
@@ -105,13 +110,15 @@ class LLM::Function
   ##
   # Set (or get) the function parameters
   # @yieldparam [LLM::Schema] schema The schema object
-  # @return [void]
+  # @return [LLM::Schema::Leaf, nil]
   def params
     if block_given?
+      params = yield(@schema)
+      params = LLM::Schema.parse(params) if Hash === params
       if @params
-        @params.merge!(yield(@schema))
+        @params.merge!(params)
       else
-        @params = yield(@schema)
+        @params = params
       end
     else
       @params
@@ -131,8 +138,51 @@ class LLM::Function
   # Call the function
   # @return [LLM::Function::Return] The result of the function call
   def call
-    runner = ((Class === @runner) ? @runner.new : @runner)
-    Return.new(id, name, runner.call(**arguments))
+    call_function
+  ensure
+    @called = true
+  end
+
+  ##
+  # Calls the function in a separate thread.
+  #
+  # This is the low-level method that powers concurrent tool execution.
+  # Prefer the collection methods on {LLM::Context#functions} for most
+  # use cases: {LLM::Function::Array#call}, {LLM::Function::Array#wait},
+  # or {LLM::Function::Array#spawn}.
+  #
+  # @example
+  #   # Normal usage (via collection)
+  #   ctx.talk(ctx.functions.wait)
+  #
+  #   # Direct usage (uncommon)
+  #   thread = tool.spawn
+  #   result = thread.value
+  #
+  # @param [Symbol] strategy
+  #   Controls concurrency strategy:
+  #   - `:thread`: Use threads
+  #   - `:task`: Use async tasks (requires async gem)
+  #   - `:fiber`: Use raw fibers
+  #
+  # @return [Thread, Async::Task, Fiber]
+  #   Returns a thread, async task, or fiber whose `#value` is an {LLM::Function::Return}.
+  def spawn(strategy)
+    case strategy
+    when :task
+      require "async" unless defined?(::Async)
+      Async { call_function }
+    when :thread
+      Thread.new { call_function }
+    when :fiber
+      Fiber.new do
+        call_function
+      ensure
+        Fiber.yield
+      end.tap(&:resume)
+    else
+      raise ArgumentError, "Unknown strategy: #{strategy.inspect}. Expected :thread, :task, or :fiber"
+    end
   ensure
     @called = true
   end
@@ -141,9 +191,9 @@ class LLM::Function
   # Returns a value that communicates that the function call was cancelled
   # @example
   #   llm = LLM.openai(key: ENV["KEY"])
-  #   ses = LLM::Session.new(llm, tools: [fn1, fn2])
-  #   ses.talk "I want to run the functions"
-  #   ses.talk ses.functions.map(&:cancel)
+  #   ctx = LLM::Context.new(llm, tools: [fn1, fn2])
+  #   ctx.talk "I want to run the functions"
+  #   ctx.talk ctx.functions.map(&:cancel)
   # @return [LLM::Function::Return]
   def cancel(reason: "function call cancelled")
     Return.new(id, name, {cancelled: true, reason:})
@@ -176,7 +226,7 @@ class LLM::Function
   # @return [Hash]
   def adapt(provider)
     case provider.class.to_s
-    when "LLM::Gemini"
+    when "LLM::Google"
       {name: @name, description: @description, parameters: @params}.compact
     when "LLM::Anthropic"
       {name: @name, description: @description, input_schema: @params}.compact
@@ -185,6 +235,8 @@ class LLM::Function
     end
   end
 
+  private
+
   def format_openai(provider)
     case provider.class.to_s
     when "LLM::OpenAI::Responses"
@@ -199,4 +251,17 @@ class LLM::Function
       }.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.
+  #
+  # @return [LLM::Function::Return]
+  #   Returns a Return object with either the function result or error information.
+  def call_function
+    runner = ((Class === @runner) ? @runner.new : @runner)
+    Return.new(id, name, runner.call(**arguments))
+  rescue => ex
+    Return.new(id, name,  {error: true, type: ex.class.name, message: ex.message})
+  end
 end

data/lib/llm/mcp/command.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+class LLM::MCP
+  ##
+  # The {LLM::MCP::Command} class manages the lifecycle of an MCP process
+  # by wrapping a system command. It provides methods to start the process,
+  # write to its stdin, read from its stdout and stderr, and wait for it
+  # to exit.
+  class Command
+    ##
+    # @return [Integer, nil]
+    #  The PID of the running command, or nil if it's not running
+    attr_reader :pid
+
+    attr_reader :stdin, :stdout, :stderr
+
+    ##
+    # @param [Array<String>] argv The command to run for the MCP process
+    # @param [Hash] env The environment variables to set for the MCP process
+    # @param [String, nil] cwd The working directory for the MCP process
+    # @return [LLM::MCP::Command] A new Command instance
+    def initialize(argv:, env: {}, cwd: nil)
+      @argv = argv
+      @env = env
+      @cwd = cwd
+      @pid = nil
+      @buffers = {}
+    end
+
+    ##
+    # Starts a command.
+    # @raise [LLM::Error]
+    #  When the command is already running
+    # @return [void]
+    def start
+      raise LLM::MCP::Error, "MCP command is already running" if alive?
+      @stdout, @stderr, @stdin = 3.times.map { Pipe.new }
+      @buffers.clear
+      @pid = Process.spawn(env.to_h, *argv, {chdir: cwd, out: stdout.w, err: stderr.w, in: stdin.r}.compact)
+      [stdin.close_reader, [stdout, stderr].each(&:close_writer)]
+    end
+
+    ##
+    # Stops the command if it's running.
+    # @return [void]
+    def stop
+      return nil unless alive?
+      [stdin.close_writer, [stdout, stderr].each(&:close_reader)]
+      Process.kill("TERM", pid)
+      @buffers.clear
+      wait
+    end
+
+    ##
+    # Returns true when command is running.
+    # @return [Boolean]
+    def alive?
+      !@pid.nil?
+    end
+
+    ##
+    # Writes to the command's stdin
+    # @param [String] message The message to write
+    # @return [void]
+    def write(message)
+      stdin.write(message)
+      stdin.write("\n")
+      stdin.flush
+    end
+
+    ##
+    # Reads from the command's IO without blocking.
+    # @param [Symbol] io
+    #  The IO stream to read from (:stdout, :stderr)
+    # @raise [LLM::Error]
+    #  When the command is not running
+    # @raise [IO::WaitReadable]
+    #  When no complete message is available to read
+    # @return [String]
+    #  The next complete line from the specified IO stream
+    def read_nonblock(io = :stdout)
+      raise LLM::MCP::Error, "MCP command is not running" unless alive?
+      io = public_send(io)
+      @buffers[io] ||= +""
+      loop do
+        if (index = @buffers[io].index("\n"))
+          return @buffers[io].slice!(0, index + 1)
+        end
+        @buffers[io] << io.read_nonblock(4096)
+      end
+    end
+
+    ##
+    # Waits for the command to exit and returns its exit status.
+    # @return [Process::Status, nil]
+    #  The exit status of the command, or nil
+    def wait
+      Process.wait(pid)
+      @pid = nil
+    rescue Errno::ECHILD
+      nil
+    end
+
+    private
+
+    attr_reader :argv, :env, :cwd
+  end
+end

data/lib/llm/mcp/error.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+class LLM::MCP
+  class Error < LLM::Error
+    attr_reader :code, :data
+
+    ##
+    # @param [Hash] response
+    #  The full response from the MCP process, including the error object
+    # @return [LLM::MCP::Error]
+    def self.from(response:)
+      error = response.fetch("error")
+      new(*error.values_at("message", "code", "data"))
+    end
+
+    ##
+    # @param [String] message
+    #  The error message
+    # @param [Integer] code
+    #  The error code
+    # @param [Object] data
+    #  Additional error data provided by the MCP process
+    def initialize(message, code = nil, data = nil)
+      super(message)
+      @code = code
+      @data = data
+    end
+  end
+
+  TimeoutError = Class.new(Error)
+end

data/lib/llm/mcp/pipe.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+class LLM::MCP
+  ##
+  # The {LLM::MCP::Pipe LLM::MCP::Pipe} class wraps a pair of IO
+  # objects created by {IO.pipe}. It is used by
+  # {LLM::MCP::Transport::Stdio LLM::MCP::Transport::Stdio} to manage
+  # the stdin, stdout, and stderr streams of an MCP process through
+  # one small interface.
+  class Pipe
+    ##
+    # @return [IO]
+    #  Returns the reader
+    attr_reader :r
+
+    ##
+    # @return [IO]
+    #  Returns the writer
+    attr_reader :w
+
+    ##
+    # Returns a new pipe.
+    # @return [LLM::MCP::Pipe]
+    def initialize
+      @r, @w = IO.pipe
+    end
+
+    ##
+    # Reads from the reader end without blocking.
+    # @raise [IO::WaitReadable]
+    #  When no data is available to read
+    # @return [String]
+    def read_nonblock(...)
+      @r.read_nonblock(...)
+    end
+
+    ##
+    # Writes to the writer.
+    # @return [Integer]
+    def write(...)
+      @w.write(...)
+    end
+
+    ##
+    # Flushes the writer.
+    # @return [void]
+    def flush
+      @w.flush
+    end
+
+    ##
+    # Returns true when both ends are closed.
+    # @return [Boolean]
+    def closed?
+      [@r, @w].all?(&:closed?)
+    end
+
+    ##
+    # Closes both ends of the pipe.
+    # @return [void]
+    def close
+      [@r, @w].each(&:close)
+    rescue IOError
+    end
+
+    ##
+    # Closes the reader.
+    # @return [void]
+    def close_reader
+      @r.close
+    rescue IOError
+    end
+
+    ##
+    # Closes the writer.
+    # @return [void]
+    def close_writer
+      @w.close
+    rescue IOError
+    end
+  end
+end