llm.rb 4.8.0 → 4.9.0

data/lib/llm/providers/openai/response_adapter/responds.rb

@@ -38,7 +38,15 @@ module LLM::OpenAI::ResponseAdapter
     end
 
     def adapt_tool(tool)
-      {id: tool.call_id, name: tool.name, arguments: LLM.json.load(tool.arguments)}
+      {id: tool.call_id, name: tool.name, arguments: parse_tool_arguments(tool.arguments)}
+    end
+
+    def parse_tool_arguments(arguments)
+      return {} if arguments.to_s.empty?
+      parsed = LLM.json.load(arguments)
+      Hash === parsed ? parsed : {}
+    rescue *LLM.json.parser_error
+      {}
     end
   end
 end

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

@@ -41,7 +41,7 @@ class LLM::OpenAI
       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)
-      messages = [*(params.delete(:input) || []), LLM::Message.new(role, prompt)]
+      messages = build_complete_messages(prompt, params, role)
       @provider.tracer.set_request_metadata(user_input: extract_user_input(messages, fallback: prompt))
       body = LLM.json.dump({input: [adapt(messages, mode: :response)].flatten}.merge!(params))
       set_body_stream(req, StringIO.new(body))
@@ -89,6 +89,14 @@ class LLM::OpenAI
       define_method(m) { |*args, **kwargs, &b| @provider.send(m, *args, **kwargs, &b) }
     end
 
+    def build_complete_messages(prompt, params, role)
+      if LLM::Prompt === prompt
+        [*(params.delete(:input) || []), *prompt]
+      else
+        [*(params.delete(:input) || []), LLM::Message.new(role, prompt)]
+      end
+    end
+
     def adapt_schema(params)
       return {} unless params && params[:schema]
       schema = params.delete(:schema)

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

@@ -43,6 +43,7 @@ class LLM::OpenAI
           target_message = @body["choices"][index]["message"]
           delta = choice["delta"] || {}
           delta.each do |key, value|
+            next if value.nil?
             if key == "content"
               target_message[key] ||= +""
               target_message[key] << value
@@ -57,6 +58,7 @@ class LLM::OpenAI
           message_hash = {"role" => "assistant"}
           @body["choices"][index] = {"message" => message_hash}
           (choice["delta"] || {}).each do |key, value|
+            next if value.nil?
             if key == "content"
               @io << value if @io.respond_to?(:<<)
               message_hash[key] = value

data/lib/llm/providers/openai.rb

@@ -10,9 +10,9 @@ module LLM
   #   require "llm"
   #
   #   llm = LLM.openai(key: ENV["KEY"])
-  #   ses = LLM::Session.new(llm)
-  #   ses.talk ["Tell me about this photo", ses.local_file("/images/photo.png")]
-  #   ses.messages.select(&:assistant?).each { print "[#{_1.role}]", _1.content, "\n" }
+  #   ctx = LLM::Context.new(llm)
+  #   ctx.talk ["Tell me about this photo", ctx.local_file("/images/photo.png")]
+  #   ctx.messages.select(&:assistant?).each { print "[#{_1.role}]", _1.content, "\n" }
   class OpenAI < Provider
     require_relative "openai/error_handler"
     require_relative "openai/request_adapter"
@@ -36,6 +36,13 @@ module LLM
       super(host: HOST, **)
     end
 
+    ##
+    # @return [Symbol]
+    #  Returns the provider's name
+    def name
+      :openai
+    end
+
     ##
     # Provides an embedding
     # @see https://platform.openai.com/docs/api-reference/embeddings/create OpenAI docs
@@ -213,13 +220,21 @@ module LLM
     end
 
     def build_complete_request(prompt, params, role)
-      messages = [*(params.delete(:messages) || []), Message.new(role, prompt)]
+      messages = build_complete_messages(prompt, params, role)
       body = LLM.json.dump({messages: adapt(messages, mode: :complete).flatten}.merge!(params))
       req = Net::HTTP::Post.new(completions_path, headers)
       set_body_stream(req, StringIO.new(body))
       [req, messages]
     end
 
