ruby_llm 1.16.0 → 2.0.0.rc2

data/lib/ruby_llm/chunk.rb

@@ -1,6 +1,16 @@
 # frozen_string_literal: true
 
 module RubyLLM
+  # A Chunk is one streamed fragment of an assistant response. Chunks are
+  # yielded to the block passed to Chat#ask or Chat#complete when streaming.
+  # A Chunk is a Message, so it responds to the same readers, but it holds
+  # only the data received in that part of the stream, such as a piece of
+  # content, partial tool calls, or the finish reason on the final chunk.
+  #
+  #   chat.ask "Write a haiku about Ruby" do |chunk|
+  #     print chunk.content
+  #   end
+  #
   class Chunk < Message
   end
 end

data/lib/ruby_llm/citation.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  # A Citation links a span of generated text to the source material that
+  # supports it. Providers return citations in different shapes. RubyLLM
+  # normalizes all of them into Citation objects on Message#citations.
+  # Fields a provider does not report are +nil+.
+  #
+  #   chat = RubyLLM.chat(model: 'claude-sonnet-5').with_citations
+  #   response = chat.ask "Who created Ruby?", with: "facts.txt"
+  #
+  #   response.citations.each do |citation|
+  #     citation.title      # => "facts.txt"
+  #     citation.cited_text # => the quoted passage from facts.txt
+  #     citation.text       # => the span of the answer it supports
+  #   end
+  #
+  class Citation
+    include Support::Inspectable
+
+    # The URL of the cited source, when citing the web, or +nil+.
+    attr_reader :url
+
+    # The title or filename of the cited source, or +nil+.
+    attr_reader :title
+
+    # The quoted snippet from the source material, or +nil+.
+    attr_reader :cited_text
+
+    # The span of the response content this citation supports, or +nil+.
+    attr_reader :text
+
+    # The character offset where the cited span starts in the response
+    # content, or +nil+.
+    #
+    #   response.content[citation.start_index...citation.end_index] == citation.text # => true
+    #
+    attr_reader :start_index
+
+    # The character offset where the cited span ends in the response
+    # content, or +nil+.
+    attr_reader :end_index
+
+    # The provider's identifier for the cited source, or +nil+.
+    attr_reader :source_id
+
+    # The 0-indexed position of the source document or search result,
+    # or +nil+.
+    attr_reader :source_index
+
+    # The first page of a PDF citation (1-indexed, inclusive), or +nil+.
+    attr_reader :start_page
+
+    # The last page of a PDF citation (1-indexed, inclusive), or +nil+.
+    attr_reader :end_page
+
+    def initialize(options = {}) # :nodoc:
+      @url = options[:url]
+      @title = options[:title]
+      @cited_text = options[:cited_text]
+      @text = options[:text]
+      @start_index = options[:start_index]
+      @end_index = options[:end_index]
+      @source_id = options[:source_id]
+      @source_index = options[:source_index]
+      @start_page = options[:start_page]
+      @end_page = options[:end_page]
+    end
+
+    def self.from_h(data) # :nodoc:
+      new(Support::Utils.deep_symbolize_keys(data))
+    end
+
+    def inspect_attributes # :nodoc:
+      { url: url, title: title, start_index: start_index, end_index: end_index }
+    end
+
+    # Returns the citation as a Hash with symbol keys, omitting +nil+ fields.
+    def to_h
+      {
+        url: url,
+        title: title,
+        cited_text: cited_text,
+        text: text,
+        start_index: start_index,
+        end_index: end_index,
+        source_id: source_id,
+        source_index: source_index,
+        start_page: start_page,
+        end_page: end_page
+      }.compact
+    end
+
+    # Returns +true+ if +other+ is a Citation with the same attributes,
+    # +false+ otherwise.
+    def ==(other)
+      other.is_a?(Citation) && to_h == other.to_h
+    end
+    alias eql? == # :nodoc:
+
+    def hash # :nodoc:
+      to_h.hash
+    end
+  end
+end

