ruby_llm 2.0.0 → 2.1.0

data/lib/ruby_llm/models.rb

@@ -16,15 +16,18 @@ module RubyLLM
   # Models.find delegate to the global registry.
   class Models
     include Enumerable
+    include Lookup
 
     MODELS_DEV_PROVIDER_MAP = { # :nodoc:
       'openai' => 'openai',
       'anthropic' => 'anthropic',
+      'azure' => 'azure',
       'google' => 'gemini',
       'google-vertex' => 'vertexai',
       'amazon-bedrock' => 'bedrock',
       'cohere' => 'cohere',
       'deepseek' => 'deepseek',
+      'hetzner' => 'hetzner',
       'mistral' => 'mistral',
       'ollama-cloud' => 'ollama_cloud',
       'openrouter' => 'openrouter',
@@ -33,24 +36,11 @@ module RubyLLM
       'xai' => 'xai'
     }.freeze
     MODELS_DEV_INPUT_MODALITIES = %w[text image audio pdf video file].freeze # :nodoc:
-    MODELS_DEV_OUTPUT_MODALITIES = %w[text image audio video embeddings moderation rerank].freeze # :nodoc:
+    MODELS_DEV_OUTPUT_MODALITIES = %w[text image audio video embeddings moderation rerank judgment].freeze # :nodoc:
     # First-party providers outrank the aggregators that resell their models.
     PROVIDER_PREFERENCE = %w[
-      openai
-      anthropic
-      gemini
-      deepseek
-      mistral
-      cohere
-      perplexity
-      xai
-      vertexai
-      bedrock
-      openrouter
-      azure
-      ollama_cloud
-      ollama
-      gpustack
+      openai anthropic gemini deepseek mistral cohere typesafe perplexity xai
+      vertexai bedrock openrouter azure hetzner ollama_cloud ollama gpustack
     ].freeze # :nodoc:
     INSTANCE_DELEGATES = (Enumerable.instance_methods(false) + %i[
       all
@@ -68,6 +58,8 @@ module RubyLLM
       load_from_store
       save_to_json
     ]).uniq.freeze # :nodoc:
+    INSTANCE_LOCK = Mutex.new
+    private_constant :INSTANCE_LOCK
 
     class << self
       # The providers whose model list could not be fetched during the last
@@ -82,7 +74,7 @@ module RubyLLM
       end
 
       def instance # :nodoc:
-        @instance ||= new
+        @instance || INSTANCE_LOCK.synchronize { @instance ||= new }
       end
 
       def bundled_registry_file # :nodoc:
@@ -229,7 +221,7 @@ module RubyLLM
 
         connection = Transport::Connection.basic do |f|
           f.request :json
-          f.response :json, parser_options: { symbolize_names: true }
+          f.use Transport::JsonResponse, parser_options: { symbolize_names: true }
         end
         { models: parse_models_dev_catalog(connection.get('https://models.dev/api.json').body), fetched: true }
       rescue StandardError => e
@@ -540,7 +532,7 @@ module RubyLLM
     # :startdoc:
 
     def initialize(models = nil) # :nodoc:
-      @models = models || self.class.load_models
+      replace_models(models || self.class.load_models)
     end
 
     # Replaces the models in this registry with those read from the JSON
@@ -548,7 +540,7 @@ module RubyLLM
     # <tt>RubyLLM.config.model_registry_file</tt>. A missing or invalid
     # file falls back to the registry bundled with the gem.
     def load_from_json(file = RubyLLM.config.model_registry_file)
-      @models = self.class.models_from_file(file) || self.class.models_from_bundle
+      replace_models(self.class.models_from_file(file) || self.class.models_from_bundle)
       self
     end
 
@@ -558,7 +550,7 @@ module RubyLLM
       store = RubyLLM.config.model_registry_store
       raise ModelRegistryError, 'No model registry store is configured' unless store
 
-      @models = Array(store.read)
+      replace_models(Array(store.read))
       self
     end
 
@@ -680,14 +672,14 @@ module RubyLLM
         merged_models = self.class.merge_models(self.class.models_from_provider_gems, main_models)
         persisted_models = RubyLLM.config.model_registry_store ? merged_models : main_models
         persist_registry!(persisted_models, published:)
-        @models = stored_models || merged_models
+        replace_models(stored_models || merged_models)
         payload.merge!(model_count: all.size, not_modified: published.not_modified)
       end
       self
     end
 
     def refresh_from_providers(remote_only: false) # :nodoc:
