nitro_intelligence 3.1.0 → 4.1.0

data/lib/nitro_intelligence/client/handlers/observed/image_handler.rb

@@ -5,6 +5,7 @@ module NitroIntelligence
   module Client
     module Handlers
       module Observed
+        # @api private
         class ImageHandler
           def initialize(base_handler:, observer:)
             @base_handler = base_handler
@@ -18,7 +19,7 @@ module NitroIntelligence
 
             # Modifies parameters in place
             prompt = handle_prompt(parameters:)
-            trace_name = parameters[:trace_name] || prompt&.name || @observer.project_client.project.slug
+            trace_name = parameters[:trace_name] || prompt&.name || project.slug
 
             @observer.observe(
               "image-generation",
@@ -35,6 +36,10 @@ module NitroIntelligence
 
         private
 
+          def project
+            @observer.project_client.project
+          end
+
           def build_image_generation(message:, target_image:, reference_images:, parameters:)
             NitroIntelligence::ImageGeneration.new(message:, target_image:, reference_images:) do |config|
               config.aspect_ratio = parameters[:aspect_ratio] if parameters.key?(:aspect_ratio)
@@ -44,12 +49,17 @@ module NitroIntelligence
           end
 
           def handle_image_generation_uploads(input, output, image_generation)
+            # Uploads go to Cerebro's media API directly, past any masking, and a masked
+            # project records no input or output for a media reference to sit in.
+            return if project.mask_content?
+
             # If we are doing image generation we should upload the media to observability manually
             upload_handler = NitroIntelligence::Observability::UploadHandler.new(
-              auth_token: @observer.project_client.project.auth_token
+              auth_token: project.auth_token
             )
             upload_handler.upload(
               image_generation.trace_id,
+              observation_id: image_generation.observation_id,
               upload_queue: Queue.new(image_generation.files)
             )
 
@@ -60,7 +70,7 @@ module NitroIntelligence
 
           def handle_prompt(parameters:)
             prompt = NitroIntelligence::Observability::PromptResolver.for(
-              store: @observer.project_client.project.prompt_store,
+              store: project.prompt_store,
               parameters:
             )
             return nil if prompt.blank?
@@ -76,12 +86,17 @@ module NitroIntelligence
           end
 
           def workflow(generation:, image_generation:, parameters:)
-            chat_completion = @base_handler.perform_request(parameters:, correlation_trace_id: generation.trace_id)
+            chat_completion = @base_handler.perform_request(
+              parameters:, correlation_trace_id: generation.trace_id, mask_content: project.mask_content?
+            )
 
             image_generation.trace_id = generation.trace_id
+            image_generation.observation_id = generation.id
             image_generation.parse_file(chat_completion)
 
-            input = parameters[:messages]
+            # A copy, because recording replaces its image URLs and the caller may send the same
+            # messages again.
+            input = parameters[:messages].deep_dup
             output = chat_completion.choices.first.message.to_h
             handle_image_generation_uploads(input, output, image_generation)
 

data/lib/nitro_intelligence/client/handlers/observed/text_to_speech_handler.rb

@@ -5,7 +5,12 @@ module NitroIntelligence
   module Client
     module Handlers
       module Observed
+        # @api private
         class TextToSpeechHandler
+          # Raised by {Client::Base#text_to_speech} on an observed client when the prompt it names
+          # is not a text prompt.
+          #
+          # @api public
           class ObservedTextToSpeechPromptError < StandardError; end
 
           def initialize(base_handler:, observer:)
@@ -18,7 +23,7 @@ module NitroIntelligence
 
             @base_handler.validate_and_resolve!(parameters)
 
-            trace_name = parameters[:trace_name] || prompt&.name || @observer.project_client.project.slug
+            trace_name = parameters[:trace_name] || prompt&.name || project.slug
 
             @observer.observe(
               "text-to-speech",
@@ -28,15 +33,19 @@ module NitroIntelligence
               prompt:,
               input: message
             ) do |generation|
-              workflow(message:, parameters:, trace_id: generation.trace_id)
+              workflow(generation:, message:, parameters:)
             end
           end
 
         private
 
+          def project
+            @observer.project_client.project
+          end
+
           def handle_prompt(parameters:)
             prompt = NitroIntelligence::Observability::PromptResolver.for(
-              store: @observer.project_client.project.prompt_store,
+              store: project.prompt_store,
               parameters:
             )
             return nil if prompt.blank?
@@ -54,21 +63,30 @@ module NitroIntelligence
             prompt
           end
 
-          def handle_text_to_speech_upload(tts_file, trace_id)
+          def handle_text_to_speech_upload(tts_file, trace_id, observation_id:)
+            # Uploads go to Cerebro's media API directly, past any masking. A masked
+            # project has no media reference to record; the observer masks the output.
+            return "" if project.mask_content?
+
             upload_handler = NitroIntelligence::Observability::UploadHandler.new(
-              auth_token: @observer.project_client.project.auth_token
+              auth_token: project.auth_token
             )
+            audio = Audio.new(tts_file)
+            audio.direction = "output"
+
             upload_handler.upload(
               trace_id,
-              upload_queue: Queue.new([Audio.new(tts_file)])
+              observation_id:,
+              upload_queue: Queue.new([audio])
             )
 
             uploaded_media = upload_handler.uploaded_media.first
             "@@@langfuseMedia:type=#{uploaded_media.mime_type}|id=#{uploaded_media.reference_id}|source=bytes@@@"
           end
 
-          def workflow(message:, parameters:, trace_id:)
-            tts = @base_handler.perform_request(message:, parameters:, correlation_trace_id: trace_id)
+          def workflow(generation:, message:, parameters:)
+            tts = @base_handler.perform_request(message:, parameters:, correlation_trace_id: generation.trace_id,
+                                                mask_content: project.mask_content?)
             output = ""
 
             Tempfile.create(["tts", ".#{parameters[:response_format]}"]) do |tempfile|
@@ -76,7 +94,7 @@ module NitroIntelligence
               tempfile.write(tts.string)
               tempfile.rewind
 
-              output = handle_text_to_speech_upload(tempfile, trace_id)
+              output = handle_text_to_speech_upload(tempfile, generation.trace_id, observation_id: generation.id)
             end
 
             # Usage details and the resolved model are read off a response body, and

data/lib/nitro_intelligence/client/handlers/text_to_speech_handler.rb

@@ -4,6 +4,7 @@ require "nitro_intelligence/client/handlers/base_handler"
 module NitroIntelligence
   module Client
     module Handlers
+      # @api private
       class TextToSpeechHandler < BaseHandler
         ALLOWED_EXTRA_PARAMETERS = OpenAI::Models::Audio::SpeechCreateParams.fields.keys.uniq.freeze
 
@@ -12,9 +13,10 @@ module NitroIntelligence
           perform_request(message:, parameters:)
         end
 
-        def perform_request(message: "", parameters: {}, correlation_trace_id: nil)
+        def perform_request(message: "", parameters: {}, correlation_trace_id: nil, mask_content: false)
           add_request_headers(parameters, MODALITY_HEADER => "audio", REQUESTED_MODEL_HEADER => parameters[:model])
           add_correlation_headers(parameters, trace_id: correlation_trace_id)
+          add_message_redaction_header(parameters, mask_content:)
           @client.audio.speech.create(
             input: message,
             **parameters.slice(*ALLOWED_EXTRA_PARAMETERS)

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,22 +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/deprecator.rb

@@ -0,0 +1,10 @@
+require "active_support/deprecation"
+
+module NitroIntelligence
+  # Removed in the next major release. A Rails host has it registered with its own deprecators by
+  # the Railtie, so its `config.active_support` deprecation settings (log, raise, silence) apply;
+  # elsewhere it warns on stderr.
+  def self.deprecator
+    @deprecator ||= ActiveSupport::Deprecation.new("5.0", "nitro_intelligence")
+  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)
 

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,4 +1,5 @@
 module NitroIntelligence
+  # @api private
   class Model
     attr_reader :name, :omit_output_fields
 
@@ -8,6 +9,7 @@ module NitroIntelligence
     end
   end
 
+  # @api private
   class ImageModel < Model
     attr_reader :aspect_ratios, :resolutions
 
@@ -18,8 +20,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,