data/lib/ruby_llm/configuration.rb

@@ -3,11 +3,29 @@
 require 'logger'
 
 module RubyLLM
-  # Global configuration for RubyLLM
+  # A Configuration holds every RubyLLM setting: provider credentials,
+  # default models, timeouts, retries, logging, and the model registry.
+  # The global instance is yielded by RubyLLM.configure and available as
+  # RubyLLM.config.
+  #
+  #   RubyLLM.configure do |config|
+  #     config.openai_api_key = ENV['OPENAI_API_KEY']
+  #     config.anthropic_api_key = ENV['ANTHROPIC_API_KEY']
+  #   end
+  #
+  # RubyLLM.context yields an isolated copy for per-request or per-tenant
+  # overrides.
+  #
+  # Provider credentials such as +openai_api_key+ are declared by each
+  # provider. See https://rubyllm.com/next/configuration-providers/ for
+  # provider credentials and endpoint settings.
+  #
+  # Assigning an empty or whitespace-only string to any option stores
+  # +nil+, so unset environment variables behave as if the option was
+  # never set.
   class Configuration
     class << self
-      # Declare a single configuration option.
-      def option(key, default = nil)
+      def option(key, default = nil) # :nodoc:
         key = key.to_sym
         return if options.include?(key)
 
@@ -22,10 +40,12 @@ module RubyLLM
         defaults[key] = default
       end
 
-      def register_provider_options(options)
+      def register_provider_options(options) # :nodoc:
         Array(options).each { |key| option(key, nil) }
       end
 
+      # Returns the names of all declared options as an array of symbols,
+      # including options registered by providers.
       def options
         option_keys.dup
       end
@@ -40,55 +60,272 @@ module RubyLLM
     # System-level options are declared here.
     # Provider-specific options are declared in each provider class via
     # `self.configuration_options` and registered through Provider.register.
-    option :default_model, 'gpt-5.4'
+
+    ##
+    # :attr_accessor: default_model
+    #
+    # The model id used by RubyLLM.chat when no model is given.
+    # Default: <tt>'gpt-5.6'</tt>.
+    option :default_model, 'gpt-5.6'
+
+    ##
+    # :attr_accessor: default_embedding_model
+    #
+    # The model id used by RubyLLM.embed when no model is given.
+    # Default: <tt>'text-embedding-3-small'</tt>.
     option :default_embedding_model, 'text-embedding-3-small'
+
+    ##
+    # :attr_accessor: default_moderation_model
+    #
+    # The model id used by RubyLLM.moderate when no model is given.
+    # Default: <tt>'omni-moderation-latest'</tt>.
     option :default_moderation_model, 'omni-moderation-latest'
-    option :default_image_model, 'gpt-image-1.5'
-    option :default_transcription_model, 'whisper-1'
 
-    option :model_registry_file, -> { File.expand_path('models.json', __dir__) }
-    option :model_registry_class, 'Model'
+    ##
+    # :attr_accessor: default_image_model
+    #
+    # The model id used by RubyLLM.paint when no model is given.
+    # Default: <tt>'gpt-image-2'</tt>.
+    option :default_image_model, 'gpt-image-2'
+
+    ##
+    # :attr_accessor: default_speech_model
+    #
+    # The model id used by RubyLLM.speak when no model is given.
+    # Default: <tt>'gpt-4o-mini-tts-2025-12-15'</tt>.
+    option :default_speech_model, 'gpt-4o-mini-tts-2025-12-15'
+
+    ##
+    # :attr_accessor: default_transcription_model
+    #
+    # The model id used by RubyLLM.transcribe when no model is given.
+    # Default: <tt>'gpt-transcribe'</tt>.
+    option :default_transcription_model, 'gpt-transcribe'
+
+    ##
+    # :attr_accessor: default_ocr_model
+    #
+    # The model id used by RubyLLM.ocr when no model is given.
+    # Default: <tt>'mistral-ocr-latest'</tt>.
+    option :default_ocr_model, 'mistral-ocr-latest'
+
+    ##
+    # :attr_accessor: default_video_model
+    #
+    # The model id used by RubyLLM.animate when no model is given.
+    # Default: <tt>'grok-imagine-video-1.5'</tt>.
+    option :default_video_model, 'grok-imagine-video-1.5'
+
+    ##
+    # :attr_accessor: video_generation_timeout
+    #
+    # Seconds RubyLLM.animate waits for a video job to finish before
+    # raising an error. Default: 600.
+    option :video_generation_timeout, 600
+
+    ##
+    # :attr_accessor: video_generation_poll_interval
+    #
+    # Seconds between status polls while RubyLLM.animate waits for a
+    # video job. Default: 5.
+    option :video_generation_poll_interval, 5
 