-      @models = self.class.fetch_merged_models(remote_only: remote_only)
+      replace_models(self.class.fetch_merged_models(remote_only: remote_only))
       self
     end
 
@@ -697,6 +689,11 @@ module RubyLLM
 
     private
 
+    def replace_models(models)
+      @models = models.dup
+      @model_index = nil
+    end
+
     # Filters keep the unlisted entries so #find and #unlisted still see them
     # after a chain such as by_provider(:openai).unlisted.
     def select_models(&)
@@ -792,51 +789,5 @@ module RubyLLM
 
       store.respond_to?(:description) ? store.description : store.class.name
     end
-
-    def find_with_provider(model_id, provider, config = nil)
-      resolved_id = Aliases.resolve(model_id, provider)
-      resolved_id = resolve_provider_registry_id(resolved_id, provider, config)
-      all_including_unlisted.find { |m| m.id == resolved_id && m.provider == provider.to_s } ||
-        all_including_unlisted.find { |m| m.id == model_id && m.provider == provider.to_s } ||
-        raise_model_not_found(model_id, provider: provider)
-    end
-
-    def resolve_provider_registry_id(model_id, provider, config = nil)
-      provider_class = Provider.resolve(provider)
-      return model_id unless provider_class
-
-      provider_class.resolve_registry_id(model_id, self, config || RubyLLM.config)
-    end
-
-    # A name can be one provider's exact id and another's alias:
-    # claude-opus-4 is exact on vertexai, an alias on anthropic.
-    # Provider preference settles it, not the kind of match.
-    def find_without_provider(model_id)
-      resolved_id = Aliases.resolve(model_id)
-      matches = all_including_unlisted.select { |m| [model_id, resolved_id].include?(m.id) }
-                                      .sort_by { |m| m.id == model_id ? 0 : 1 }
-
-      preferred_match(matches) || raise_model_not_found(model_id)
-    end
-
-    def raise_model_not_found(model_id, provider: nil)
-      message = "Unknown model: #{model_id.inspect}"
-      message = "#{message} for provider: #{provider.inspect}" if provider
-
-      raise ModelNotFoundError, "#{message}. #{refresh_registry_guidance}"
-    end
-
-    def refresh_registry_guidance
-      'If the model exists at the provider, refresh the registry with `RubyLLM.models.refresh`.'
-    end
-
-    def preferred_match(candidates)
-      return candidates.first if candidates.size == 1
-
-      candidates.min_by do |model|
-        index = PROVIDER_PREFERENCE.index(model.provider)
-        [model.unlisted? ? 1 : 0, index || PROVIDER_PREFERENCE.length]
-      end
-    end
   end
 end

data/lib/ruby_llm/moderation.rb

@@ -81,6 +81,8 @@ module RubyLLM
     # +model+ is not given. Pass +provider:+ and <tt>assume_model_exists: true</tt>
     # to use a model that is not in the registry. An explicitly selected
     # provider may instead use a configured resource without a model.
+    # +owner:+ attributes the usage to a record, such as a user, and wins
+    # over RubyLLM.with_usage_owner.
     #
     #   RubyLLM.moderate("User message")
     #   RubyLLM.moderate(["First comment", "Second comment"]).results
@@ -93,7 +95,8 @@ module RubyLLM
                       assume_model_exists: false,
                       context: nil,
                       provider_options: {},
-                      metadata: nil)
+                      metadata: nil,
+                      owner: nil)
       attachments = Attachment.wrap(with)
       raise ArgumentError, 'must provide input text, image attachment, or both' if input.nil? && attachments.empty?
 
@@ -116,7 +119,9 @@ module RubyLLM
       }
 
       RubyLLM.instrument('moderation.ruby_llm', payload, config: config) do |event|
-        result = provider_instance.moderate(input, model:, with: attachments, provider_options:)
+        result = Accounting::Usage.owned_by(owner) do
+          provider_instance.moderate(input, model:, with: attachments, provider_options:)
+        end
         event[:result] = result
         event[:flagged] = result.flagged?
         event[:tokens] = result.tokens

data/lib/ruby_llm/ocr.rb

@@ -41,6 +41,8 @@ module RubyLLM
     # the given zero-based page indexes. +provider_options:+ merges options
     # into the request in the provider's own vocabulary, such as Mistral's
     # +include_image_base64:+ or +table_format:+.
