llm.rb 4.8.0 → 4.10.0

data/lib/llm/bot.rb

@@ -1,265 +1,3 @@
 # frozen_string_literal: true
 
-module LLM
-  ##
-  # {LLM::Session LLM::Session} provides an object that can maintain a
-  # conversation. A conversation can use the chat completions API
-  # that all LLM providers support or the responses API that currently
-  # only OpenAI supports.
-  #
-  # @example
-  #   #!/usr/bin/env ruby
-  #   require "llm"
-  #
-  #   llm = LLM.openai(key: ENV["KEY"])
-  #   ses = LLM::Session.new(llm)
-  #
-  #   prompt = LLM::Prompt.new(llm) do
-  #     system "Be concise and show your reasoning briefly."
-  #     user "If a train goes 60 mph for 1.5 hours, how far does it travel?"
-  #     user "Now double the speed for the same time."
-  #   end
-  #
-  #   ses.talk(prompt)
-  #   ses.messages.each { |m| puts "[#{m.role}] #{m.content}" }
-  class Session
-    require_relative "session/deserializer"
-    include Deserializer
-
-    ##
-    # Returns an Enumerable for the messages in a conversation
-    # @return [LLM::Buffer<LLM::Message>]
-    attr_reader :messages
-
-    ##
-    # @param [LLM::Provider] provider
-    #  A provider
-    # @param [Hash] params
-    #  The parameters to maintain throughout the conversation.
-    #  Any parameter the provider supports can be included and
-    #  not only those listed here.
-    # @option params [String] :model Defaults to the provider's default model
-    # @option params [Array<LLM::Function>, nil] :tools Defaults to nil
-    def initialize(provider, params = {})
-      @provider = provider
-      @params = {model: provider.default_model, schema: nil}.compact.merge!(params)
-      @messages = LLM::Buffer.new(provider)
-    end
-
-    ##
-    # Maintain a conversation via the chat completions API.
-    # This method immediately sends a request to the LLM and returns the response.
-    #
-    # @param prompt (see LLM::Provider#complete)
-    # @param params The params, including optional :role (defaults to :user), :stream, :tools, :schema etc.
-    # @return [LLM::Response] Returns the LLM's response for this turn.
-    # @example
-    #   llm = LLM.openai(key: ENV["KEY"])
-    #   ses = LLM::Session.new(llm)
-    #   res = ses.talk("Hello, what is your name?")
-    #   puts res.messages[0].content
-    def talk(prompt, params = {})
-      prompt, params, messages = fetch(prompt, params)
-      params = params.merge(messages: [*@messages.to_a, *messages])
-      params = @params.merge(params)
-      res = @provider.complete(prompt, params)
-      role = params[:role] || @provider.user_role
-      role = @provider.tool_role if params[:role].nil? && [*prompt].grep(LLM::Function::Return).any?
-      @messages.concat [LLM::Message.new(role, prompt)]
-      @messages.concat messages
-      @messages.concat [res.choices[-1]]
-      res
-    end
-    alias_method :chat, :talk
-
-    ##
-    # Maintain a conversation via the responses API.
-    # This method immediately sends a request to the LLM and returns the response.
-    #
-    # @note Not all LLM providers support this API
-    # @param prompt (see LLM::Provider#complete)
-    # @param params The params, including optional :role (defaults to :user), :stream, :tools, :schema etc.
-    # @return [LLM::Response] Returns the LLM's response for this turn.
-    # @example
-    #   llm = LLM.openai(key: ENV["KEY"])
-    #   ses = LLM::Session.new(llm)
-    #   res = ses.respond("What is the capital of France?")
-    #   puts res.output_text
-    def respond(prompt, params = {})
-      prompt, params, messages = fetch(prompt, params)
-      res_id = @messages.find(&:assistant?)&.response&.response_id
-      params = params.merge(previous_response_id: res_id, input: messages).compact
-      params = @params.merge(params)
-      res = @provider.responses.create(prompt, params)
-      role = params[:role] || @provider.user_role
-      @messages.concat [LLM::Message.new(role, prompt)]
-      @messages.concat messages
-      @messages.concat [res.choices[-1]]
-      res
-    end
-
-    ##
-    # @return [String]
-    def inspect
-      "#<#{self.class.name}:0x#{object_id.to_s(16)} " \
-      "@provider=#{@provider.class}, @params=#{@params.inspect}, " \
-      "@messages=#{@messages.inspect}>"
-    end
-
-    ##
-    # Returns an array of functions that can be called
-    # @return [Array<LLM::Function>]
-    def functions
-      @messages
-        .select(&:assistant?)
-        .flat_map do |msg|
-          fns = msg.functions.select(&:pending?)
-          fns.each do |fn|
-            fn.tracer = tracer
-            fn.model  = msg.model
-          end
-        end
-    end
-
-    ##
-    # Returns token usage for the conversation
-    # @note
-    # This method returns token usage for the latest
-    # assistant message, and it returns an empty object
-    # if there are no assistant messages
-    # @return [LLM::Object]
-    def usage
-      @messages.find(&:assistant?)&.usage || LLM::Object.from({})
-    end
-
-    ##
-    # Build a role-aware prompt for a single request.
-    #
-    # Prefer this method over {#build_prompt}. The older
-    # method name is kept for backward compatibility.
-    # @example
-    #   prompt = ses.prompt do
-    #     system "Your task is to assist the user"
-    #     user "Hello, can you assist me?"
-    #   end
-    #   ses.talk(prompt)
-    # @param [Proc] b
-    #  A block that composes messages. If it takes one argument,
-    #  it receives the prompt object. Otherwise it runs in prompt context.
-    # @return [LLM::Prompt]
-    def prompt(&b)
-      LLM::Prompt.new(@provider, &b)
-    end
-    alias_method :build_prompt, :prompt
-
-    ##
-    # Recongize an object as a URL to an image
-    # @param [String] url
-    #  The URL
-    # @return [LLM::Object]
-    #  Returns a tagged object
-    def image_url(url)
-      LLM::Object.from(value: url, kind: :image_url)
-    end
-
-    ##
-    # Recongize an object as a local file
-    # @param [String] path
-    #  The path
-    # @return [LLM::Object]
-    #  Returns a tagged object
-    def local_file(path)
-      LLM::Object.from(value: LLM.File(path), kind: :local_file)
-    end
-
-    ##
-    # Reconginize an object as a remote file
-    # @param [LLM::Response] res
-    #  The response
-    # @return [LLM::Object]
-    #  Returns a tagged object
-    def remote_file(res)
-      LLM::Object.from(value: res, kind: :remote_file)
-    end
-
-    ##
-    # @return [LLM::Tracer]
-    #  Returns an LLM tracer
-    def tracer
-      @provider.tracer
-    end
-
-    ##
-    # Returns the model a Session is actively using
-    # @return [String]
-    def model
-      messages.find(&:assistant?)&.model || @params[:model]
-    end
-
-    ##
-    # @return [Hash]
-    def to_h
-      {model:, messages:}
-    end
-
-    ##
-    # @return [String]
-    def to_json(...)
-      {schema_version: 1}.merge!(to_h).to_json(...)
-    end
-
-    ##
-    # Save a session
-    # @example
-    #  llm = LLM.openai(key: ENV["KEY"])
-    #  ses = LLM::Session.new(llm)
-    #  ses.talk "Hello"
-    #  ses.save(path: "session.json")
-    # @raise [SystemCallError]
-    #  Might raise a number of SystemCallError subclasses
-    # @return [void]
-    def serialize(path:)
-      ::File.binwrite path, LLM.json.dump(self)
-    end
-    alias_method :save, :serialize
-
-    ##
-    # Restore a session
-    # @param [String, nil] path
-    #  The path to a JSON file
-    # @param [String, nil] string
-    #  A raw JSON string
-    # @raise [SystemCallError]
-    #  Might raise a number of SystemCallError subclasses
-    # @return [LLM::Session]
-    def deserialize(path: nil, string: nil)
-      payload = if path.nil? and string.nil?
-        raise ArgumentError, "a path or string is required"
-      elsif path
-        ::File.binread(path)
-      else
-        string
-      end
-      ses = LLM.json.load(payload)
-      @messages.concat [*ses["messages"]].map { deserialize_message(_1) }
-      self
-    end
-    alias_method :restore, :deserialize
-
-    private
-
-    def fetch(prompt, params)
-      return [prompt, params, []] unless LLM::Prompt === prompt
-      messages = prompt.to_a
-      prompt = messages.shift
-      params.merge!(role: prompt.role)
-      [prompt.content, params, messages]
-    end
-  end
-
-  # Backward-compatible alias
-  Bot = Session
-
-  # Scheduled for removal in v5.0
-  deprecate_constant :Bot
-end
+require_relative "context"