-    option :use_new_acts_as, false
-    option :model_registry_source, nil
+    ##
+    # :attr_accessor: model_registry_file
+    #
+    # Path of the writable JSON cache holding the model registry. Defaults
+    # to the operating system's user cache directory. The copy bundled with
+    # the gem is used until this file exists.
+    option :model_registry_file, -> { Models::Registry.cache_path }
 
+    ##
+    # :attr_accessor: model_registry_store
+    #
+    # Store object the model registry reads from and persists to. Rails
+    # apps using the acts_as helpers set this to the database store
+    # automatically. A store must respond to +read+, returning an array of
+    # Model entries, and may respond to +write(registry)+ to let
+    # Models#refresh persist. Default: +nil+ (use +model_registry_file+).
+    option :model_registry_store, nil
+
+    # Optional persistence adapter installed by the Rails integration.
+    option :batch_store, nil # :nodoc:
+
+    # Keeps custom 1.x initializers bootable long enough to run the 2.0
+    # upgrade generator. The registry is always RubyLLM-owned in 2.0.
+    def model_registry_class=(_value) # :nodoc:
+      RubyLLM.deprecator.warn(
+        'config.model_registry_class is ignored in RubyLLM 2.0; remove it from your initializer'
+      )
+    end
+
+    def use_new_acts_as=(_value) # :nodoc:
+      RubyLLM.deprecator.warn(
+        'config.use_new_acts_as is ignored in RubyLLM 2.0; remove it from your initializer'
+      )
+    end
+
+    ##
+    # :attr_accessor: request_timeout
+    #
+    # Seconds to wait for a response before timing out. Default: 300.
     option :request_timeout, 300
+
+    ##
+    # :attr_accessor: max_retries
+    #
+    # Number of times to retry failed requests. Default: 3.
     option :max_retries, 3
+
+    ##
+    # :attr_accessor: retry_interval
+    #
+    # Initial delay in seconds before the first retry. Default: 0.1.
     option :retry_interval, 0.1
+
+    ##
+    # :attr_accessor: retry_backoff_factor
+    #
+    # Multiplier applied to the retry delay after each attempt.
+    # Default: 2.
     option :retry_backoff_factor, 2
+
+    ##
+    # :attr_accessor: retry_interval_randomness
+    #
+    # Random jitter factor applied to retry delays. Default: 0.5.
     option :retry_interval_randomness, 0.5
+
+    ##
+    # :attr_accessor: retry_max_interval
+    #
+    # Longest delay in seconds to wait between retries, including delays
+    # requested by the provider through rate-limit headers. When a
+    # provider asks for a longer wait, the request fails immediately
+    # instead of sleeping. Default: 30.
+    option :retry_max_interval, 30
+
+    ##
+    # :attr_accessor: http_proxy
+    #
+    # Proxy URL for all requests, such as
+    # <tt>'http://proxy.example.com:8080'</tt>. HTTP, authenticated, and
+    # SOCKS5 proxies are supported. Default: +nil+.
     option :http_proxy, nil