+    def build_complete_messages(prompt, params, role)
+      if LLM::Prompt === prompt
+        [*(params.delete(:messages) || []), *prompt]
+      else
+        [*(params.delete(:messages) || []), Message.new(role, prompt)]
+      end
+    end
+
     def extract_user_input(messages, fallback:)
       message = messages.reverse.find(&:user?) || messages.last
       value = message&.content || fallback

data/lib/llm/providers/xai.rb

@@ -11,9 +11,9 @@ module LLM
   #   require "llm"
   #
   #   llm = LLM.xai(key: ENV["KEY"])
-  #   ses = LLM::Session.new(llm)
-  #   ses.talk ["Tell me about this photo", ses.local_file("/images/photo.png")]
-  #   ses.messages.select(&:assistant?).each { print "[#{_1.role}]", _1.content, "\n" }
+  #   ctx = LLM::Context.new(llm)
+  #   ctx.talk ["Tell me about this photo", ctx.local_file("/images/photo.png")]
+  #   ctx.messages.select(&:assistant?).each { print "[#{_1.role}]", _1.content, "\n" }
   class XAI < OpenAI
     require_relative "xai/images"
 
@@ -25,6 +25,13 @@ module LLM
       super
     end
 
+    ##
+    # @return [Symbol]
+    #  Returns the provider's name
+    def name
+      :xai
+    end
+
     ##
     # @raise [NotImplementedError]
     def files

data/lib/llm/providers/zai.rb

@@ -11,8 +11,8 @@ module LLM
   #   require "llm"
   #
   #   llm = LLM.zai(key: ENV["KEY"])
-  #   ses = LLM::Session.new(llm, stream: $stdout)
-  #   ses.talk "Hello"
+  #   ctx = LLM::Context.new(llm, stream: $stdout)
+  #   ctx.talk "Hello"
   class ZAI < OpenAI
     ##
     # @param [String] host A regional host or the default ("api.z.ai")
@@ -21,6 +21,13 @@ module LLM
       super
     end
 
+    ##
+    # @return [Symbol]
+    #  Returns the provider's name
+    def name
+      :zai
+    end
+
     ##
     # @raise [NotImplementedError]
     def files

data/lib/llm/registry.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+##
+# The {LLM::Registry LLM::Registry} class provides a small API over
+# provider model data. It exposes model metadata such as pricing,
+# capabilities, modalities, and limits from the registry files
+# stored under `data/`. The data is provided by https://models.dev
+# and shipped with llm.rb.
+class LLM::Registry
+  @root = File.join(__dir__, "..", "..")
+
+  ##
+  # @raise [LLM::Error]
+  #  Might raise an error
+  # @param [Symbol]
+  #  A provider name
+  # @return [LLM::Registry]
+  def self.for(name)
+    path = File.join @root, "data", "#{name}.json"
+    if File.file?(path)
+      new LLM.json.load(File.binread(path))
+    else
+      raise LLM::NoSuchRegistryError, "no registry found for #{name}"
+    end
+  end
+
+  ##
+  # @param [Hash] blob
+  #  A model registry
+  # @return [LLM::Registry]
+  def initialize(blob)
+    @registry = LLM::Object.from(blob)
+    @models = @registry.models
+  end
+
+  ##
+  # @return [LLM::Object]
+  #  Returns model costs
+  def cost(model:)
+    lookup(model:).cost
+  end
+
+  ##
+  # @return [LLM::Object]
+  #  Returns model modalities
+  def modalities(model:)
+    lookup(model:).modalities
+  end
+
+  ##
+  # @return [LLM::Object]
+  #  Returns model limits such as the context window size
+  def limit(model:)
+    lookup(model:).limit
+  end
+
+  private
+
+  def lookup(model:)
+    if @models.key?(model)
+      @models[model]
+    else
+      patterns = {/-\d{4}-\d{2}-\d{2}$/ => "", /\A(gpt-.*)-\d{4}$/ => "\\1"}
+      fallback = find_map(patterns) { model.dup.sub!(_1, _2) } || "none"
+      if @models.key?(fallback)
+        @models[fallback]
+      else
+        raise LLM::NoSuchModelError, "no such model: #{model} (fallback: #{fallback})"
+      end
+    end
+  end
+
+  ##
+  # Similar to #{find} but returns the block's return value
+  # @return [Object, nil]
+  def find_map(pair)
+    result = nil
+    pair.each_pair { break if result = yield(_1, _2) }
+    result
+  end
+end