data/lib/llm/buffer.rb

@@ -83,6 +83,13 @@ module LLM
       "message_count=#{@messages.size}>"
     end
 
+    ##
+    # @return [Integer]
+    #  Returns the number of messages in the buffer
+    def size
+      @messages.size
+    end
+
     ##
     # Returns true when the buffer is empty
     # @return [Boolean]

data/lib/llm/{session → context}/deserializer.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-class LLM::Session
+class LLM::Context
   ##
   # @api private
   module Deserializer
@@ -11,7 +11,8 @@ class LLM::Session
       tool_calls = deserialize_tool_calls(payload["tools"])
       returns = deserialize_returns(payload["content"]) if returns.nil?
       original_tool_calls = payload["original_tool_calls"]
-      extra = {tool_calls:, original_tool_calls:}.compact
+      usage = payload["usage"]
+      extra = {tool_calls:, original_tool_calls:, tools: @params[:tools], usage:}.compact
       content = returns.nil? ? payload["content"] : returns
       LLM::Message.new(payload["role"], content, extra)
     end
@@ -27,7 +28,7 @@ class LLM::Session
       returns = [*items].filter_map do |item|
         next unless Hash === item
         id, name, value = item.values_at("id", "name", "value")
-        next if id.nil? || name.nil? || value.nil?
+        next if name.nil? || value.nil?
         LLM::Function::Return.new(id, name, value)
       end
       returns.empty? ? nil : returns