+    # +owner:+ attributes the usage to a record, such as a user, and wins
+    # over RubyLLM.with_usage_owner.
     #
     #   RubyLLM.ocr("report.pdf")
     #   RubyLLM.ocr("https://example.com/scan.png")
@@ -55,7 +57,8 @@ module RubyLLM
                  context: nil,
                  pages: nil,
                  provider_options: {},
-                 metadata: nil)
+                 metadata: nil,
+                 owner: nil)
       config = context&.config || RubyLLM.config
       model ||= config.default_ocr_model
       model, provider_instance = Models.resolve(model, provider: provider, assume_model_exists: assume_model_exists,
@@ -71,7 +74,9 @@ module RubyLLM
       }
 
       RubyLLM.instrument('ocr.ruby_llm', payload, config: config) do |event|
-        result = provider_instance.ocr(file, model:, pages:, provider_options:)
+        result = Accounting::Usage.owned_by(owner) do
+          provider_instance.ocr(file, model:, pages:, provider_options:)
+        end
         event[:result] = result
         event[:response_model] = result.model
         result

data/lib/ruby_llm/open_telemetry/attributes.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  class OpenTelemetry
+    module Attributes # :nodoc:
+      OPERATIONS = {
+        'chat.ruby_llm' => 'chat',
+        'embedding.ruby_llm' => 'embeddings',
+        'image.ruby_llm' => 'generate_content',
+        'speech.ruby_llm' => 'generate_content',
+        'transcription.ruby_llm' => 'transcription',
+        'ocr.ruby_llm' => 'ocr',
+        'rerank.ruby_llm' => 'rerank',
+        'moderation.ruby_llm' => 'moderation',
+        'judgment.ruby_llm' => 'judgment',
+        'tool_call.ruby_llm' => 'execute_tool',
+        'workflow.ruby_llm' => 'invoke_workflow',
+        'workflow_step.ruby_llm' => 'ruby_llm.workflow_step'
+      }.freeze
+      PROVIDERS = {
+        'bedrock' => 'aws.bedrock',
+        'azure' => 'azure.ai.openai',
+        'gemini' => 'gcp.gen_ai',
+        'vertexai' => 'gcp.vertex_ai',
+        'mistral' => 'mistral_ai',
+        'xai' => 'x_ai'
+      }.freeze
+      INTERNAL_OPERATIONS = %w[execute_tool invoke_workflow ruby_llm.workflow_step].freeze
+
+      module_function
+
+      def span_name(operation, payload)
+        target = case operation
+                 when 'execute_tool' then payload[:tool_name]
+                 when 'invoke_workflow' then payload[:workflow_name]
+                 when 'ruby_llm.workflow_step' then payload[:workflow_step_name]
+                 else payload[:model]
+                 end
+        [operation, target].compact.join(' ')
+      end
+
+      def span_kind(operation)
+        INTERNAL_OPERATIONS.include?(operation) ? :internal : :client
+      end
+
+      def request(operation, payload, event:)
+        return workflow(operation, payload) if %w[invoke_workflow ruby_llm.workflow_step].include?(operation)
+        return tool(payload) if operation == 'execute_tool'
+
+        {
+          'gen_ai.operation.name' => operation,
+          'gen_ai.provider.name' => PROVIDERS.fetch(payload[:provider], payload[:provider]),
+          'gen_ai.request.model' => payload[:model],
+          'gen_ai.request.temperature' => payload[:temperature],
+          'gen_ai.request.max_tokens' => payload[:max_output_tokens],
+          'gen_ai.request.stream' => (true if payload[:streaming]),
+          'gen_ai.embeddings.dimension.count' => payload[:dimensions],
+          'gen_ai.output.type' => output_type(event, payload)
+        }.compact
+      end
+
+      def output_type(event, payload)
+        return 'json' if payload[:schema]
+        return 'image' if event == 'image.ruby_llm'
+        return 'speech' if event == 'speech.ruby_llm'
+
+        nil
+      end
+
+      def response(payload)
+        response = payload[:response]
+        attributes = {
+          'gen_ai.response.model' => payload[:response_model],
+          'gen_ai.response.finish_reasons' => ([response.finish_reason.to_s] if response&.finish_reason)
+        }.compact
+        attributes.merge!(tokens(payload[:response_tokens] || payload[:tokens])) if payload[:tokens]
+        attributes
+      end
+
+      def tokens(tokens)
+        input = [tokens.input, tokens.cache_read, tokens.cache_write].compact
+        {
+          'gen_ai.usage.input_tokens' => (input.sum unless input.empty?),
+          'gen_ai.usage.output_tokens' => tokens.output,
+          'gen_ai.usage.cache_read.input_tokens' => tokens.cache_read,
+          'gen_ai.usage.cache_write.input_tokens' => tokens.cache_write,
+          'gen_ai.usage.reasoning.output_tokens' => tokens.thinking
+        }.compact
+      end
+
+      def tool(payload)
+        {
+          'gen_ai.operation.name' => 'execute_tool',
+          'gen_ai.tool.name' => payload[:tool_name],
+          'gen_ai.tool.call.id' => payload[:tool_call_id],
+          'gen_ai.tool.type' => 'function'
+        }.compact
+      end
+
+      def workflow(operation, payload)
+        {
+          'gen_ai.operation.name' => (operation unless operation == 'ruby_llm.workflow_step'),
+          'gen_ai.workflow.name' => payload[:workflow_name],
+          'ruby_llm.workflow.id' => payload[:workflow_id],
+          'ruby_llm.workflow.step.name' => payload[:workflow_step_name],
+          'ruby_llm.workflow.step.id' => payload[:workflow_step_id]
+        }.compact
+      end
+    end
+  end
+end