+
+    ##
+    # :attr_accessor: tool_concurrency
+    #
+    # How chats run multiple tool calls from one response: +false+ for
+    # sequential execution, +true+ or +:threads+ for threads, +:fibers+
+    # for fibers via the async gem. Default: +false+.
     option :tool_concurrency, false
 
+    ##
+    # :attr_accessor: auto_upload_large_files
+    #
+    # Whether oversized local attachments are uploaded to provider file
+    # storage automatically. Default: +true+.
+    option :auto_upload_large_files, true
+
+    ##
+    # :attr_accessor: logger
+    #
+    # Logger receiving RubyLLM output. When set, it overrides #log_file
+    # and #log_level. Default: +nil+.
     option :logger, nil
+
+    ##
+    # :attr_accessor: instrumenter
+    #
+    # Object receiving instrumentation events. It must respond to
+    # <tt>instrument(name, payload)</tt> and accept an optional block,
+    # like ActiveSupport::Notifications, which Rails apps use
+    # automatically. Default: +nil+.
     option :instrumenter, nil
+
+    ##
+    # :attr_accessor: deprecation_behavior
+    #
+    # How deprecation warnings are handled: +:warn+, +:silence+, or
+    # +:raise+. Default: +:warn+.
     option :deprecation_behavior, :warn
+
+    ##
+    # :attr_accessor: faraday_adapter
+    #
+    # Faraday adapter used for HTTP requests. Default: +:net_http+.
     option :faraday_adapter, :net_http
-    option :log_file, -> { $stdout }
-    option :log_level, -> { ENV['RUBYLLM_DEBUG'] ? Logger::DEBUG : Logger::INFO }
-    option :log_stream_debug, -> { ENV['RUBYLLM_STREAM_DEBUG'] == 'true' }
+
+    ##
+    # :attr_accessor: log_file
+    #
+    # Destination for the built-in logger, a path or an IO.
+    # Defaults to the +RUBYLLM_LOG_FILE+ environment variable when set,
+    # <tt>$stdout</tt> otherwise.
+    option :log_file, -> { ENV.fetch('RUBYLLM_LOG_FILE', nil) || $stdout }
+
+    ##
+    # :attr_accessor: log_level
+    #
+    # Severity of the built-in logger. Defaults to <tt>Logger::DEBUG</tt>
+    # when the +RUBYLLM_DEBUG+ environment variable says yes
+    # (<tt>true</tt>, <tt>1</tt>, <tt>yes</tt>, or <tt>on</tt>),
+    # <tt>Logger::INFO</tt> otherwise.
+    option :log_level, -> { env_says_yes?('RUBYLLM_DEBUG') ? Logger::DEBUG : Logger::INFO }
+
+    ##
+    # :attr_accessor: log_stream_debug
+    #
+    # Whether raw streaming chunks are logged. Defaults to +true+ when the
+    # +RUBYLLM_STREAM_DEBUG+ environment variable says yes, +false+
+    # otherwise.
+    option :log_stream_debug, -> { env_says_yes?('RUBYLLM_STREAM_DEBUG') }
+
+    ##
+    # :attr_accessor: log_regexp_timeout
+    #
+    # Timeout in seconds for the regular expressions that scrub logged
+    # payloads. Defaults to the global <tt>Regexp.timeout</tt>, or 1.0
+    # when none is set. Requires Ruby 3.2 or later; on older Rubies
+    # setting a value logs a warning.
     option :log_regexp_timeout, -> { Regexp.respond_to?(:timeout) ? (Regexp.timeout || 1.0) : nil }
 
-    def initialize
+    def initialize # :nodoc:
       self.class.send(:defaults).each do |key, default|
         value = default.respond_to?(:call) ? instance_exec(&default) : default
         public_send("#{key}=", value)
       end
     end
 