data/lib/llm/context.rb

@@ -0,0 +1,292 @@
+# frozen_string_literal: true
+
+module LLM
+  ##
+  # {LLM::Context LLM::Context} represents a stateful interaction with
+  # an LLM, including conversation history, tools, execution state,
+  # and cost tracking. It evolves over time as the system runs.
+  #
+  # Context is the stateful environment in which an LLM operates.
+  # This is not just prompt context; it is an active, evolving
+  # execution boundary for LLM workflows.
+  #
+  # A context can use the chat completions API that all providers
+  # support or the responses API that currently only OpenAI supports.
+  #
+  # @example
+  #   #!/usr/bin/env ruby
+  #   require "llm"
+  #
+  #   llm = LLM.openai(key: ENV["KEY"])
+  #   ctx = LLM::Context.new(llm)
+  #
+  #   prompt = LLM::Prompt.new(llm) do
+  #     system "Be concise and show your reasoning briefly."
+  #     user "If a train goes 60 mph for 1.5 hours, how far does it travel?"
+  #     user "Now double the speed for the same time."
+  #   end
+  #
+  #   ctx.talk(prompt)
+  #   ctx.messages.each { |m| puts "[#{m.role}] #{m.content}" }
+  class Context
+    require_relative "context/deserializer"
+    include Deserializer
+
+    ##
+    # Returns the accumulated message history for this context
+    # @return [LLM::Buffer<LLM::Message>]
+    attr_reader :messages
+
+    ##
+    # Returns a provider
+    # @return [LLM::Provider]
+    attr_reader :llm
+
+    ##
+    # @param [LLM::Provider] llm
+    #  A provider
+    # @param [Hash] params
+    #  The parameters to maintain throughout the conversation.
+    #  Any parameter the provider supports can be included and
+    #  not only those listed here.
+    # @option params [String] :model Defaults to the provider's default model
+    # @option params [Array<LLM::Function>, nil] :tools Defaults to nil
+    def initialize(llm, params = {})
+      @llm = llm
+      @params = {model: llm.default_model, schema: nil}.compact.merge!(params)
+      @messages = LLM::Buffer.new(llm)
+    end
+
+    ##
+    # Interact with the context via the chat completions API.
+    # This method immediately sends a request to the LLM and returns the response.
+    #
+    # @param prompt (see LLM::Provider#complete)
+    # @param params The params, including optional :role (defaults to :user), :stream, :tools, :schema etc.
+    # @return [LLM::Response] Returns the LLM's response for this turn.
+    # @example
+    #   llm = LLM.openai(key: ENV["KEY"])
+    #   ctx = LLM::Context.new(llm)
+    #   res = ctx.talk("Hello, what is your name?")
+    #   puts res.messages[0].content
+    def talk(prompt, params = {})
+      params = params.merge(messages: @messages.to_a)
+      params = @params.merge(params)
+      res = @llm.complete(prompt, params)
+      role = params[:role] || @llm.user_role
+      role = @llm.tool_role if params[:role].nil? && [*prompt].grep(LLM::Function::Return).any?
+      @messages.concat LLM::Prompt === prompt ? prompt.to_a : [LLM::Message.new(role, prompt)]
+      @messages.concat [res.choices[-1]]
+      res
+    end
+    alias_method :chat, :talk
+
+    ##
+    # Interact with the context via the responses API.
+    # This method immediately sends a request to the LLM and returns the response.
+    #
+    # @note Not all LLM providers support this API
+    # @param prompt (see LLM::Provider#complete)
+    # @param params The params, including optional :role (defaults to :user), :stream, :tools, :schema etc.
+    # @return [LLM::Response] Returns the LLM's response for this turn.
+    # @example
+    #   llm = LLM.openai(key: ENV["KEY"])
+    #   ctx = LLM::Context.new(llm)
+    #   res = ctx.respond("What is the capital of France?")
+    #   puts res.output_text
+    def respond(prompt, params = {})
+      res_id = @messages.find(&:assistant?)&.response&.response_id
+      params = params.merge(previous_response_id: res_id, input: @messages.to_a).compact
+      params = @params.merge(params)
+      res = @llm.responses.create(prompt, params)
+      role = params[:role] || @llm.user_role
+      @messages.concat LLM::Prompt === prompt ? prompt.to_a : [LLM::Message.new(role, prompt)]
+      @messages.concat [res.choices[-1]]
+      res
+    end
+
+    ##
+    # @return [String]
+    def inspect
+      "#<#{self.class.name}:0x#{object_id.to_s(16)} " \
+      "@llm=#{@llm.class}, @params=#{@params.inspect}, " \
+      "@messages=#{@messages.inspect}>"
+    end
+
+    ##
+    # Returns an array of functions that can be called
+    # @return [Array<LLM::Function>]
+    def functions
+      @messages
+        .select(&:assistant?)
+        .flat_map do |msg|
+          fns = msg.functions.select(&:pending?)
+          fns.each do |fn|
+            fn.tracer = tracer
+            fn.model  = msg.model
+          end
+        end.extend(LLM::Function::Array)
+    end
+
+    ##
+    # Returns token usage accumulated in this context
+    # @note
+    # This method returns token usage for the latest
+    # assistant message, and it returns nil for non-assistant
+    # messages.
+    # @return [LLM::Object, nil]
+    def usage
+      @messages.find(&:assistant?)&.usage
+    end
+
+    ##
+    # Build a role-aware prompt for a single request.
+    #
+    # Prefer this method over {#build_prompt}. The older
+    # method name is kept for backward compatibility.
+    # @example
+    #   prompt = ctx.prompt do
+    #     system "Your task is to assist the user"
+    #     user "Hello, can you assist me?"
+    #   end
+    #   ctx.talk(prompt)
+    # @param [Proc] b
+    #  A block that composes messages. If it takes one argument,
+    #  it receives the prompt object. Otherwise it runs in prompt context.
+    # @return [LLM::Prompt]
+    def prompt(&b)
+      LLM::Prompt.new(@llm, &b)
+    end
+    alias_method :build_prompt, :prompt
+
+    ##
+    # Recongize an object as a URL to an image
+    # @param [String] url
+    #  The URL
+    # @return [LLM::Object]
+    #  Returns a tagged object
+    def image_url(url)
+      LLM::Object.from(value: url, kind: :image_url)
+    end
+
+    ##
+    # Recongize an object as a local file
+    # @param [String] path
+    #  The path
+    # @return [LLM::Object]
+    #  Returns a tagged object
+    def local_file(path)
+      LLM::Object.from(value: LLM.File(path), kind: :local_file)
+    end
+
+    ##
+    # Reconginize an object as a remote file
+    # @param [LLM::Response] res
+    #  The response
+    # @return [LLM::Object]
+    #  Returns a tagged object
+    def remote_file(res)
+      LLM::Object.from(value: res, kind: :remote_file)
+    end
+
+    ##
+    # @return [LLM::Tracer]
+    #  Returns an LLM tracer
+    def tracer
+      @llm.tracer
+    end
+
+    ##
+    # Returns the model a Context is actively using
+    # @return [String]
+    def model
+      messages.find(&:assistant?)&.model || @params[:model]
+    end
+
+    ##
+    # @return [Hash]
+    def to_h
+      {model:, messages:}
+    end
+
+    ##
+    # @return [String]
+    def to_json(...)
+      {schema_version: 1}.merge!(to_h).to_json(...)
+    end
+
+    ##
+    # Save the current context state
+    # @example
+    #  llm = LLM.openai(key: ENV["KEY"])
+    #  ctx = LLM::Context.new(llm)
+    #  ctx.talk "Hello"
+    #  ctx.save(path: "context.json")
+    # @raise [SystemCallError]
+    #  Might raise a number of SystemCallError subclasses
+    # @return [void]
+    def serialize(path:)
+      ::File.binwrite path, LLM.json.dump(self)
+    end
+    alias_method :save, :serialize
+
+    ##
+    # Restore a saved context state
+    # @param [String, nil] path
+    #  The path to a JSON file
+    # @param [String, nil] string
+    #  A raw JSON string
+    # @raise [SystemCallError]
+    #  Might raise a number of SystemCallError subclasses
+    # @return [LLM::Context]
+    def deserialize(path: nil, string: nil)
+      payload = if path.nil? and string.nil?
+        raise ArgumentError, "a path or string is required"
+      elsif path
+        ::File.binread(path)
+      else
+        string
+      end
+      ctx = LLM.json.load(payload)
+      @messages.concat [*ctx["messages"]].map { deserialize_message(_1) }
+      self
+    end
+    alias_method :restore, :deserialize
+
+    ##
+    # @return [LLM::Cost]
+    #  Returns an _approximate_ cost for a given context
+    #  based on both the provider, and model
+    def cost
+      return LLM::Cost.new(0, 0) unless usage
+      cost = LLM.registry_for(llm).cost(model:)
+      LLM::Cost.new(
+        (cost.input.to_f / 1_000_000.0)  * usage.input_tokens,
+        (cost.output.to_f / 1_000_000.0) * usage.output_tokens
+      )
+    end
+
+    ##
+    # Returns the model's context window.
+    # The context window is the maximum amount of input and output
+    # tokens a model can consider in a single request.
+    # @note
+    #   This method returns 0 when the provider or
+    #   model can't be found within {LLM::Registry}.
+    # @return [Integer]
+    def context_window
+      LLM
+        .registry_for(llm)
+        .limit(model:)
+        .context
+    rescue LLM::NoSuchModelError, LLM::NoSuchRegistryError
+      0
+    end
+  end
+
+  # Backward-compatible alias
+  Bot = Context
+
+  # Scheduled for removal in v6.0
+  deprecate_constant :Bot
+end

data/lib/llm/cost.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+##
+# The {LLM::Cost LLM::Cost} class represents an approximate
+# cost breakdown for a provider request. It stores the input
+# and output costs separately and can return the total.
+#
+# @attr [Float] input_costs
+#   Returns the input cost
+# @attr [Float] output_costs
+#   Returns the output cost
+class LLM::Cost < Struct.new(:input_costs, :output_costs)
+  ##
+  # @return [Float]
+  #  Returns the total cost
+  def total
+    input_costs + output_costs
+  end
+
+  ##
+  # @return [String]
+  #  Returns the total cost in a human friendly format
+  def to_s
+    format("%.12f", total).sub(/\.?0+$/, "")
+  end
+end

data/lib/llm/error.rb

@@ -54,4 +54,12 @@ module LLM
   ##
   # When stuck in a tool call loop
   ToolLoopError = Class.new(Error)
+
+  ##
+  # When {LLM::Registry} can't map a model
+  NoSuchModelError = Class.new(Error)
+
+  ##
+  # When {LLM::Registry} can't map a registry
+  NoSuchRegistryError = Class.new(Error)
 end

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