data/lib/ruby_llm/open_telemetry.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  # Optional OpenTelemetry tracing through RubyLLM's instrumentation events.
+  # Configure your application's SDK and exporters before calling .enable.
+  class OpenTelemetry
+    @mutex = Mutex.new
+
+    class << self
+      # Enables tracing without replacing the configured instrumenter.
+      # Requires the optional opentelemetry-api gem. Repeated calls are harmless.
+      # The application owns the tracer provider, SDK, and exporters.
+      def enable
+        require 'opentelemetry-api'
+        @mutex.synchronize do
+          @subscriber ||= new
+          Support::Instrumentation.subscribe(@subscriber)
+        end
+        nil
+      rescue LoadError
+        raise LoadError, "OpenTelemetry tracing requires the 'opentelemetry-api' gem. Add it to your Gemfile."
+      end
+
+      # Disables tracing for new operations without shutting down the SDK.
+      # Operations already running finish their spans normally.
+      def disable
+        @mutex.synchronize { Support::Instrumentation.unsubscribe(@subscriber) if @subscriber }
+        nil
+      end
+    end
+
+    def instrument(name, payload) # :nodoc:
+      operation = Attributes::OPERATIONS[name]
+      return yield unless operation
+
+      span = safely do
+        tracer.start_span(Attributes.span_name(operation, payload),
+                          kind: Attributes.span_kind(operation),
+                          attributes: Attributes.request(operation, payload, event: name))
+      end
+      return yield unless span
+
+      ::OpenTelemetry::Trace.with_span(span) do
+        yield
+      rescue StandardError => e
+        record_error(span, e)
+        raise
+      ensure
+        safely { span.add_attributes(Attributes.response(payload)) }
+        safely { span.finish }
+      end
+    end
+
+    def capture_context # :nodoc:
+      ::OpenTelemetry::Context.current
+    end
+
+    def with_context(context, &) # :nodoc:
+      ::OpenTelemetry::Context.with_current(context, &)
+    end
+
+    private
+
+    def record_error(span, error)
+      safely do
+        span.set_attribute('error.type', error.class.name)
+        span.status = ::OpenTelemetry::Trace::Status.error
+      end
+    end
+
+    def tracer
+      ::OpenTelemetry.tracer_provider.tracer('ruby_llm', RubyLLM::VERSION)
+    end
+
+    def safely
+      yield
+    rescue StandardError => e
+      RubyLLM.logger.warn("OpenTelemetry instrumentation failed (#{e.class})")
+      nil
+    end
+  end
+end

data/lib/ruby_llm/probability.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  # The probability that a judgment's yes/no question is true.
+  class Probability
+    include Support::Inspectable
+
+    # Returns the probability of yes, between 0 and 1.
+    attr_reader :probability
+
+    def initialize(probability:) # :nodoc:
+      @probability = probability
+      freeze
+    end
+
+    # Returns :probability.
+    def type
+      :probability
+    end
+
+    # Returns the answer as a Hash.
+    def to_h
+      { type:, probability: }
+    end
+
+    def inspect_attributes # :nodoc:
+      { probability: }
+    end
+  end
+end