data/lib/llm/schema/parser.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+class LLM::Schema
+  ##
+  # The {LLM::Schema::Parser LLM::Schema::Parser} module provides
+  # methods for parsing a JSON schema into {LLM::Schema::Leaf}
+  # objects. It is used by {LLM::Schema LLM::Schema} to convert
+  # external JSON schema definitions into the schema objects used
+  # throughout llm.rb.
+  module Parser
+    ##
+    # Parses a JSON schema into an {LLM::Schema::Leaf}.
+    # @param [Hash] schema
+    #  The JSON schema to parse
+    # @raise [TypeError]
+    #  When the schema is not supported
+    # @return [LLM::Schema::Leaf]
+    def parse(schema, root = nil)
+      schema = normalize_schema(schema)
+      root ||= schema
+      schema = resolve_ref(schema, root)
+      case schema["type"]
+      when "object" then apply(parse_object(schema, root), schema)
+      when "array" then apply(parse_array(schema, root), schema)
+      when "string" then apply(parse_string(schema), schema)
+      when "integer" then apply(parse_integer(schema), schema)
+      when "number" then apply(parse_number(schema), schema)
+      when "boolean" then apply(schema().boolean, schema)
+      when "null" then apply(schema().null, schema)
+      else raise TypeError, "unsupported schema type #{schema["type"].inspect}"
+      end
+    end
+
+    private
+
+    def parse_object(schema, root)
+      properties = (schema["properties"] || {})
+        .transform_keys(&:to_s)
+        .transform_values { parse(_1, root) }
+      required = schema["required"] || []
+      required.each do |key|
+        next unless properties[key]
+        properties[key].required
+      end
+      schema().object(properties)
+    end
+
+    def parse_array(schema, root)
+      items = schema["items"] ? parse(schema["items"], root) : schema().null
+      schema().array(items)
+    end
+
+    def parse_string(schema)
+      leaf = schema().string
+      leaf.min(schema["minLength"]) if schema.key?("minLength")
+      leaf.max(schema["maxLength"]) if schema.key?("maxLength")
+      leaf
+    end
+
+    def parse_integer(schema)
+      leaf = schema().integer
+      leaf.min(schema["minimum"]) if schema.key?("minimum")
+      leaf.max(schema["maximum"]) if schema.key?("maximum")
+      leaf.multiple_of(schema["multipleOf"]) if schema.key?("multipleOf")
+      leaf
+    end
+
+    def parse_number(schema)
+      leaf = schema().number
+      leaf.min(schema["minimum"]) if schema.key?("minimum")
+      leaf.max(schema["maximum"]) if schema.key?("maximum")
+      leaf.multiple_of(schema["multipleOf"]) if schema.key?("multipleOf")
+      leaf
+    end
+
+    def apply(leaf, schema)
+      leaf.description(schema["description"]) if schema.key?("description")
+      leaf.default(schema["default"]) if schema.key?("default")
+      leaf.enum(*schema["enum"]) if schema.key?("enum")
+      leaf.const(schema["const"]) if schema.key?("const")
+      leaf
+    end
+
+    def normalize_schema(schema)
+      case schema
+      when LLM::Object
+        normalize_schema(schema.to_h)
+      when Hash
+        schema.each_with_object({}) do |(key, value), out|
+          out[key.to_s] = normalize_schema(value)
+        end
+      when Array
+        schema.map { normalize_schema(_1) }
+      else
+        schema
+      end
+    end
+
+    def resolve_ref(schema, root)
+      return schema unless schema.key?("$ref")
+      ref = schema["$ref"]
+      raise TypeError, "unsupported schema ref #{ref.inspect}" unless ref.start_with?("#/")
+      target = ref.delete_prefix("#/").split("/").reduce(root) { |node, key| node.fetch(key) }
+      normalize_schema(target).merge(schema.except("$ref"))
+    rescue KeyError
+      raise TypeError, "unresolvable schema ref #{ref.inspect}"
+    end
+  end
+end

