llm.rb 11.3.0 → 12.0.0

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

@@ -4,30 +4,21 @@ 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 base64-encoded image data.
+  # xAI returns base64-encoded image data.
   #
-  # @example Temporary URLs
+  # @example
   #   #!/usr/bin/env ruby
   #   require "llm"
-  #   require "open-uri"
-  #   require "fileutils"
   #
   #   llm = LLM.xai(key: ENV["KEY"])
-  #   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"
-  #
-  # @example Binary strings
-  #   #!/usr/bin/env ruby
-  #   require "llm"
-  #
-  #   llm = LLM.xai(key: ENV["KEY"])
-  #   res = llm.images.create prompt: "A dog on a rocket to the moon",
-  #                           response_format: "b64_json"
+  #   res = llm.images.create prompt: "A dog on a rocket to the moon"
   #   IO.copy_stream res.images[0], "rocket.png"
   class Images < LLM::OpenAI::Images
+    ##
+    # @api private
+    PATTERN = %r{\A(?:https?://|data:)}
+    private_constant :PATTERN
+
     ##
     # Create an image
     # @example
@@ -40,20 +31,52 @@ class LLM::XAI
     # @param [Hash] params Other parameters (see xAI docs)
     # @raise (see LLM::Provider#request)
     # @return [LLM::Response]
-    def create(prompt:, model: "grok-imagine-image", **params)
-      super
+    def create(prompt:, model: "grok-imagine-image-quality", **params)
+      req = LLM::Transport::Request.post(path("/images/generations"), headers)
+      req.body = LLM.json.dump({prompt:, n: 1, model:, response_format: "b64_json"}.merge!(params))
+      res, span, tracer = execute(request: req, operation: "request")
+      res = LLM::OpenAI::ResponseAdapter.adapt(res, type: :image)
+      tracer.on_request_finish(operation: "request", model:, res:, span:)
+      res
     end
 
     ##
-    # @raise [NotImplementedError]
-    def edit(model: "grok-imagine-image", **)
-      raise NotImplementedError
+    # Edit an image
+    # @example
+    #   llm = LLM.xai(key: ENV["KEY"])
+    #   res = llm.images.edit(image: "/images/book.png", prompt: "The book is floating in the clouds")
+    #   IO.copy_stream res.images[0], "floating-book.png"
+    # @see https://docs.x.ai/docs/guides/image-generations xAI docs
+    # @param [String, LLM::File, File] image The image to edit
+    # @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 edit(image:, prompt:, model: "grok-imagine-image-quality", **params)
+      req = LLM::Transport::Request.post(path("/images/edits"), headers)
+      req.body = LLM.json.dump({
+        prompt:,
+        model:,
+        image: image_url(image),
+        response_format: "b64_json"
+      }.merge!(params))
+      res, span, tracer = execute(request: req, operation: "request")
+      res = LLM::OpenAI::ResponseAdapter.adapt(res, type: :image)
+      tracer.on_request_finish(operation: "request", model:, res:, span:)
+      res
     end
 
-    ##
-    # @raise [NotImplementedError]
-    def create_variation(model: "grok-imagine-image", **)
-      raise NotImplementedError
+    private
+
+    def image_url(image)
+      case image
+      when String
+        url = image.match?(PATTERN) ? image : LLM.File(image).to_data_uri
+      else
+        url = LLM.File(image).to_data_uri
+      end
+      {url:, type: "image_url"}
     end
   end
 end

data/lib/llm/providers/xai.rb

@@ -70,10 +70,10 @@ module LLM
 
     ##
     # Returns the default model for chat completions
-    # #see https://docs.x.ai/docs/models grok-4-0709
+    # #see https://docs.x.ai/docs/models grok-4.3
     # @return [String]
     def default_model
-      "grok-4-0709"
+      "grok-4.3"
     end
   end
 end

data/lib/llm/registry.rb

@@ -12,7 +12,7 @@ class LLM::Registry
   ##
   # @raise [LLM::Error]
   #  Might raise an error
-  # @param [Symbol]
+  # @param [Symbol] name
   #  A provider name
   # @return [LLM::Registry]
   def self.for(name)
@@ -71,7 +71,7 @@ class LLM::Registry
   end
 
   ##
-  # Similar to #{find} but returns the block's return value
+  # Similar to `#find` but returns the block's return value
   # @return [Object, nil]
   def find_map(pair)
     result = nil

data/lib/llm/response.rb

@@ -14,7 +14,7 @@ module LLM
   # through {#res}. When the default net/http transport is in use,
   # {LLM::Transport::Response::HTTP
   # LLM::Transport::Response::HTTP} keeps the
-  # original {Net::HTTPResponse Net::HTTPResponse} available through
+  # original `Net::HTTPResponse` available through
   # its own {LLM::Transport::Response::HTTP#res #res}.
   class Response
     require "json"
@@ -56,6 +56,16 @@ module LLM
       @res.success?
     end
 
+    ##
+    # Returns the provider response id when present.
+    # @return [String, nil]
+    def id
+      return nil unless LLM::Object === body
+      body.id          ||
+      body.responseId  || body.response_id ||
+      body.requestId   || body.request_id
+    end
+
     ##
     # Returns true if the response is from the Files API
     # @return [Boolean]

data/lib/llm/schema/leaf.rb

@@ -95,7 +95,7 @@ class LLM::Schema
     ##
     # @return [Hash]
     def to_h
-      {description: @description, default: @default, enum: @enum}.compact
+      {description: @description, default: @default, enum: @enum, const: @const}.compact
     end
 
     ##
@@ -104,6 +104,12 @@ class LLM::Schema
       to_h.to_json(options)
     end
 
+    ##
+    # @return [String]
+    def to_s
+      LLM::Schema::Renderer.render(self)
+    end
+
     ##
     # @param [LLM::Schema::Leaf] other
     #  An object to compare

data/lib/llm/schema/object.rb

@@ -12,7 +12,7 @@ class LLM::Schema
     attr_reader :properties
 
     ##
-    # @param params [Hash]
+    # @param [Hash] properties
     #  A hash of properties
     # @return [LLM::Schema::Object]
     def initialize(properties)

data/lib/llm/schema/renderer.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+class LLM::Schema
+  ##
+  # Internal renderer for prompt-friendly schema output.
+  # @api private
+  module Renderer
+    extend self
+
+    ##
+    # Render a schema node as a human-readable string.
+    # @param [LLM::Schema::Leaf] node
+    #  The schema node to render
+    # @param [Integer] indent
+    #  The indentation level
+    # @param [String, Symbol, nil] name
+    #  The property name for nested nodes
+    # @param [Boolean] root
+    #  Whether the node is the root schema object
+    # @return [String]
+    def render(node, indent: 0, name: nil, root: false)
+      line = (" " * indent).to_s
+      if name
+        line << name.to_s
+        line << "?" unless node.required?
+        line << ": "
+      end
+      line << type_name(node)
+      metadata = metadata_for(node, include_required: !root)
+      line << " (#{metadata.join(", ")})" unless metadata.empty?
+      line << " - #{node.description}" if node.respond_to?(:description) && node.description
+      nested = nested_lines(node, indent: indent + 2)
+      ([line] + nested).join("\n")
+    end
+
+    private
+
+    ##
+    # Render nested lines for compound schema nodes.
+    # @param [LLM::Schema::Leaf] node
+    #  The schema node
+    # @param [Integer] indent
+    #  The indentation level
+    # @return [Array<String>]
+    def nested_lines(node, indent:)
+      case node
+      when LLM::Schema::Object
+        node.properties.map { |key, val| render(val, indent:, name: key) }
+      when LLM::Schema::Array
+        items = node.to_h[:items]
+        items.is_a?(LLM::Schema::Object) ? [render(items, indent:, name: "items")] : []
+      else
+        []
+      end
+    end
+
+    ##
+    # Return the printable type name for a schema node.
+    # @param [LLM::Schema::Leaf] node
+    #  The schema node
+    # @return [String]
+    def type_name(node)
+      h = node.to_h
+      return "array<#{inline_type(h[:items])}>" if node.is_a?(LLM::Schema::Array)
+      return "anyOf<#{inline_types(h[:anyOf])}>" if node.is_a?(LLM::Schema::AnyOf)
+      return "oneOf<#{inline_types(h[:oneOf])}>" if node.is_a?(LLM::Schema::OneOf)
+      return "allOf<#{inline_types(h[:allOf])}>" if node.is_a?(LLM::Schema::AllOf)
+      h[:type] || "unknown"
+    end
+
+    ##
+    # Return the inline type description for a nested node.
+    # @param [LLM::Schema::Leaf, Object] node
+    #  The nested schema node
+    # @return [String]
+    def inline_type(node)
+      return type_name(node) if node.is_a?(LLM::Schema::Leaf)
+      node.inspect
+    end
+
+    ##
+    # Return the inline type description for a list of nodes.
+    # @param [Array<LLM::Schema::Leaf>] values
+    #  The union members
+    # @return [String]
+    def inline_types(values)
+      values.map { inline_type(_1) }.join(", ")
+    end
+
+    ##
+    # Extract printable metadata for a schema node.
+    # @param [LLM::Schema::Leaf] node
+    #  The schema node
+    # @param [Boolean] include_required
+    #  Whether to include the required marker
+    # @return [Array<String>]
+    def metadata_for(node, include_required:)
+      h = node.to_h.dup
+      details = []
+      details << "required" if include_required && node.required?
+      details << "default: #{value(node.default)}" if node.default
+      details << "enum: #{node.enum.map { value(_1) }.join(" | ")}" if node.enum
+      details << "const: #{value(node.const)}" if node.const
+      h.except(:type, :description, :default, :enum, :const, :required, :properties, :items, :anyOf, :oneOf, :allOf)
+        .each { |key, val| details << "#{key}: #{value(val)}" }
+      details
+    end
+
+    ##
+    # Convert a scalar value into its printable representation.
+    # @param [Object] val
+    #  The value to render
+    # @return [String]
+    def value(val)
+      case val
+      when ::String then val.inspect
+      else val.to_s
+      end
+    end
+  end
+end

data/lib/llm/schema.rb

@@ -34,6 +34,7 @@
 class LLM::Schema
   require_relative "schema/version"
   require_relative "schema/parser"
+  require_relative "schema/renderer"
   require_relative "schema/leaf"
   require_relative "schema/object"
   require_relative "schema/array"
@@ -121,6 +122,19 @@ class LLM::Schema
     end
   end
 
+  ##
+  # @param [Hash] defaults
+  # @return [LLM::Schema::Object]
+  def self.defaults(defaults)
+    lock do
+      object.tap do |schema|
+        defaults.each do |name, val|
+          Utils.fetch(schema.properties, name).default(val)
+        end
+      end
+    end
+  end
+
   ##
   # @api private
   # @return [LLM::Schema]
@@ -139,6 +153,14 @@ class LLM::Schema
     end
   end
 
+  ##
+  # Render the schema as a prompt-friendly string.
+  # @return [String]
+  def self.to_s
+    Renderer.render(object, root: true)
+  end
+  (class << self; self; end).alias_method(:inspect, :to_s)
+
   ##
   # @api private
   def self.lock(&)
@@ -220,4 +242,12 @@ class LLM::Schema
   def null
     Null.new
   end
+
+  ##
+  # Render a schema leaf as a prompt-friendly string.
+  # @return [String]
+  def to_s
+    self.class.to_s
+  end
+  alias_method :inspect, :to_s
 end

data/lib/llm/sequel/agent.rb

@@ -7,8 +7,7 @@ module LLM::Sequel
   # This wrapper reuses the same record-backed runtime surface as
   # {LLM::Sequel::Plugin}, but builds an {LLM::Agent LLM::Agent} instead of an
   # {LLM::Context LLM::Context}. Agent defaults such as model, tools, schema,
-  # instructions, and concurrency are configured on the model class and
-  # forwarded to an internal agent subclass.
+  # instructions, and concurrency are configured on an internal agent subclass.
   module Agent
     require_relative "plugin"
     EMPTY_HASH = LLM::Sequel::Plugin::EMPTY_HASH
@@ -25,7 +24,7 @@ module LLM::Sequel
       options = DEFAULTS.merge(options)
       model.db.extension :pg_json if %i[json jsonb].include?(options[:format])
       model.instance_variable_set(:@llm_agent_options, options.freeze)
-      model.instance_exec(&block) if block
+      block_given? ? model.instance_exec(model.agent, &block) : nil
     end
 
     module ClassMethods
@@ -33,46 +32,6 @@ module LLM::Sequel
         @llm_agent_options || Agent::DEFAULTS
       end
 
-      def model(model = nil, &block)
-        return agent.model if model.nil? && !block
-        agent.model(model, &block)
-      end
-
-      def tools(*tools, &block)
-        return agent.tools if tools.empty? && !block
-        agent.tools(*tools, &block)
-      end
-
-      def skills(*skills, &block)
-        return agent.skills if skills.empty? && !block
-        agent.skills(*skills, &block)
-      end
-
-      def schema(schema = nil, &block)
-        return agent.schema if schema.nil? && !block
-        agent.schema(schema, &block)
-      end
-
-      def instructions(instructions = nil)
-        return agent.instructions if instructions.nil?
-        agent.instructions(instructions)
-      end
-
-      def concurrency(concurrency = nil)
-        return agent.concurrency if concurrency.nil?
-        agent.concurrency(concurrency)
-      end
-
-      def confirm(*tool_names, &block)
-        return agent.confirm if tool_names.empty? && !block
-        agent.confirm(*tool_names, &block)
-      end
-
-      def tracer(tracer = nil, &block)
-        return agent.tracer if tracer.nil? && !block
-        agent.tracer(tracer, &block)
-      end
-
       def agent
         @agent ||= Class.new(LLM::Agent)
       end

data/lib/llm/sequel/plugin.rb

@@ -16,6 +16,13 @@ module LLM::Sequel
   # JSON typecasting for the model. `provider:`, `context:`, and `tracer:`
   # can also be configured as symbols that are called on the model.
   module Plugin
+    DEFAULTS = {
+      data_column: :data,
+      format: :string,
+      provider: :set_provider,
+      context: :set_context,
+      tracer: :set_tracer
+    }.freeze
     EMPTY_HASH = {}.freeze
 
     ##
@@ -94,13 +101,6 @@ module LLM::Sequel
         end
       end
     end
-    DEFAULTS = {
-      data_column: :data,
-      format: :string,
-      tracer: nil,
-      provider: nil,
-      context: EMPTY_HASH
-    }.freeze
 
     ##
     # Called by Sequel when the plugin is first applied to a model class.
@@ -304,6 +304,24 @@ module LLM::Sequel
 
     private
 
+    ##
+    # @return [LLM::Provider]
+    def set_provider
+      raise NotImplementedError, "implement the set_provider callback"
+    end
+
+    ##
+    # @return [Hash]
+    def set_context
+      Plugin::EMPTY_HASH.dup
+    end
+
+    ##
+    # @return [LLM::Tracer]
+    def set_tracer
+      nil
+    end
+
     ##
     # @return [LLM::Context]
     def ctx

data/lib/llm/stream.rb

@@ -15,7 +15,7 @@ module LLM
   #   therefore block streaming progress and should generally return as
   #   quickly as possible.
   #
-  # The most common callback is {#on_content}, which also maps to {#<<}.
+  # The most common callback is {#on_content}, which also maps to `#<<`.
   # Providers may also call {#on_reasoning_content} and {#on_tool_call} when
   # that data is available. Runtime features such as context compaction may
   # also emit lifecycle callbacks like {#on_transform} or {#on_compaction}.

data/lib/llm/tool.rb

@@ -63,7 +63,7 @@ class LLM::Tool
   ##
   # @param [LLM::A2A] a2a
   #  The A2A client that will execute the tool call
-  # @param [LLM::A2A::Card::Skill]
+  # @param [LLM::A2A::Card::Skill] skill
   #  An A2A tool
   # @return [Class<LLM::Tool>]
   #  Returns a subclass of LLM::Tool
@@ -124,7 +124,7 @@ class LLM::Tool
 
   ##
   # Registers the tool as a function when inherited
-  # @param [Class] klass The subclass
+  # @param [Class] tool The subclass
   # @return [void]
   def self.inherited(tool)
     LLM.lock(:inherited) do

data/lib/llm/tracer/telemetry.rb

@@ -30,8 +30,7 @@ module LLM
   #   require "llm"
   #   require "opentelemetry-exporter-otlp"
   #
-  #   endpoint = "https://api.smith.langchain.com/otel/v1/traces"
-  #   exporter = OpenTelemetry::Exporter::OTLP::Exporter.new(endpoint:)
+  #   exporter = OpenTelemetry::Exporter::OTLP::Exporter.new
   #
   #   llm = LLM.openai(key: ENV["KEY"])
   #   llm.tracer = LLM::Tracer::Telemetry.new(llm, exporter:)
@@ -59,7 +58,6 @@ module LLM
     # @return [self]
     def start_trace(trace_group_id: nil, name: "llm", attributes: {}, metadata: nil)
       return self if trace_group_id.to_s.empty?
-
       span_context = span_context_from_trace_group_id(trace_group_id.to_s)
       parent_ctx = ::OpenTelemetry::Trace.context_with_span(
         ::OpenTelemetry::Trace.non_recording_span(span_context)
@@ -316,7 +314,7 @@ module LLM
       set_span_attributes(span, consume_extra_outputs.merge(outputs || {}))
       finish_metadata = consume_finish_metadata_proc(res)
       metadata = (metadata || {}).merge(finish_metadata || {})
-      set_span_attributes(span, metadata.transform_keys { "langsmith.metadata.#{_1}" })
+      set_span_attributes(span, metadata.transform_keys { "llm.metadata.#{_1}" })
       span.add_event("gen_ai.request.finish")
       span.tap(&:finish)
     end
@@ -326,7 +324,7 @@ module LLM
         "gen_ai.operation.name" => operation
       }.merge!(finish_attributes(operation, res)).compact
       chunks_json = retrieval_chunks_json(res)
-      attributes["langsmith.metadata.chunks"] = chunks_json if chunks_json
+      attributes["llm.metadata.chunks"] = chunks_json if chunks_json
       attributes.each { span.set_attribute(_1, _2) }
       span.add_event("gen_ai.request.finish")
       span.tap(&:finish)
@@ -334,7 +332,7 @@ module LLM
 
     ##
     # @api private
-    # Serialize retrieval response chunks for span attributes (e.g. langsmith.metadata.chunks).
+    # Serialize retrieval response chunks for span attributes.
     # Returns a JSON string or nil when res has no data.
     def consume_finish_metadata_proc(res)
       key = LLM::Tracer::FINISH_METADATA_PROC_KEY

data/lib/llm/tracer.rb

@@ -11,7 +11,6 @@ module LLM
   class Tracer
     require_relative "tracer/logger"
     require_relative "tracer/telemetry"
-    require_relative "tracer/langsmith"
     require_relative "tracer/null"
 
     ##
@@ -45,7 +44,7 @@ module LLM
     # @param [Object, nil] span
     # @param [String] model
     # @param [Hash, nil] outputs Optional span attributes (e.g. gen_ai.output.messages) from llm.rb or caller.
-    # @param [Hash, nil] metadata Optional metadata (emitted as langsmith.metadata.*) from llm.rb or caller.
+    # @param [Hash, nil] metadata Optional metadata from llm.rb or caller.
     # @return [void]
     def on_request_finish(operation:, res:, model: nil, span: nil, outputs: nil, metadata: nil)
       raise NotImplementedError, "#{self.class} does not implement '#{__method__}'"
@@ -110,8 +109,7 @@ module LLM
     # @param [Hash] attributes
     #  OpenTelemetry attributes to set on the root span.
     # @param [Hash, nil] metadata
-    #  Optional. Trace-level metadata merged into the trace (e.g. langsmith.metadata.*).
-    #  Only used by tracers that support it (e.g. {LLM::Tracer::Langsmith}).
+    #  Optional. Trace-level metadata merged into the trace by tracers that support it.
     # @return [self]
     def start_trace(trace_group_id: nil, name: "llm", attributes: {}, metadata: nil)
       self
@@ -150,11 +148,10 @@ 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 fiber-local storage and emits them as langsmith/GenAI attributes.
+    # span or to the trace. No-op by default.
     #
     # @param [Hash, nil] metadata
-    #  Key-value pairs merged into trace/span metadata (e.g. langsmith.metadata.*).
+    #  Key-value pairs merged into trace/span metadata.
     # @param [Hash, nil] inputs
     #  Key-value pairs set on the next span at start (e.g. gen_ai.input.messages).
     #  Consumed when the span is created.
@@ -169,9 +166,9 @@ module LLM
     ##
     # Optional: set a proc to supply metadata when the next chat span finishes.
     # The proc is called with the response (res) and should return a Hash of
-    # metadata (e.g. { intent: "...", confidence: 1.0 }) to merge onto the span
-    # as langsmith.metadata.*. Cleared after use. Used by apps to attach
-    # routing/intent that is only known after the response.
+    # metadata (e.g. { intent: "...", confidence: 1.0 }) to merge onto the span.
+    # Cleared after use. Used by apps to attach routing/intent that is only
+    # known after the response.
     #
     # @param [Proc, nil] proc (res) -> Hash or nil
     # @return [self]
@@ -182,19 +179,10 @@ module LLM
 
     FINISH_METADATA_PROC_KEY = :"llm.tracer.finish_metadata_proc"
 
-    ##
-    # Returns the current extra bag (metadata, inputs, outputs) for the current
-    # thread/trace. Used by subclasses; default returns empty hashes.
-    #
-    # @return [Hash] { metadata: {}, inputs: {}, outputs: {} }
-    def current_extra
-      {}
-    end
-
     ##
     # 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 fiber-local inputs; default returns {}.
+    # tracer when starting a span. Subclasses can override to return stored
+    # inputs; default returns {}.
     #
     # @return [Hash] Attribute key => value to set on the span at start
     def consume_extra_inputs

data/lib/llm/transport/execution.rb

@@ -59,9 +59,24 @@ class LLM::Transport
     # @return [LLM::Object, String]
     def parse_response(res)
       case res["content-type"]
-      when %r{\Aapplication/json\s*} then LLM::Object.from(LLM.json.load(res.body))
+      when %r{\Aapplication/json\s*}
+        body = read_body(res.body)
+        LLM::Object.from(LLM.json.load(body))
       else res.body
       end
     end
+
+    ##
+    # @param [#class] body
+    # @return [String]
+    def read_body(body)
+      case body.class.to_s
+      when "Net::ReadAdapter"
+        str = +""
+        body.read_body { str << _1 }
+        str
+      else body
+      end
+    end
   end
 end

data/lib/llm/transport/http.rb

@@ -5,7 +5,7 @@ require "net/http"
 class LLM::Transport
   ##
   # The {LLM::Transport::HTTP LLM::Transport::HTTP} transport is the
-  # built-in adapter for Ruby's {Net::HTTP Net::HTTP}. It manages
+  # built-in adapter for Ruby's `Net::HTTP`. It manages
   # transient HTTP connections, tracks active requests by owner, and
   # interrupts in-flight requests when needed.
   #
@@ -69,7 +69,7 @@ class LLM::Transport
 
     ##
     # Performs a request on the current HTTP transport.
-    # Accepts both {Net::HTTPRequest} and {LLM::Transport::Request}.
+    # Accepts both `Net::HTTPRequest` and {LLM::Transport::Request}.
     #
     # @param [Net::HTTPRequest, LLM::Transport::Request] request
     # @param [Fiber] owner