-    def instance_variables
-      super.reject { |ivar| ivar.to_s.match?(/_id|_key|_secret|_token$/) }
+    def instance_variables # :nodoc:
+      super.reject { |ivar| ivar.to_s.match?(/(_id|_key|_secret|_token|_credential_provider)$/) }
+    end
+
+    # Object#inspect reads the instance variable table directly, so
+    # credentials only stay out of console and log output when #inspect is
+    # built from the redacted #instance_variables.
+    def inspect # :nodoc:
+      attributes = instance_variables.map { |ivar| "#{ivar}=#{instance_variable_get(ivar).inspect}" }
+      "#<#{self.class.name} #{attributes.join(', ')}>"
     end
 
-    def log_regexp_timeout=(value)
-      if value.nil?
-        @log_regexp_timeout = nil
-      elsif Regexp.respond_to?(:timeout)
-        @log_regexp_timeout = value
-      else
+    remove_method :log_regexp_timeout=
+    def log_regexp_timeout=(value) # :nodoc:
+      if value && !Regexp.respond_to?(:timeout)
         RubyLLM.logger.warn("log_regexp_timeout is not supported on Ruby #{RUBY_VERSION}")
-        @log_regexp_timeout = value
       end
+      @log_regexp_timeout = value
+    end
+
+    private
+
+    # Whether the +name+ environment variable is set to something that means
+    # yes, so that <tt>RUBYLLM_DEBUG=false</tt> reads as off rather than as
+    # merely set.
+    def env_says_yes?(name)
+      %w[true 1 yes on].include?(ENV[name].to_s.strip.downcase)
     end
   end
 end

data/lib/ruby_llm/context.rb

@@ -1,29 +1,151 @@
 # frozen_string_literal: true
 
 module RubyLLM
-  # Holds per-call configs
+  # A Context is an isolated configuration scope. It offers the same entry
+  # points as the top-level RubyLLM module but reads from its own
+  # Configuration copy instead of the global one, which suits multi-tenant
+  # applications and per-request overrides.
+  #
+  # Contexts are created with RubyLLM.context:
+  #
+  #   ctx = RubyLLM.context do |config|
+  #     config.openai_api_key = ENV.fetch('TENANT_OPENAI_API_KEY')
+  #     config.request_timeout = 180
+  #   end
+  #
+  #   ctx.chat.ask "Explain Ruby blocks."
+  #   ctx.paint("A paper boat in the rain").save("boat.png")
+  #   ctx.transcribe("meeting.wav").text
+  #
+  # The global configuration is left untouched.
+  #
+  # Batch submission uses each chat's own configuration (a chat carries
+  # the config it was built with), so there is no context entry point for
+  # it. To look up an existing batch, where no chats carry the config,
+  # pass a context to Batch.find:
+  #
+  #   RubyLLM::Batch.find(id, provider: :anthropic, context: ctx)
+  #
   class Context
-    attr_reader :config
+    attr_reader :config # :nodoc:
 
-    def initialize(config)
+    def initialize(config) # :nodoc:
       @config = config
-      @connections = {}
     end
 
+    # Creates a new Chat that uses this context's configuration.
+    # Accepts the same arguments as RubyLLM.chat.
     def chat(*args, **kwargs, &)
       Chat.new(*args, **kwargs, context: self, &)
     end
 
+    # Counts tokens using this context's configuration.
+    # Accepts the same arguments as RubyLLM.count_tokens.
+    def count_tokens(text, model: nil, provider: nil)
+      chat(model:, provider:).count_tokens(text)
+    end
+
+    # Tokenizes plain text using this context's configuration.
+    # Accepts the same arguments as RubyLLM.tokenize.
+    def tokenize(*args, **kwargs)
+      Tokenization.tokenize(*args, **kwargs, context: self)
+    end
+
+    # Runs a named workflow using this context's instrumenter. Accepts the same
+    # arguments as RubyLLM.workflow.
+    def workflow(name, id: nil, metadata: nil, &)
+      Workflow.new(name, id:, metadata:, config: config).run(&)
+    end
+
+    # Generates embeddings using this context's configuration.
+    # Accepts the same arguments as RubyLLM.embed.
     def embed(*args, **kwargs, &)
       Embedding.embed(*args, **kwargs, context: self, &)
     end
 