data/lib/llm/schema.rb

@@ -31,6 +31,7 @@
 #  end
 class LLM::Schema
   require_relative "schema/version"
+  require_relative "schema/parser"
   require_relative "schema/leaf"
   require_relative "schema/object"
   require_relative "schema/array"
@@ -41,6 +42,9 @@ class LLM::Schema
   require_relative "schema/boolean"
   require_relative "schema/null"
 
+  @__monitor = Monitor.new
+  extend LLM::Schema::Parser
+
   ##
   # Configures a monitor for a subclass
   # @return [void]

data/lib/llm/server_tool.rb

@@ -8,10 +8,10 @@
 #
 # @example
 #   #!/usr/bin/env ruby
-#   llm = LLM.gemini ENV["KEY"]
-#   ses = LLM::Session.new(llm, tools: [LLM::ServerTool.new(:google_search)])
-#   ses.talk("Summarize today's news", role: :user)
-#   print ses.messages.find(&:assistant?).content, "\n"
+#   llm = LLM.google ENV["KEY"]
+#   ctx = LLM::Context.new(llm, tools: [LLM::ServerTool.new(:google_search)])
+#   ctx.talk("Summarize today's news", role: :user)
+#   print ctx.messages.find(&:assistant?).content, "\n"
 class LLM::ServerTool < Struct.new(:name, :options, :provider)
   ##
   # @return [String]
@@ -24,7 +24,7 @@ class LLM::ServerTool < Struct.new(:name, :options, :provider)
   def to_h
     case provider.class.to_s
     when "LLM::Anthropic" then options.merge("name" => name.to_s)
-    when "LLM::Gemini" then {name => options}
+    when "LLM::Google" then {name => options}
     else options.merge("type" => name.to_s)
     end
   end

data/lib/llm/session.rb

@@ -1,3 +1,12 @@
 # frozen_string_literal: true
 
-require_relative "bot"
+require_relative "context"
+
+module LLM
+  # Backward-compatible alias for LLM::Context
+  # @deprecated Use {LLM::Context} instead. Scheduled for removal in v6.0.
+  Session = Context
+
+  # Scheduled for removal in v6.0
+  deprecate_constant :Session
+end

data/lib/llm/tool.rb

@@ -30,14 +30,87 @@ class LLM::Tool
     const_set constant, LLM::Schema.const_get(constant)
   end
 
+  ##
+  # @param [LLM::MCP] mcp
+  #  The MCP client that will execute the tool call
+  # @param [Hash] tool
+  #  A tool (as a raw Hash)
+  # @return [Class<LLM::Tool>]
+  #  Returns a subclass of LLM::Tool
+  def self.mcp(mcp, tool)
+    klass = Class.new(LLM::Tool) do
+      name tool["name"]
+      description tool["description"]
+      params { tool["inputSchema"] || {type: "object", properties: {}} }
+
+      define_singleton_method(:inspect) do
+        "<LLM::Tool:0x#{object_id.to_s(16)} name=#{tool["name"]} (mcp)>"
+      end
+      singleton_class.alias_method :to_s, :inspect
+
+      define_singleton_method(:mcp?) do
+        true
+      end
+
+      define_method(:call) do |**args|
+        mcp.call_tool(tool["name"], args)
+      end
+    end
+    unregister(klass)
+  end
+
+  ##
+  # Returns all subclasses of LLM::Tool
+  # @note
+  #  This method excludes tools who haven't defined a name
+  #  as well as tools defined via MCP.
+  # @return [Array<LLM::Tool>]
+  def self.registry
+    lock do
+      @registry.select(&:name)
+    end
+  end
+  @registry = []
+
+  ##
+  # Clear the registry
+  # @return [void]
+  def self.clear_registry!
+    lock do
+      @registry.clear
+      nil
+    end
+  end
+
+  ##
+  # Register a tool in the registry
+  # @param [LLM::Tool] tool
+  # @api private
+  def self.register(tool)
+    lock do
+      @registry << tool
+    end
+  end
+
+  ##
+  # Unregister a tool from the registry
+  # @param [LLM::Tool] tool
+  # @api private
+  def self.unregister(tool)
+    lock do
+      @registry.delete(tool)
+    end
+  end
+
   ##
   # Registers the tool as a function when inherited
   # @param [Class] klass The subclass
   # @return [void]
