llm.rb 4.7.0 → 4.9.0

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

@@ -41,7 +41,8 @@ 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))
       res, span, tracer = execute(request: req, stream:, stream_parser:, operation: "chat", model: params[:model])
@@ -88,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)
@@ -99,5 +108,11 @@ class LLM::OpenAI
     def stream_parser
       LLM::OpenAI::Responses::StreamParser
     end
+
+    def extract_user_input(messages, fallback:)
+      message = messages.reverse.find(&:user?) || messages.last
+      value = message&.content || fallback
+      value.is_a?(String) ? value : LLM.json.dump(value)
+    end
   end
 end

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
@@ -65,7 +72,8 @@ module LLM
     # @return (see LLM::Provider#complete)
     def complete(prompt, params = {})
       params, stream, tools, role = normalize_complete_params(params)
-      req = build_complete_request(prompt, params, role)
+      req, messages = build_complete_request(prompt, params, role)
+      tracer.set_request_metadata(user_input: extract_user_input(messages, fallback: prompt))
       res, span, tracer = execute(request: req, stream: stream, operation: "chat", model: params[:model])
       res = ResponseAdapter.adapt(res, type: :completion)
         .extend(Module.new { define_method(:__tools__) { tools } })
@@ -212,11 +220,25 @@ 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
+      [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
+      value.is_a?(String) ? value : LLM.json.dump(value)
     end
   end
 end

data/lib/llm/providers/xai/images.rb

@@ -5,7 +5,7 @@ class LLM::XAI
   # The {LLM::XAI::Images LLM::XAI::Images} class provides an interface
   # for [xAI's images API](https://docs.x.ai/docs/guides/image-generations).
   # xAI supports multiple response formats: temporary URLs, or binary strings
-  # encoded in base64. The default is to return temporary URLs.
+  # encoded in base64. The default is to return base64-encoded image data.
   #
   # @example Temporary URLs
   #   #!/usr/bin/env ruby
@@ -14,7 +14,8 @@ class LLM::XAI
   #   require "fileutils"
   #
   #   llm = LLM.xai(key: ENV["KEY"])
-  #   res = llm.images.create prompt: "A dog on a rocket to the moon"
+  #   res = llm.images.create prompt: "A dog on a rocket to the moon",
+  #                        response_format: "url"
   #   FileUtils.mv OpenURI.open_uri(res.urls[0]).path,
   #                "rocket.png"
   #
@@ -32,26 +33,26 @@ class LLM::XAI
     # @example
     #   llm = LLM.xai(key: ENV["KEY"])
     #   res = llm.images.create prompt: "A dog on a rocket to the moon"
-    #   res.urls.each { print _1, "\n"}
+    #   IO.copy_stream res.images[0], "rocket.png"
     # @see https://docs.x.ai/docs/guides/image-generations xAI docs
     # @param [String] prompt The prompt
     # @param [String] model The model to use
     # @param [Hash] params Other parameters (see xAI docs)
     # @raise (see LLM::Provider#request)
     # @return [LLM::Response]
-    def create(prompt:, model: "grok-2-image-1212", **params)
+    def create(prompt:, model: "grok-imagine-image", **params)
       super
     end
 
     ##
     # @raise [NotImplementedError]
-    def edit(model: "grok-2-image-1212", **)
+    def edit(model: "grok-imagine-image", **)
       raise NotImplementedError
     end
 
     ##
     # @raise [NotImplementedError]
-    def create_variation(model: "grok-2-image-1212", **)
+    def create_variation(model: "grok-imagine-image", **)
       raise NotImplementedError
     end
   end

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/enum.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+class LLM::Schema
+  ##
+  # The {LLM::Schema::Enum LLM::Schema::Enum} class represents a
+  # string value constrained to one of a fixed set of values.
+  class Enum
+    ##
+    # Returns a string leaf constrained to the given values
+    # @param [Array<String>] values
+    # @return [LLM::Schema::String]
+    def self.[](*values)
+      LLM::Schema::String.new.enum(*values)
+    end
+  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,15 +31,20 @@
 #  end
 class LLM::Schema
   require_relative "schema/version"
+  require_relative "schema/parser"
   require_relative "schema/leaf"
   require_relative "schema/object"
   require_relative "schema/array"
   require_relative "schema/string"
+  require_relative "schema/enum"
   require_relative "schema/number"
   require_relative "schema/integer"
   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/param.rb

@@ -65,7 +65,7 @@ class LLM::Tool
         leaf.required if required
         leaf.description(description) if description
         leaf.default(default) if default
-        leaf.enum(enum) if enum
+        leaf.enum(*enum) if enum
         leaf
       end
     end

data/lib/llm/tool.rb

@@ -22,7 +22,7 @@ class LLM::Tool
   extend LLM::Tool::Param
 
   types = [
-    :Leaf, :String, :Array,
+    :Leaf, :String, :Enum, :Array,
     :Object, :Integer, :Number,
     :Boolean, :Null
   ]
@@ -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