nitro_intelligence 4.0.0 → 4.1.1

data/lib/nitro_intelligence/client/observed.rb

@@ -1,5 +1,6 @@
 require "nitro_intelligence/client/handlers/observed/audio_transcription_handler"
 require "nitro_intelligence/client/handlers/observed/chat_handler"
+require "nitro_intelligence/client/handlers/observed/decision_handler"
 require "nitro_intelligence/client/handlers/observed/image_handler"
 require "nitro_intelligence/client/handlers/observed/text_to_speech_handler"
 require "nitro_intelligence/observability/prompt_store"
@@ -8,6 +9,7 @@ require "nitro_intelligence/trace"
 
 module NitroIntelligence
   module Client
+    # @api private
     class Observed < Base
       def initialize(client:, observer:)
         super(client:)
@@ -29,6 +31,12 @@ module NitroIntelligence
           )
       end
 
+      def decision_handler
+        @decision_handler ||= Handlers::Observed::DecisionHandler.new(
+          base_handler: Handlers::DecisionHandler.new(client: @client), observer: @observer
+        )
+      end
+
       def image_handler
         @image_handler ||= Handlers::Observed::ImageHandler.new(
           base_handler: Handlers::ImageHandler.new(client: @client), observer: @observer

data/lib/nitro_intelligence/client/observers/langfuse_observer.rb

@@ -1,6 +1,8 @@
 module NitroIntelligence
   module Client
+    # @api private
     module Observers
+      # @api private
       class LangfuseObserver
         # The inference gateway returns its own request identifier on every
         # response, including error responses. Recording it on the observation is
@@ -25,9 +27,10 @@ module NitroIntelligence
           seed = parameters[:trace_seed]
           trace_id = NitroIntelligence::Trace.create_id(seed:) if seed.present?
 
+          # Into the request's own parameters, so the gateway's spend metadata names the prompt too,
+          # without writing into a metadata hash the caller may pass again.
           if prompt
-            metadata[:prompt_name] = prompt.name
-            metadata[:prompt_version] = prompt.version
+            metadata = parameters[:metadata] = metadata.merge(prompt_name: prompt.name, prompt_version: prompt.version)
           end
 
           metadata = metadata.transform_values(&:to_s)
@@ -55,6 +58,10 @@ module NitroIntelligence
 
       private
 
+        def project
+          @project_client.project
+        end
+
         # Applied once the response is in hand, so the observation reflects what came
         # back rather than what was asked for. Each attribute is set only when the
         # handler supplied it: an observation that records nothing is better than one
@@ -65,7 +72,12 @@ module NitroIntelligence
         def record_result(generation, trace_attributes)
           return unless trace_attributes
 
-          handle_truncation(trace_attributes[:input], trace_attributes[:output], trace_attributes[:model])
+          trace_attributes = masked(trace_attributes)
+
+          # Truncation trims fields out of an output that a masked project does not record.
+          unless project.mask_content?
+            handle_truncation(trace_attributes[:input], trace_attributes[:output], trace_attributes[:model])
+          end
 
           RECORDED_ATTRIBUTES.each do |name|
             value = trace_attributes[name]
@@ -77,6 +89,15 @@ module NitroIntelligence
           generation.update_trace(input: trace_attributes[:input], output: trace_attributes[:output])
         end
 
+        def masked(trace_attributes)
+          return trace_attributes unless project.mask_content?
+
+          trace_attributes.merge(
+            input: project.mask(trace_attributes[:input]),
+            output: project.mask(trace_attributes[:output])
+          )
+        end
+
         # A response the endpoint answered but did not finish -- a generation cut off at its
         # token ceiling, say -- is neither a success worth nothing being said about nor a
         # failure the request raised on. Recording it at WARNING leaves it findable without
@@ -98,6 +119,8 @@ module NitroIntelligence
         def record_input(generation, input)
           return if input.blank?
 
+          input = project.mask(input)
+
           generation.input = input
           generation.update_trace(input:)
         end
@@ -126,15 +149,20 @@ module NitroIntelligence
         end
 
         def record_failure(generation, error)
-          generation.update(
-            level: "ERROR",
-            status_message: "#{error.class}: #{error.message}".truncate(MAX_STATUS_MESSAGE_LENGTH)
-          )
+          generation.update(level: "ERROR", status_message: failure_message(error))
 
           call_id = litellm_call_id(error)
           generation.metadata = { litellm_call_id: call_id } if call_id
         end
 
+        # The message of a gateway error can quote the request or the response, so a
+        # masked project records which error occurred and nothing it said.
+        def failure_message(error)
+          return error.class.to_s if project.mask_content?
+
+          "#{error.class}: #{error.message}".truncate(MAX_STATUS_MESSAGE_LENGTH)
+        end
+
         def litellm_call_id(error)
           return nil unless error.respond_to?(:headers)
 

data/lib/nitro_intelligence/configuration.rb

@@ -3,24 +3,70 @@ require "logger"
 require "nitro_intelligence/null_cache"
 
 module NitroIntelligence
+  # The settings {NitroIntelligence.configure} yields. Each is set on the yielded object, never on
+  # this class.
+  #
+  # @example
+  #   NitroIntelligence.configure do |config|
+  #     config.logger = Rails.logger
+  #     config.inference_api_key = "..."
+  #   end
   class Configuration
     include ActiveSupport::Configurable
 
+    # @!attribute [rw] logger
+    #   @return [Logger] where diagnostic output goes. Defaults to standard output.
     config_accessor :logger, default: Logger.new($stdout)
+    # @!attribute [rw] cache_provider
+    #   @return [ActiveSupport::Cache::Store] the cache prompts are kept in, normally `Rails.cache`.
+    #     Defaults to one that caches nothing.
     config_accessor :cache_provider, default: NitroIntelligence::NullCache.new
+    # @!attribute [rw] current_revision
+    #   @return [String] the host application's revision, such as its commit, recorded on each trace
+    #     in Cerebro as its `release`
     config_accessor :current_revision, default: ""
+    # @!attribute [rw] environment
+    #   @return [String] the runtime environment, such as `Rails.env`, recorded on traces and scores.
+    #     Defaults to `"test"`.
     config_accessor :environment, default: "test"
+    # @!attribute [rw] assistants_config
+    #   @return [Hash] the assistants {NitroIntelligence.assistants} makes addressable by key: shared
+    #     `base_url` and `user_id`, and one entry per assistant under `definitions`. Without
+    #     `definitions` it is read as the keyword arguments of a single {Assistants} client. See the
+    #     README's "Assistants" section.
     config_accessor :assistants_config, default: {}
+    # @!attribute [rw] inference_api_key
+    #   @return [String] the API key for the inference gateway
     config_accessor :inference_api_key, default: ""
+    # @!attribute [rw] inference_base_url
+    #   @return [String] the inference gateway's base URL. Defaults to the shared gateway.
     config_accessor :inference_base_url, default: "https://inference.powerhome.ai"
+    # @!attribute [rw] inference_max_retries
+    #   @return [Integer] how many times the client retries a failed request itself. Defaults to 0:
+    #     see the README's "Retries and Timeouts".
     config_accessor :inference_max_retries, default: 0
+    # @!attribute [rw] inference_timeout
+    #   @return [Numeric, nil] the request timeout in seconds. Nil keeps openai-ruby's default of 600.
     config_accessor :inference_timeout, default: nil
+    # @!attribute [rw] model_config
+    #   @return [Hash] the default model for each modality (`default_text_model`,
+    #     `default_audio_transcription_model`, `default_image_model`,
+    #     `default_text_to_speech_model`) and the per-model settings under `models`. See the README's
+    #     "Configuration".
     config_accessor :model_config, default: {}
+    # @!attribute [rw] observability_base_url
+    #   @return [String] Cerebro's base URL. Defaults to the shared deployment.
     config_accessor :observability_base_url, default: "https://cerebro.powerhome.ai"
+    # @!attribute [rw] observability_projects
+    #   @return [Array<Hash>] the credentials of each Cerebro project the host reports to, each with
+    #     `slug`, `id`, `public_key` and `secret_key`
     config_accessor :observability_projects, default: []
+    # @!attribute [rw] observability_user_id
+    #   @return [String] the user recorded on observed traces when a request passes no `user_id`
     config_accessor :observability_user_id, default: ""
 
     class << self
+      # @api private
       def configure
         yield config
       end

data/lib/nitro_intelligence/decision.rb

@@ -0,0 +1,105 @@
+module NitroIntelligence
+  # What {Client::Base#decide} returns: a decision model's answers to the questions asked of it,
+  # keyed by the names the questions were given. See https://docs.typesafe.ai/api/system-one.md
+  class Decision
+    # The answer to a `noul` question.
+    #
+    # @!attribute [r] noul
+    #   @return [Float] the probability, from 0 to 1, that the answer is yes
+    NoulAnswer = Data.define(:noul)
+
+    # The answer to a `choice` question.
+    #
+    # @!attribute [r] choice
+    #   @return [String] the most probable option's name
+    # @!attribute [r] confidence
+    #   @return [Float] how concentrated the probabilities are, from 0 to 1
+    # @!attribute [r] probabilities
+    #   @return [Hash{String => Float}] the probability of every option, keyed by option name
+    ChoiceAnswer = Data.define(:choice, :confidence, :probabilities)
+
+    # The answer to a `score` question, whose levels are numbered from 0 in the order the
+    # question's `criteria` listed them.
+    #
+    # @!attribute [r] score
+    #   @return [Float] the expected level, which may fall between levels
+    # @!attribute [r] confidence
+    #   @return [Float] how concentrated the probabilities are, from 0 to 1
+    # @!attribute [r] probabilities
+    #   @return [Hash{Integer, String => Float}] the probability of every level, keyed by level
+    #     number, or by the key the gateway sent where that is not a number
+    # @!attribute [r] legend
+    #   @return [Hash{Integer, String => String, Hash, Array}] the description of every level, as the
+    #     question's `criteria` gave it, keyed like `probabilities`
+    ScoreAnswer = Data.define(:score, :confidence, :probabilities, :legend)
+
+    # @return [String, nil] the model that answered, as the gateway named it; nil when the
+    #   response did not name one
+    attr_reader :model
+    # @return [ActiveSupport::HashWithIndifferentAccess] the answers keyed by question name, each a
+    #   {NoulAnswer}, {ChoiceAnswer} or {ScoreAnswer}, or, for an answer of any other type, what the
+    #   gateway sent
+    attr_reader :answers
+    # @return [Hash] the answers as the gateway sent them, keyed by question name
+    attr_reader :raw_answers
+    # @return [ActiveSupport::HashWithIndifferentAccess] the token counts the gateway reported
+    attr_reader :usage
+    # @api private
+    attr_reader :response
+
+    # @!method last_response
+    #   @return [OpenAI::ResponseMetadata, nil] the HTTP response, including the
+    #     gateway's headers
+    delegate :last_response, to: :response
+
+    # @api private
+    def initialize(response)
+      @response = response
+      @model = response.model
+      @raw_answers = response[:answers].to_h
+      @answers = raw_answers.to_h { |name, answer| [name, build_answer(answer)] }.with_indifferent_access
+      @usage = response[:usage].to_h.with_indifferent_access
+    end
+
+  private
+
+    # A `box` answer, and any answer type added after this client, is returned as the hash it
+    # arrived as rather than dropped. An answer that is not a hash at all is returned as it came
+    # too, so it does not cost the caller every other answer in a response already paid for. Every
+    # answer is built from a copy, so changing one leaves `raw_answers` as the gateway sent it.
+    def build_answer(answer)
+      answer = answer.deep_dup
+      return answer unless answer.is_a?(Hash)
+
+      case answer[:type]
+      when "noul"
+        NoulAnswer.new(noul: answer[:noul])
+      when "choice"
+        ChoiceAnswer.new(
+          choice: answer[:choice],
+          confidence: answer[:confidence],
+          probabilities: answer[:probabilities].to_h.transform_keys(&:to_s)
+        )
+      when "score"
+        ScoreAnswer.new(
+          score: answer[:score],
+          confidence: answer[:confidence],
+          probabilities: levels(answer[:probabilities]),
+          legend: levels(answer[:legend])
+        )
+      else
+        answer
+      end
+    end
+
+    # Levels arrive as JSON object keys, so "0", "1" and so on. A key that is not a number is
+    # kept as it came rather than failing every other answer in the response.
+    def levels(hash)
+      hash.to_h.transform_keys do |level|
+        Integer(level.to_s, 10)
+      rescue ArgumentError
+        level.to_s
+      end
+    end
+  end
+end

data/lib/nitro_intelligence/langfuse_extension.rb

@@ -11,6 +11,7 @@
 require "nitro_intelligence/langfuse_tracer_provider"
 
 module NitroIntelligence
+  # @api private
   class LangfuseExtension
     attr_reader :config
 

data/lib/nitro_intelligence/langfuse_tracer_provider.rb

@@ -1,10 +1,11 @@
-# This is an adaptation of https://github.com/simplepractice/langfuse-rb/blob/main/lib/langfuse/otel_setup.rb
-# that lets users create multiple Langfuse clients in the same process.
-# See also components/nitro_intelligence/lib/nitro_intelligence/langfuse_extension.rb
-#
-# The content of this file should eventually make its way upstream.
-#
 module NitroIntelligence
+  # This is an adaptation of https://github.com/simplepractice/langfuse-rb/blob/main/lib/langfuse/otel_setup.rb
+  # that lets users create multiple Langfuse clients in the same process.
+  # See also components/nitro_intelligence/lib/nitro_intelligence/langfuse_extension.rb
+  #
+  # The content of this file should eventually make its way upstream.
+  #
+  # @api private
   class LangfuseTracerProvider
     def initialize(config)
       @trace_id_key = OpenTelemetry::Context.create_key("nitro-intelligence-trace-id")

data/lib/nitro_intelligence/media/audio.rb

@@ -1,7 +1,13 @@
 require "nitro_intelligence/media/media"
 
 module NitroIntelligence
+  # @api private
   class Audio < Media
+    # Raised by {Client::Base#transcribe_audio} on an observed client whose project does not mask
+    # content, when `audio_file` has no path. It is raised while uploading the audio to Cerebro,
+    # after the gateway has transcribed it, so the transcription is lost.
+    #
+    # @api public
     class AudioFileFormatError < StandardError; end
 
     def initialize(file)

data/lib/nitro_intelligence/media/image.rb

@@ -4,9 +4,21 @@ require "mini_magick"
 require "nitro_intelligence/media/media"
 
 module NitroIntelligence
+  # An image, such as {ImageGeneration#generated_image}.
+  #
+  # @!attribute [r] byte_string
+  #   @return [String] the image's contents, as a byte string
+  # @!attribute [r] file_extension
+  #   @return [String] the image's extension, such as `"png"`, without a dot
+  # @!attribute [r] mime_type
+  #   @return [String] the image's MIME type, such as `"image/png"`
   class Image < Media
-    attr_reader :height, :width
+    # @return [Integer] in pixels
+    attr_reader :height
+    # @return [Integer] in pixels
+    attr_reader :width
 
+    # @api private
     def self.from_base64(base64_string)
       # Strip data_uri from string
       base64_string = base64_string.sub(/^data:[^;]*;base64,/, "")
@@ -15,6 +27,7 @@ module NitroIntelligence
       new(byte_string)
     end
 
+    # @api private
     def initialize(file)
       super
 

data/lib/nitro_intelligence/media/image_generation.rb

@@ -7,7 +7,9 @@ require "time"
 require "nitro_intelligence/media/image"
 
 module NitroIntelligence
+  # What {Client::Base#generate_image} returns.
   class ImageGeneration
+    # @api private
     class Config
       DEFAULT_ASPECT_RATIO = "1:1".freeze
       DEFAULT_RESOLUTION = "1K".freeze
@@ -21,10 +23,17 @@ module NitroIntelligence
       end
     end
 
-    attr_reader :byte_string, :config, :file_type, :file_extension, :generated_image, :messages, :reference_images,
-                :target_image
+    # @api private
+    attr_reader :byte_string, :config, :file_type, :file_extension, :messages, :reference_images, :target_image
+    # @return [Image, nil] the generated image; nil when the model returned none
+    attr_reader :generated_image
+    # @return [String, nil] the trace the request was recorded under; nil without observability
     attr_accessor :trace_id
+    # @return [String, nil] the generation observation the images are attached to; nil without
+    #   observability
+    attr_accessor :observation_id
 
+    # @api private
     def initialize(
       message: "",
       target_image: nil,
@@ -35,6 +44,7 @@ module NitroIntelligence
       @model = NitroIntelligence.model_catalog.lookup_by_name(@config.model)
       @reference_images = reference_images.map { |img| Image.new(img) }
       @trace_id = nil
+      @observation_id = nil
 
       # Overrides
       yield(@config) if block_given?
@@ -48,10 +58,12 @@ module NitroIntelligence
       build_messages(message, @target_image, @reference_images)
     end
 
+    # @api private
     def files
       [target_image, reference_images, generated_image].flatten.compact
     end
 
+    # @api private
     def parse_file(chat_completion)
       base64_string = chat_completion.choices.first&.message.to_h.fetch(:images, {})&.first&.dig(:image_url, :url)
 
@@ -111,8 +123,7 @@ module NitroIntelligence
 
     def validate_config!
       # Check model supported
-      @model = NitroIntelligence.model_catalog.lookup_by_name(@config.model)
-      raise ArgumentError, "Unsupported model: '#{@config.model}'" unless @model
+      @model = NitroIntelligence.model_catalog.fetch(@config.model, type: ImageModel)
 
       # Check aspect_ratio supported
       unless @model.aspect_ratios.include?(@config.aspect_ratio)

data/lib/nitro_intelligence/media/media.rb

@@ -1,6 +1,10 @@
 require "base64"
 
 module NitroIntelligence
+  # A file sent to or returned by a model. Callers see it as an {Image}, which documents the readers
+  # they use.
+  #
+  # @api private
   class Media
     attr_accessor :direction, :reference_id
     attr_reader :base64, :byte_string, :file_extension, :file_type, :mime_type

data/lib/nitro_intelligence/models/model.rb

@@ -1,5 +1,11 @@
 module NitroIntelligence
+  # @api private
   class Model
+    # What the model is for, as an error names it: "image" for ImageModel, "text-to-speech" for
+    # TextToSpeechModel. Taken from the class name, so a new kind of model has one without
+    # declaring it.
+    def self.kind = name.demodulize.delete_suffix("Model").underscore.dasherize
+
     attr_reader :name, :omit_output_fields
 
     def initialize(name:, omit_output_fields: [], **)
@@ -8,6 +14,7 @@ module NitroIntelligence
     end
   end
 
+  # @api private
   class ImageModel < Model
     attr_reader :aspect_ratios, :resolutions
 
@@ -18,8 +25,13 @@ module NitroIntelligence
     end
   end
 
+  # @api private
+  class DecisionModel < Model; end
+
+  # @api private
   class TextModel < Model; end
 
+  # @api private
   class TextToSpeechModel < Model
     attr_reader :default_voice,
                 :default_response_format,

data/lib/nitro_intelligence/models/model_catalog.rb

@@ -1,9 +1,11 @@
 require "nitro_intelligence/models/model_factory"
 
 module NitroIntelligence
+  # @api private
   class ModelCatalog
     attr_reader :models,
                 :default_audio_transcription_model,
+                :default_decision_model,
                 :default_image_model,
                 :default_text_model,
                 :default_text_to_speech_model
@@ -12,6 +14,7 @@ module NitroIntelligence
       model_config = model_config.symbolize_keys
       @models = (model_config[:models] || []).map { |model_metadata| ModelFactory.build(model_metadata) }
       @default_audio_transcription_model = lookup_by_name(model_config[:default_audio_transcription_model])
+      @default_decision_model = lookup_by_name(model_config[:default_decision_model])
       @default_image_model = lookup_by_name(model_config[:default_image_model])
       @default_text_model = lookup_by_name(model_config[:default_text_model])
       @default_text_to_speech_model = lookup_by_name(model_config[:default_text_to_speech_model])
@@ -21,6 +24,21 @@ module NitroIntelligence
       @models.find { |model| model.name == name }
     end
 
+    # The named model, checked to be of the type a request needs. A model of another type
+    # would fail at the gateway, or deep in a handler's own validation, with an error that
+    # does not say why.
+    def fetch(name, type: Model)
+      model = lookup_by_name(name)
+      raise ArgumentError, "Unsupported model: '#{name}'" unless model
+
+      return model if model.is_a?(type)
+
+      article = type.kind.start_with?(/[aeiou]/) ? "an" : "a"
+      raise ArgumentError, "Model '#{name}' is not #{article} #{type.kind} model"
+    end
+
+    # Unused within the gem, which validates through #fetch, but kept for applications that check
+    # whether a model is configured before offering it.
     def exists?(name)
       lookup_by_name(name).present?
     end

data/lib/nitro_intelligence/models/model_factory.rb

@@ -1,10 +1,12 @@
 require "nitro_intelligence/models/model"
 
 module NitroIntelligence
+  # @api private
   class ModelFactory
     TYPES = {
       "text" => TextModel,
       "audio_transcription" => TextModel,
+      "decision" => DecisionModel,
       "image" => ImageModel,
       "text_to_speech" => TextToSpeechModel,
     }.freeze

data/lib/nitro_intelligence/null_cache.rb

@@ -1,6 +1,8 @@
 module NitroIntelligence
   # Default no-operation cache implementation used
   # as a sensible default for initializing NitroIntelligence
+  #
+  # @api private
   class NullCache
     def read(_key) = nil
     def write(_key, _value, **_options) = true

data/lib/nitro_intelligence/observability/project.rb

@@ -2,18 +2,36 @@ require "base64"
 require "nitro_intelligence/observability/prompt_store"
 
 module NitroIntelligence
+  # Cerebro, the Langfuse deployment observed requests are recorded in.
   module Observability
+    # A Cerebro project `observability_projects` configures. Use it to reach Cerebro's API, or to
+    # link to the project's traces, where this gem does not.
     class Project
+      # Raised by {ProjectClientRegistry#fetch} when `observability_projects` does not configure the
+      # project.
       class NotFoundError < StandardError; end
 
-      attr_reader :slug, :id, :public_key, :secret_key, :auth_token, :prompt_store
+      # @api private
+      # Recorded in place of anything a masked project would otherwise send to Cerebro.
+      MASKED_CONTENT = "[masked]".freeze
 
-      def initialize(slug:, id:, public_key:, secret_key:, **_kwargs)
+      # @return [String] the project's id in Cerebro, as in its URLs:
+      #   `"#{config.observability_base_url}/project/#{id}/traces/#{trace_id}"`
+      attr_reader :id
+      # @return [String] the Base64 `public_key:secret_key` credential for Cerebro's public API,
+      #   without the scheme: send it as `Authorization: Basic #{auth_token}`
+      attr_reader :auth_token
+      # @api private
+      attr_reader :slug, :public_key, :secret_key, :prompt_store
+
+      # @api private
+      def initialize(slug:, id:, public_key:, secret_key:, mask_content: false, **_kwargs)
         @slug = slug
         @id = id
         @public_key = public_key
         @secret_key = secret_key
         @auth_token = Base64.strict_encode64("#{public_key}:#{secret_key}")
+        @mask_content = mask_content == true
         @prompt_store = PromptStore.new(
           observability_project_slug: slug,
           observability_public_key: public_key,
@@ -21,6 +39,27 @@ module NitroIntelligence
         )
       end
 
+      # @api private
+      def mask_content?
+        @mask_content
+      end
+
+      # @api private
+      #
+      # Replaces the whole value rather than fields within it: the shape of a response
+      # varies by provider, and redacting named fields is what let reasoning leak
+      # through the gateway's own redaction. Absence stays absence, so an observation
+      # that never had an output does not gain one.
+      def mask(value)
+        return value if !mask_content? || value.nil?
+
+        MASKED_CONTENT
+      end
+
+      # The project `observability_projects` configures under `slug`.
+      #
+      # @param slug [String]
+      # @return [Project, nil] nil when no project is configured under `slug`
       def self.find_by_slug(slug:)
         project_config = NitroIntelligence.config.observability_projects.find { |project| project["slug"] == slug }
 

data/lib/nitro_intelligence/observability/project_client.rb

@@ -1,15 +1,24 @@
 module NitroIntelligence
   module Observability
+    # A project's connection to Cerebro, as {ProjectClientRegistry#fetch} gives it.
     class ProjectClient
+      # Not raised by the gem, which raises {Project::NotFoundError} for a project
+      # `observability_projects` does not configure. Public only because applications raise it
+      # themselves.
       class NotFoundError < StandardError; end
 
-      attr_reader :project, :observability_client
+      # @return [Project]
+      attr_reader :project
+      # @api private
+      attr_reader :observability_client
 
+      # @api private
       def initialize(project:, observability_client:)
         @project = project
         @observability_client = observability_client
       end
 
+      # @api private
       def shutdown
         @observability_client.shutdown
       end

data/lib/nitro_intelligence/observability/project_client_registry.rb

@@ -4,16 +4,34 @@ require "nitro_intelligence/observability/project_client"
 
 module NitroIntelligence
   module Observability
+    # Each Cerebro project's client, built once per process, as {NitroIntelligence.project_client_registry}
+    # holds them. Fetching each project at boot builds its client before the first request.
+    #
+    # @example In an initializer
+    #   NitroIntelligence.config.observability_projects.each do |project|
+    #     NitroIntelligence.project_client_registry.fetch(project["slug"])
+    #   end
+    #   at_exit { NitroIntelligence.project_client_registry.shutdown_all }
     class ProjectClientRegistry
+      # @api private
       def initialize(base_url:)
         @base_url = base_url
         @project_clients = {}
       end
 
+      # The client for the project configured under `slug`, built on first use.
+      #
+      # @param slug [String]
+      # @return [ProjectClient]
+      # @raise [Project::NotFoundError] when `observability_projects` does not configure the project
       def fetch(slug)
         @project_clients[slug] ||= build_project_client(slug)
       end
 
+      # Sends what each client still holds to Cerebro, and stops it. Call it as the process exits, or
+      # the last traces and scores are lost.
+      #
+      # @return [void]
       def shutdown_all
         @project_clients.values.each(&:shutdown)
       end