-  def self.inherited(klass)
+  def self.inherited(tool)
     LLM.lock(:inherited) do
-      klass.instance_eval { @__monitor ||= Monitor.new }
-      klass.function.register(klass)
+      tool.instance_eval { @__monitor ||= Monitor.new }
+      tool.function.register(tool)
+      LLM::Tool.register(tool)
     end
   end
 
@@ -75,7 +148,7 @@ class LLM::Tool
   # @api private
   def self.function
     lock do
-      @function ||= LLM::Function.new(self)
+      @function ||= LLM::Function.new(nil)
     end
   end
 
@@ -84,4 +157,12 @@ class LLM::Tool
   def self.lock(&)
     @__monitor.synchronize(&)
   end
+  @__monitor = Monitor.new
+
+  ##
+  # Returns true if the tool is an MCP tool
+  # @return [Boolean]
+  def self.mcp?
+    false
+  end
 end

data/lib/llm/tracer/logger.rb

@@ -23,7 +23,7 @@ module LLM
     ##
     # @param (see LLM::Tracer#on_request_start)
     # @return [void]
-    def on_request_start(operation:, model: nil)
+    def on_request_start(operation:, model: nil, **)
       case operation
       when "chat" then start_chat(operation:, model:)
       when "retrieval" then start_retrieval(operation:)

data/lib/llm/tracer/telemetry.rb

@@ -20,10 +20,10 @@ module LLM
   #   llm = LLM.openai(key: ENV["KEY"])
   #   llm.tracer = LLM::Tracer::Telemetry.new(llm)
   #
-  #   ses = LLM::Session.new(llm)
-  #   ses.talk "hello"
-  #   ses.talk "how are you?"
-  #   ses.tracer.spans.each { |span| pp span }
+  #   ctx = LLM::Context.new(llm)
+  #   ctx.talk "hello"
+  #   ctx.talk "how are you?"
+  #   ctx.tracer.spans.each { |span| pp span }
   #
   # @example OTLP export
   #   #!/usr/bin/env ruby
@@ -36,9 +36,9 @@ module LLM
   #   llm = LLM.openai(key: ENV["KEY"])
   #   llm.tracer = LLM::Tracer::Telemetry.new(llm, exporter:)
   #
-  #   ses = LLM::Session.new(llm)
-  #   ses.talk "hello"
-  #   ses.talk "how are you?"
+  #   ctx = LLM::Context.new(llm)
+  #   ctx.talk "hello"
+  #   ctx.talk "how are you?"
   class Tracer::Telemetry < Tracer
     ##
     # param [LLM::Provider] provider

data/lib/llm/tracer.rb

@@ -147,7 +147,7 @@ module LLM
     # Merges extra attributes for the current trace/span. Used by applications
     # (e.g. chatbot) to add metadata, span inputs, or span outputs to the next
     # span or to the trace. No-op by default; {LLM::Tracer::Langsmith} merges
-    # into thread-local storage and emits them as langsmith/GenAI attributes.
+    # into fiber-local storage and emits them as langsmith/GenAI attributes.
     #
     # @param [Hash, nil] metadata
     #  Key-value pairs merged into trace/span metadata (e.g. langsmith.metadata.*).