+    # Stages an embedding request using this context's configuration.
+    # Accepts the same arguments as RubyLLM.embed_later.
+    def embed_later(text, model: nil, provider: nil, dimensions: nil)
+      EmbeddingRequest.new(text, model:, provider:, dimensions:, context: self)
+    end
+
+    # Generates an image using this context's configuration.
+    # Accepts the same arguments as RubyLLM.paint.
     def paint(*args, **kwargs, &)
       Image.paint(*args, **kwargs, context: self, &)
     end
 
-    def connection_for(provider_instance)
-      provider_instance.connection
+    # Generates a video using this context's configuration, blocking
+    # until it is ready. Accepts the same arguments as RubyLLM.animate.
+    def animate(*args, **kwargs, &)
+      Video.animate(*args, **kwargs, context: self, &)
+    end
+
+    # Submits a video generation job using this context's configuration.
+    # Accepts the same arguments as RubyLLM.animate_later.
+    def animate_later(*args, **kwargs, &)
+      VideoJob.animate_later(*args, **kwargs, context: self, &)
+    end
+
+    # Runs content moderation using this context's configuration.
+    # Accepts the same arguments as RubyLLM.moderate.
+    def moderate(*args, **kwargs, &)
+      Moderation.moderate(*args, **kwargs, context: self, &)
+    end
+
+    # Runs hosted research using this context's configuration.
+    # Accepts the same arguments as RubyLLM.research.
+    def research(*args, **kwargs)
+      ResearchJob.research(*args, **kwargs, context: self)
+    end
+
+    # Submits hosted research using this context's configuration.
+    # Accepts the same arguments as RubyLLM.research_later.
+    def research_later(*args, **kwargs)
+      ResearchJob.research_later(*args, **kwargs, context: self)
+    end
+
+    # Generates speech audio using this context's configuration. Given a
+    # block, yields SpeechChunk objects and returns the complete Speech.
+    # Accepts the same arguments as RubyLLM.speak.
+    def speak(*args, **kwargs, &)
+      Speech.speak(*args, **kwargs, context: self, &)
+    end
+
+    # Transcribes audio using this context's configuration.
+    # Accepts the same arguments as RubyLLM.transcribe.
+    def transcribe(*args, **kwargs, &)
+      Transcription.transcribe(*args, **kwargs, context: self, &)
+    end
+
+    # Extracts document text using this context's configuration.
+    # Accepts the same arguments as RubyLLM.ocr.
+    def ocr(*args, **kwargs, &)
+      OCR.ocr(*args, **kwargs, context: self, &)
+    end
+
+    # Ranks documents using this context's configuration.
+    # Accepts the same arguments as RubyLLM.rerank.
+    def rerank(*args, **kwargs, &)
+      Rerank.rerank(*args, **kwargs, context: self, &)
+    end
+
+    # Uploads a file to a provider using this context's configuration.
+    # Accepts the same arguments as RubyLLM.upload.
+    def upload(*args, **kwargs, &)
+      UploadedFile.upload(*args, **kwargs, context: self, &)
+    end
+
+    # Downloads a provider-hosted file using this context's configuration.
+    # Accepts the same arguments as RubyLLM.download.
+    def download(*args, **kwargs, &)
+      UploadedFile.download(*args, **kwargs, context: self, &)
+    end
+
+    # Creates a provider-side prompt cache using this context's
+    # configuration. Accepts the same arguments as RubyLLM.cache.
+    def cache(*args, **kwargs, &)
+      CachedContent.create(*args, **kwargs, context: self, &)
     end
   end
 end