data/lib/ruby_llm/progress.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  # Progress a tool or an MCP server reports while it works. A Tool reports
+  # it with Tool#progress; Chat#after_tool_progress and MCP.after_progress
+  # callbacks receive it.
+  #
+  #   chat.after_tool_progress do |tool_call, progress|
+  #     puts "#{tool_call.name}: #{progress.message} #{progress.value}/#{progress.total}"
+  #   end
+  #
+  class Progress
+    include Support::Inspectable
+
+    # How much work is done, or +nil+ when only a message was reported. It
+    # only grows, but its unit is the reporter's.
+    attr_reader :value
+
+    # How much work there is in total, or +nil+ when the reporter does not
+    # know.
+    attr_reader :total
+
+    # What the tool or server is doing, or +nil+.
+    attr_reader :message
+
+    def initialize(value: nil, total: nil, message: nil) # :nodoc:
+      @value = value
+      @total = total
+      @message = message
+    end
+
+    # Returns the share of work done, from 0.0 to 1.0, or +nil+ without a
+    # value and a total.
+    def fraction
+      value.to_f / total if value && total&.positive?
+    end
+
+    private
+
+    def inspect_attributes
+      { value:, total:, message: }
+    end
+  end
+end

data/lib/ruby_llm/prompt/context.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+# The object a prompt template is evaluated in. Locals become local
+# variables of the template, and +render+ inserts a partial.
+#
+# The class is declared with its full name so the template binding has no
+# RubyLLM lexical scope: +Chat+ in a template is the application's model,
+# not RubyLLM::Chat.
+class RubyLLM::Prompt::Context # rubocop:disable Style/ClassAndModuleChildren
+  LOCAL_VARIABLE_NAME = /\A(?![A-Z0-9])(?:[[:alnum:]_]|[^\0-\177])+\z/
+  private_constant :LOCAL_VARIABLE_NAME
+
+  # Returns the locals passed to the current prompt or partial. Use it to
+  # read an optional local, or a local whose name is not a valid Ruby
+  # variable name:
+  #
+  #   <% if local_assigns[:product_name] %>
+  #
+  attr_reader :local_assigns
+
+  def initialize(prompt, local_assigns) # :nodoc:
+    @prompt = prompt
+    @local_assigns = local_assigns
+  end
+
+  # Renders a partial with locals. A bare name is looked up next to the
+  # current prompt only. A name with a path is looked up in the prompt roots.
+  #
+  #   <%= render "tone" %>
+  #   <%= render "shared/safety", product_name: product_name %>
+  #   <%= render partial: "shared/safety", locals: { product_name: product_name } %>
+  #
+  def render(options = {}, locals = {})
+    return partial(options).render(**locals) unless options.is_a?(Hash)
+
+    partial(options.fetch(:partial)).render(**(options[:locals] || {}))
+  end
+
+  def scope # :nodoc:
+    @local_assigns.each_with_object(binding) do |(name, value), scope|
+      scope.local_variable_set(name, value) if name.to_s.match?(LOCAL_VARIABLE_NAME)
+    end
+  end
+
+  private
+
+  def partial(name)
+    name = name.to_s
+    partial = name.sub(%r{([^/]+)\z}, '_\\1')
+    directory = File.dirname(@prompt.name)
+    return RubyLLM::Prompt.new(partial) if name.include?('/') || directory == '.'
+
+    RubyLLM::Prompt.new("#{directory}/#{partial}")
+  end
+end

data/lib/ruby_llm/prompt.rb

@@ -50,7 +50,7 @@ module RubyLLM
     def render(**locals) # :nodoc:
       raise PromptNotFoundError, "Prompt file not found: #{path}" unless File.exist?(path)
 
-      ERB.new(File.read(path)).result_with_hash(locals)
+      ERB.new(File.read(path)).result(Context.new(self, locals).scope)
     end
 
     def self.render(name, **locals) # :nodoc:

data/lib/ruby_llm/protocol/binary_streaming.rb

@@ -8,7 +8,7 @@ module RubyLLM
         fallback = Streaming::StreamState.new
         on_data = binary_on_data(fallback, progress, &)
 
-        response = @connection.post(url, payload, usage: @usage_tracker) do |request|
+        response = @connection.post(url, payload, usage: @usage_tracker, stream: true) do |request|
           (request.options.context ||= {})[Transport::Connection::STREAM_PROGRESS_KEY] = progress
           if faraday_1?
             request.options[:on_data] = on_data