@@ -190,7 +190,7 @@ module LLM
     ##
     # Returns and clears extra inputs for the next span. Called by the telemetry
     # tracer when starting a span. Subclasses (e.g. Langsmith) override to
-    # return thread-local inputs; default returns {}.
+    # return fiber-local inputs; default returns {}.
     #
     # @return [Hash] Attribute key => value to set on the span at start
     def consume_extra_inputs
@@ -200,7 +200,7 @@ module LLM
     ##
     # Returns and clears extra outputs for the current span. Called by the
     # telemetry tracer when finishing a span. Subclasses override to return
-    # thread-local outputs; default returns {}.
+    # fiber-local outputs; default returns {}.
     #
     # @return [Hash] Attribute key => value to set on the span at finish
     def consume_extra_outputs

data/lib/llm/usage.rb

@@ -8,4 +8,9 @@
 # It can also help track usage of the context window (which may
 # vary by model).
 class LLM::Usage < Struct.new(:input_tokens, :output_tokens, :reasoning_tokens, :total_tokens, keyword_init: true)
+  ##
+  # @return [String]
+  def to_json(...)
+    LLM.json.dump({input_tokens:, output_tokens:, reasoning_tokens:, total_tokens:})
+  end
 end

data/lib/llm/version.rb

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

data/lib/llm.rb

@@ -6,6 +6,8 @@ module LLM
   require_relative "llm/tracer"
   require_relative "llm/error"
   require_relative "llm/contract"
+  require_relative "llm/registry"
+  require_relative "llm/cost"
   require_relative "llm/usage"
   require_relative "llm/prompt"
   require_relative "llm/schema"
@@ -19,7 +21,7 @@ module LLM
   require_relative "llm/multipart"
   require_relative "llm/file"
   require_relative "llm/provider"
-  require_relative "llm/session"
+  require_relative "llm/context"
   require_relative "llm/agent"
   require_relative "llm/buffer"
   require_relative "llm/function"
@@ -30,7 +32,22 @@ module LLM
 
   ##
   # Thread-safe monitors for different contexts
-  @monitors = {require: Monitor.new, clients: Monitor.new, inherited: Monitor.new}
+  @monitors = {require: Monitor.new, clients: Monitor.new, inherited: Monitor.new, registry: Monitor.new}
+
+  ##
+  # Model registry
+  @registry = {}
+
+  ##
+  # @param [Symbol, LLM::Provider] llm
+  #  The name of a provider, or an instance of LLM::Provider
+  # @return [LLM::Object]
+  def self.registry_for(llm)
+    lock(:registry) do
+      name = Symbol === llm ? llm : llm.name
+      @registry[name] ||= Registry.for(name)
+    end
+  end
 
   module_function
 
@@ -76,10 +93,10 @@ module LLM
 
   ##
   # @param (see LLM::Provider#initialize)
-  # @return (see LLM::Gemini#initialize)
-  def gemini(**)
-    lock(:require) { require_relative "llm/providers/gemini" unless defined?(LLM::Gemini) }
-    LLM::Gemini.new(**)
+  # @return (see LLM::Google#initialize)
+  def google(**)
+    lock(:require) { require_relative "llm/providers/google" unless defined?(LLM::Google) }
+    LLM::Google.new(**)
   end
 
   ##
@@ -132,6 +149,22 @@ module LLM
     LLM::ZAI.new(**)
   end
 
+  ##
+  # @param [LLM::Provider, nil] llm
+  #  The provider to use for MCP transports that need one
+  # @param [Hash, nil] stdio
+  # @option stdio [Array<String>] :argv
+  #  The command to run for the MCP process
+  # @option stdio [Hash] :env
+  #  The environment variables to set for the MCP process
+  # @option stdio [String, nil] :cwd
+  #  The working directory for the MCP process
+  # @return [LLM::MCP]
+  def mcp(llm = nil, **)
+    lock(:require) { require_relative "llm/mcp" unless defined?(LLM::MCP) }
+    LLM::MCP.new(llm, **)
+  end
+
   ##
   # Define a function
   # @example