nitro_intelligence 4.0.0 → 4.1.0

data/lib/nitro_intelligence/assistant.rb

@@ -7,26 +7,43 @@ module NitroIntelligence
   # Credentials are supplied by the host. Where they come from is the host's business -- an
   # environment variable its deployment mounts, a secrets store, a literal in configuration --
   # so nothing here encodes one deployment's wiring.
+  #
+  # @example
+  #   assistant = NitroIntelligence.assistants["candidate-concierge"]
+  #   result = assistant.run(thread_id:, messages:)
   class Assistant
+    # Raised when an assistant's entry lacks its `api_key` or `assistant_id`, naming each one
+    # missing.
     class ConfigurationError < StandardError; end
 
+    # @api private
     DEFAULT_USER_ID = Assistants::DEFAULT_USER_ID
 
+    # @api private
     # `base_url` is not among them: the client defaults it, so it cannot be missing.
     REQUIRED = %w[api_key assistant_id].freeze
 
     # The key an assistant is filed and looked up under. Not its name: an entry usually carries
     # a `name` of its own, a human-readable label for the assistant's record, and the two are
     # different things.
+    #
+    # @return [String]
     attr_reader :key
 
-    attr_reader :assistant_id, :base_url, :user_id
+    # @return [String] the assistant's id in Assistants
+    attr_reader :assistant_id
+    # @return [String] the Assistants deployment that serves it
+    attr_reader :base_url
+    # @return [String] the user its threads are created for
+    attr_reader :user_id
 
     # The key is positional so that splatting an entry cannot overwrite it, whatever the entry
     # happens to carry.
     #
     # Extra keys are accepted and ignored for the same reason: an entry carries fields the
     # application has no use for, such as the graph or the observability project it reports to.
+    #
+    # @api private
     def initialize(key, base_url: nil, api_key: nil, assistant_id: nil, user_id: nil, **_kwargs)
       @key = key.to_s
       @base_url = base_url.presence || Assistants::DEFAULT_BASE_URL
@@ -37,32 +54,84 @@ module NitroIntelligence
       validate!
     end
 
+    # The client the assistant's calls go through, for anything this class does not expose.
+    #
+    # @return [Assistants]
     def client
       @client ||= Assistants.new(base_url: @base_url, api_key: @api_key, user_id: @user_id)
     end
 
     # The calls that identify an assistant take it from here rather than from the caller.
     # Everything else is thread-scoped and delegates untouched.
+    #
+    # {Assistants#run} for this assistant.
+    #
+    # @param thread_id [String]
+    # @param messages [Array<Hash>]
+    # @param kwargs [Hash] the rest of {Assistants#run}'s arguments, except `assistant_id`
+    # @return [RunResult]
+    # @raise [ArgumentError] when given an `assistant_id`
+    # @raise (see Assistants#run)
     def run(thread_id:, messages:, **kwargs)
       reject_assistant_id!(kwargs)
       client.run(thread_id:, assistant_id:, messages:, **kwargs)
     end
 
+    # {Assistants#await_run} for this assistant.
+    #
+    # @deprecated Use {#run}`(...).reply`. Removed in 5.0.
+    # @param (see #run)
+    # @return [String, nil]
+    # @raise (see #run)
     def await_run(thread_id:, messages:, **kwargs)
       reject_assistant_id!(kwargs)
       client.await_run(thread_id:, assistant_id:, messages:, **kwargs)
     end
 
+    # {Assistants#review} for this assistant.
+    #
+    # @param thread_id [String]
+    # @param kwargs [Hash] the rest of {Assistants#review}'s arguments, except `assistant_id`
+    # @return [RunResult]
+    # @raise [ArgumentError] when given an `assistant_id`
+    # @raise (see Assistants#review)
     def review(thread_id:, **kwargs)
       reject_assistant_id!(kwargs)
       client.review(thread_id:, assistant_id:, **kwargs)
     end
 
+    # {Assistants#review_tool_calls} for this assistant.
+    #
+    # @deprecated Use {#review}`(tool_calls:, reviewer_id:, interrupt_id:)`. Removed in 5.0.
+    # @param thread_id [String]
+    # @param tool_calls [Hash, Array<Hash>]
+    # @param kwargs [Hash] the rest of {Assistants#review_tool_calls}'s arguments, except
+    #   `assistant_id`
+    # @return [nil]
+    # @raise [ArgumentError] when given an `assistant_id`
+    # @raise (see Assistants#review_tool_calls)
     def review_tool_calls(thread_id:, tool_calls:, **kwargs)
       reject_assistant_id!(kwargs)
       client.review_tool_calls(thread_id:, assistant_id:, tool_calls:, **kwargs)
     end
 
+    # @!method thread_state(thread_id:)
+    #   {Assistants#thread_state}.
+    #   @return (see Assistants#thread_state)
+    # @!method thread_messages(thread_id:)
+    #   {Assistants#thread_messages}.
+    #   @return (see Assistants#thread_messages)
+    # @!method tool_calls_pending_review(thread_id:)
+    #   {Assistants#tool_calls_pending_review}.
+    #   @deprecated (see Assistants#tool_calls_pending_review)
+    #   @return (see Assistants#tool_calls_pending_review)
+    # @!method tool_calls_under_review(thread_id:)
+    #   {Assistants#tool_calls_under_review}.
+    #   @deprecated (see Assistants#tool_calls_under_review)
+    #   @return (see Assistants#tool_calls_under_review)
+    # @!method under_review(thread_id:)
+    #   {Assistants#under_review}.
+    #   @return (see Assistants#under_review)
     delegate :thread_state, :thread_messages, :tool_calls_pending_review, :tool_calls_under_review,
              :under_review, to: :client
 

data/lib/nitro_intelligence/assistant_registry.rb

@@ -17,29 +17,47 @@ module NitroIntelligence
   #     },
   #   }
   class AssistantRegistry
+    # Raised looking up a key `definitions` does not configure, listing the ones it does.
     class UnknownAssistantError < StandardError; end
 
+    # @api private
     DEFINITIONS_KEY = "definitions".freeze
+    # @api private
     SHARED_KEYS = %w[base_url user_id].freeze
 
+    # @api private
     def initialize(config = {})
       @config = config.to_h.deep_stringify_keys
       @assistants = {}
     end
 
+    # The assistant configured under `key`.
+    #
+    # @param key [String, Symbol]
+    # @return [Assistant]
+    # @raise [UnknownAssistantError] when `definitions` has no entry for `key`
+    # @raise [Assistant::ConfigurationError] when the entry lacks its `api_key` or `assistant_id`
     def [](key)
       fetch(key)
     end
 
+    # @param (see #[])
+    # @return (see #[])
+    # @raise (see #[])
     def fetch(key)
       key = key.to_s
       @assistants[key] ||= build(key)
     end
 
+    # Whether `definitions` has an entry for `key`.
+    #
+    # @param key [String, Symbol]
+    # @return [Boolean]
     def key?(key)
       definitions.key?(key.to_s)
     end
 
+    # @return [Array<String>] the keys `definitions` configures
     def keys
       definitions.keys
     end

data/lib/nitro_intelligence/assistants.rb

@@ -6,34 +6,59 @@ require "nitro_intelligence/pending_review"
 require "nitro_intelligence/run_result"
 
 module NitroIntelligence
+  # The client for Nitro Intelligence Assistants: runs assistants on threads, and resumes runs
+  # paused for review. Most hosts reach it through {NitroIntelligence.assistants}, or through an
+  # {Assistant}, which supplies `assistant_id` itself. See `docs/ASSISTANTS.md`.
   class Assistants
+    # Raised by {#initialize} without an `api_key` or `user_id`.
     class ConfigurationError < StandardError; end
+    # Raised by {#run} when Assistants refuses to create or seed the thread, or the assistant has no
+    # graph. The message is the response body.
     class ThreadInitializationError < StandardError; end
+    # Raised by {#run} when Assistants rejects the run, and when the run itself fails. The message
+    # carries the failure Assistants reported.
     class RunError < StandardError; end
+    # Raised when resuming a thread fails: the thread is not paused on what the review answers, a
+    # decision is one the pause does not allow, or Assistants refuses the resume.
     class ThreadResumptionError < StandardError; end
+    # Raised by {#thread_state}, {#thread_messages} and {#under_review} when the thread's state cannot
+    # be read. The message is the response body.
     class ThreadStateError < StandardError; end
     # The review being answered is no longer the one the thread is paused on. A subclass, so that
     # callers rescuing ThreadResumptionError still catch it.
     class ReviewSupersededError < ThreadResumptionError; end
 
+    # @api private
     # What Assistants answers, with a 400, to a resume of a thread that is no longer paused.
     NOT_INTERRUPTED_REFUSAL = "thread is not in interrupted state".freeze
 
+    # @api private
     # Assistants answers with a conflict when `ifExists: "raise"` is sent for a thread that already exists.
     THREAD_CONFLICT_CODE = 409
 
+    # @api private
     # Where a `/runs/wait` response says which run it waited on.
     RUN_LOCATION = %r{/runs/([^/]+)\z}
 
+    # @api private
     # Every assistant this gem is built for is served by the same deployment, so a client told
     # nothing about where to reach one gets that deployment. A host talking to a different one
     # -- a review environment, a local server -- still says so.
     DEFAULT_BASE_URL = "https://assistants.powerhome.ai".freeze
 
+    # The user threads are created for when a client is given none.
     DEFAULT_USER_ID = "default-user".freeze
 
-    attr_reader :base_url, :user_id
+    # @return [String] the Assistants deployment this client calls
+    attr_reader :base_url
+    # @return [String] the user threads are created for
+    attr_reader :user_id
 
+    # @param api_key [String] the key Assistants authenticates the client with
+    # @param base_url [String, nil] the Assistants deployment to call. Defaults to the shared one.
+    # @param user_id [String] the user threads are created for
+    # @raise [ConfigurationError] when `api_key` or `user_id` is blank. Omitting `api_key` raises
+    #   Ruby's `ArgumentError` for a missing keyword instead.
     def initialize(api_key:, base_url: nil, user_id: DEFAULT_USER_ID)
       raise ConfigurationError, "api_key is required" if api_key.blank?
       raise ConfigurationError, "user_id is required" if user_id.blank?
@@ -47,6 +72,15 @@ module NitroIntelligence
     # Runs the last of `messages` on the thread, seeding a new thread with the ones before it, and
     # waits for the run to end or pause. Returns a RunResult: its `reply` is nil whenever the run
     # paused, and its `review` says what the run is waiting on.
+    #
+    # @param thread_id [String] the thread, created on its first run
+    # @param assistant_id [String] the assistant to run
+    # @param messages [Array<Hash>] the conversation, oldest first: the last is run, and the ones
+    #   before it seed a new thread
+    # @param context [Hash] the run's context, such as the variables its prompt needs
+    # @return [RunResult]
+    # @raise [RunError] when `messages` is empty, Assistants rejects the run, or the run fails
+    # @raise [ThreadInitializationError] when a new thread cannot be created or seeded
     def run(thread_id:, assistant_id:, messages:, context: {})
       raise RunError, "messages cannot be empty" if messages.blank?
 
@@ -59,7 +93,11 @@ module NitroIntelligence
 
     # The run's reply, or nil when it paused for review or ended without one.
     #
-    # Deprecated: #run says why there is no reply, and how the platform delivered the one there is.
+    # @deprecated Use {#run}`(...).reply`, which also says why there is no reply, and how the
+    #   platform delivered the one there is. Removed in 5.0.
+    # @param (see #run)
+    # @return [String, nil]
+    # @raise (see #run)
     def await_run(thread_id:, assistant_id:, messages:, context: {})
       NitroIntelligence.deprecator.warn(
         "#await_run is deprecated and is removed in 5.0; use #run(...).reply, and read #run's " \
@@ -70,12 +108,20 @@ module NitroIntelligence
 
     # The thread's state as Assistants reports it, unformatted. Callers that only want the
     # conversation should reach for #thread_messages instead.
+    #
+    # @param thread_id [String]
+    # @return [Hash] the `GET /threads/{id}/state` response
+    # @raise [ThreadStateError] when the state cannot be read
     def thread_state(thread_id:)
       get_thread_state(thread_id:, error: ThreadStateError)
     end
 
     # The thread's messages as Assistants reports them, unformatted, oldest first. Each message
     # carries its own `type` ("human", "ai", "tool", ...), which callers map to their own roles.
+    #
+    # @param thread_id [String]
+    # @return [Array<Hash>]
+    # @raise [ThreadStateError] when the state cannot be read
     def thread_messages(thread_id:)
       messages_in(thread_state(thread_id:))
     end
@@ -83,9 +129,14 @@ module NitroIntelligence
     # Every tool call in the thread that has no result yet, whether or not it is held for review,
     # with the id of the message before it.
     #
-    # Deprecated: a reviewer decides only the calls the interrupt holds, which #under_review reports.
     # nitro-web's VirtualConfirmationAgent::Client still reads this, since the VCA's interrupt is not
     # in the platform's shape; it goes when the VCA moves onto the platform.
+    #
+    # @deprecated A reviewer decides only the calls the interrupt holds, which {#under_review}
+    #   reports. Removed in 5.0.
+    # @param thread_id [String]
+    # @return [Array<Hash>] each with `previous_message_id`, `id`, `name` and `args`
+    # @raise [ThreadResumptionError] when the state cannot be read
     def tool_calls_pending_review(thread_id:)
       NitroIntelligence.deprecator.warn(
         "#tool_calls_pending_review is deprecated and is removed in 5.0; use " \
@@ -120,7 +171,12 @@ module NitroIntelligence
     # Raises ThreadResumptionError when the state cannot be read, as it always has; #under_review is
     # the plain read.
     #
-    # Deprecated in favour of #under_review, which reports a pause on the reply as well.
+    # @deprecated Use {#under_review}`(thread_id:)&.tool_calls.to_a`, which reports a pause on the
+    #   reply as well. Removed in 5.0.
+    # @param thread_id [String]
+    # @return [Array<Hash>] each with `previous_message_id`, `id`, `name`, `args` and
+    #   `allowed_decisions`
+    # @raise [ThreadResumptionError] when the state cannot be read
     def tool_calls_under_review(thread_id:)
       NitroIntelligence.deprecator.warn(
         "#tool_calls_under_review is deprecated and is removed in 5.0; use " \
@@ -131,6 +187,10 @@ module NitroIntelligence
 
     # What the thread is paused on -- its tool calls or its reply -- or nil when it is not waiting
     # on a review.
+    #
+    # @param thread_id [String]
+    # @return [PendingReview, nil]
+    # @raise [ThreadStateError] when the state cannot be read
     def under_review(thread_id:)
       PendingReview.from_thread_state(get_thread_state(thread_id:, error: ThreadStateError))
     end
@@ -153,6 +213,25 @@ module NitroIntelligence
     # here, so it never decides a pause that appeared since; reporting such a resume as
     # ReviewSupersededError is best-effort (see PendingReview#unapplied_resume?), as is reporting one
     # Assistants refuses because another review resumed the thread first.
+    #
+    # @param thread_id [String]
+    # @param assistant_id [String] the assistant the resumed run runs
+    # @param reviewer_id [String] who decided, as the host identifies them
+    # @param reply [Hash, nil] the review of a held reply
+    # @param tool_calls [Array<Hash>, Hash, nil] the reviews of held tool calls: a list of reviews
+    #   that each carry their tool call's `id`, or a hash of reviews keyed by tool call id
+    # @param interrupt_id [String, nil] the pause the reviewer was shown; required for a reply
+    # @param reviewed_at [Time, String, nil] when they decided. Defaults to now.
+    # @param context [Hash] the resumed run's context, as for {#run}
+    # @return [RunResult] the resumed run
+    # @raise [ArgumentError] without exactly one of `reply` and `tool_calls`, without a `reviewer_id`,
+    #   or reviewing a reply without an `interrupt_id`
+    # @raise [ReviewSupersededError] when the thread is no longer paused on the review answered
+    # @raise [ThreadResumptionError] when a decision is not one the pause allows, the thread is paused
+    #   on the other kind of review, or the resume fails
+    # @example
+    #   assistants.review(thread_id:, assistant_id:, reviewer_id: "jane@example.com",
+    #                     interrupt_id: pending.interrupt_id, reply: { "action" => "approve" })
     def review(thread_id:, assistant_id:, reviewer_id:, reply: nil, tool_calls: nil, interrupt_id: nil, # rubocop:disable Metrics/ParameterLists
                reviewed_at: nil, context: {})
       kind, reviews = review_subject!(reply:, tool_calls:)
@@ -188,7 +267,18 @@ module NitroIntelligence
     # a resume Assistants refuses because the thread is no longer paused is raised as it always was, a
     # ThreadResumptionError carrying the response body, which nitro-web parses. Returns nil.
     #
-    # Deprecated in favour of #review, which requires the reviewer and returns the resumed run.
+    # @deprecated Use {#review}`(tool_calls:, reviewer_id:, interrupt_id:)`, which requires the
+    #   reviewer and returns the resumed run. Removed in 5.0.
+    # @param thread_id [String]
+    # @param assistant_id [String]
+    # @param tool_calls [Hash, Array<Hash>] the reviews
+    # @param context [Hash]
+    # @param reviewer_id [String, nil]
+    # @param reviewed_at [Time, String, nil]
+    # @return [nil]
+    # @raise [ReviewSupersededError] when the resumed run shows the decisions were not applied
+    # @raise [ThreadResumptionError] when the thread is not paused on tool calls, a decision is not one
+    #   the pause allows, or the resume fails
     def review_tool_calls(thread_id:, assistant_id:, tool_calls:, context: {}, reviewer_id: nil, reviewed_at: nil)
       NitroIntelligence.deprecator.warn(
         "#review_tool_calls is deprecated and is removed in 5.0; use " \
@@ -214,8 +304,59 @@ module NitroIntelligence
     # `get_thread_state` and `resume_run` below. Renaming any of the four breaks that override --
     # loudly, in nitro-web's suite at bump time rather than in anything here. The subclass goes when
     # the VCA moves onto this platform, and this note with it.
+    #
+    # The four are private to callers and public to subclasses, so they are documented as protected.
   private
 
+    # Reads a thread. For subclasses.
+    #
+    # @!visibility protected
+    # @param thread_id [String]
+    # @return [Hash] the `GET /threads/{id}` response
+    # @raise [ThreadResumptionError] when the thread cannot be read. The message is the response body.
+    def get_thread(thread_id:)
+      parse!(get(path: "/threads/#{thread_id}"), ThreadResumptionError)
+    end
+
+    # Whether a thread, as {#get_thread} reads it, is paused. For subclasses.
+    #
+    # @!visibility protected
+    # @param thread [Hash]
+    # @return [Boolean]
+    def interrupted?(thread)
+      thread["status"] == "interrupted"
+    end
+
+    # Reads a thread's state. For subclasses.
+    #
+    # The review flows have always raised ThreadResumptionError when a state read fails, and consumers
+    # rescue it as such. A plain read resumes nothing, so #thread_state asks for ThreadStateError.
+    #
+    # @!visibility protected
+    # @param thread_id [String]
+    # @param error [Class<StandardError>] what to raise when the state cannot be read
+    # @return [Hash] the `GET /threads/{id}/state` response
+    # @raise [StandardError] `error`, with the response body as its message
+    def get_thread_state(thread_id:, error: ThreadResumptionError)
+      parse!(get(path: "/threads/#{thread_id}/state"), error)
+    end
+
+    # Resumes a paused thread with `resume` as its `command.resume`, sent as given, and waits for the
+    # run. For subclasses that build their own resume.
+    #
+    # @!visibility protected
+    # @param thread_id [String]
+    # @param assistant_id [String]
+    # @param resume [Hash, Array] the `command.resume`
+    # @param context [Hash]
+    # @return [Hash] the `/runs/wait` response
+    # @raise [ThreadResumptionError] when Assistants refuses the resume, with the response body as its
+    #   message, or the resumed run fails
+    def resume_run(thread_id:, assistant_id:, resume:, context:)
+      wait_for_run(thread_id:, body: { assistant_id:, command: { resume: }, context: }, error: ThreadResumptionError)
+        .first
+    end
+
     # Assistants accepts `initial_state` on thread creation but never applies it, so a brand new thread is
     # seeded through the thread state endpoint instead. A thread that already exists is left untouched:
     # its state was seeded when it was created and has been built up by every run since.
@@ -281,16 +422,6 @@ module NitroIntelligence
       response.code.to_i == THREAD_CONFLICT_CODE
     end
 
-    # The review flows have always raised ThreadResumptionError when a state read fails, and consumers
-    # rescue it as such. A plain read resumes nothing, so #thread_state asks for ThreadStateError.
-    def get_thread_state(thread_id:, error: ThreadResumptionError)
-      parse!(get(path: "/threads/#{thread_id}/state"), error)
-    end
-
-    def get_thread(thread_id:)
-      parse!(get(path: "/threads/#{thread_id}"), ThreadResumptionError)
-    end
-
     def trigger_run(thread_id:, assistant_id:, last_message:, context: {})
       run, = wait_for_run(thread_id:, body: { assistant_id:, context:, input: { messages: [last_message] } },
                           error: RunError)
@@ -316,11 +447,6 @@ module NitroIntelligence
       raise error, detail
     end
 
-    def resume_run(thread_id:, assistant_id:, resume:, context:)
-      wait_for_run(thread_id:, body: { assistant_id:, command: { resume: }, context: }, error: ThreadResumptionError)
-        .first
-    end
-
     def review_subject!(reply:, tool_calls:)
       subjects = { reply:, tool_calls: }.compact
       return subjects.first if subjects.one?
@@ -379,10 +505,6 @@ module NitroIntelligence
       raise ReviewSupersededError, message
     end
 
-    def interrupted?(thread)
-      thread["status"] == "interrupted"
-    end
-
     def messages_in(thread_state)
       Array(thread_state.dig("values", "messages"))
     end

data/lib/nitro_intelligence/client/base.rb

@@ -1,35 +1,111 @@
 require "nitro_intelligence/client/handlers/audio_transcription_handler"
 require "nitro_intelligence/client/handlers/chat_handler"
+require "nitro_intelligence/client/handlers/decision_handler"
 require "nitro_intelligence/client/handlers/image_handler"
 require "nitro_intelligence/client/handlers/text_to_speech_handler"
 
 module NitroIntelligence
   module Client
+    # A client {Client.new} builds. Every method takes `parameters`, the request's openai-ruby
+    # parameters plus this gem's own (`prompt_name`, `prompt_variables`, `trace_seed`, `metadata`,
+    # `user_id` and the rest the README describes), and defaults the model to the configured
+    # default for its modality.
+    #
+    # Each request works on a copy of the caller's `parameters`, which the handlers fill in with
+    # defaults and gateway headers, so a hash passed to several requests carries nothing from one
+    # request into the next.
     class Base
+      # @api private
       attr_reader :client
 
+      # @api private
       def initialize(client:)
         @client = client
       end
 
+      # Creates a chat completion.
+      #
+      # @param message [String] the user's message, used when `parameters` carries no `messages`
+      # @param parameters [Hash] openai-ruby's chat completion parameters, and this gem's own
+      # @return [OpenAI::Models::Chat::ChatCompletion]
+      # @raise [ArgumentError] when the model is not one `model_config` lists
+      # @raise [Handlers::Observed::ChatHandler::ObservedChatPromptError] on an observed client, when
+      #   the request carries no user message for the model to answer
+      # @example
+      #   client.chat(message: "Why is the sky blue?").choices.first&.message&.content
       def chat(message: "", parameters: {})
-        chat_handler.create(message:, parameters:)
+        chat_handler.create(message:, parameters: parameters.dup)
       end
 
-      # Input images should be byte strings. Returns NitroIntelligence::ImageGeneration
+      # Asks a decision model questions about some content over the gateway's System One route,
+      # `POST /v1/systemone`.
+      #
+      # @param state [String, Hash, Array] the content the questions are about
+      # @param questions [Hash] each question's name mapped to its `type` (`noul`, `choice` or
+      #   `score`), `instructions` and, for `choice` and `score`, `criteria`: the options keyed by
+      #   name, or the levels in order
+      # @param parameters [Hash] `model`, `assets` (images `state` and the questions refer to),
+      #   `metadata` and `request_options`, and on an observed client `trace_name`, `trace_seed`,
+      #   `user_id`, `session_id` and `tags`. It takes no managed prompt: `prompt_name` and
+      #   `prompt_variables` are ignored, so the instructions belong in `questions`.
+      # @return [Decision]
+      # @raise [ArgumentError] when the model is not one `model_config` lists with the type
+      #   `decision`
+      # @example
+      #   client.decide(
+      #     state: "I was charged twice.",
+      #     questions: { billing: { type: "noul", instructions: "Is this message about billing?" } }
+      #   ).answers[:billing].noul
+      def decide(state:, questions:, parameters: {})
+        decision_handler.create(state:, questions:, parameters: parameters.dup)
+      end
+
+      # Generates an image, or edits `target_image`.
+      #
+      # @param message [String] what to generate, or how to edit the target
+      # @param target_image [String, nil] the image to edit, as a byte string
+      # @param reference_images [Array<String>] further images to draw on, as byte strings
+      # @param parameters [Hash] `model`, `aspect_ratio` and `resolution`, among those `model_config`
+      #   lists for the model, and this gem's own
+      # @return [ImageGeneration]
+      # @raise [ArgumentError] when the model, aspect ratio or resolution is not one `model_config`
+      #   lists
+      # @example
+      #   result = client.generate_image(message: "A bear installing a window")
+      #   File.binwrite("bear.#{result.generated_image.file_extension}", result.generated_image.byte_string)
       def generate_image(message: "", target_image: nil, reference_images: [], parameters: {})
-        image_handler.create(message:, target_image:, reference_images:, parameters:)
+        image_handler.create(message:, target_image:, reference_images:, parameters: parameters.dup)
       end
 
-      # Audio file should be file object with extension in the filename
-      # Use file_extension for now to prevent a library dependency
+      # Transcribes audio into text.
+      #
+      # @param message [String] a prompt to guide the transcription, such as its vocabulary or style
+      # @param audio_file [File] the audio, opened in binary mode, with a filename whose extension
+      #   gives its format
+      # @param parameters [Hash] openai-ruby's transcription parameters, and this gem's own
+      # @return [OpenAI::Models::Audio::Transcription, OpenAI::Models::Audio::TranscriptionVerbose,
+      #   OpenAI::Models::Audio::TranscriptionDiarized, StringIO] whichever openai-ruby returns for
+      #   the `response_format`: a `Transcription` for `json`, the default, and the response body as a
+      #   StringIO for `text`, `srt` and `vtt`. An observed client records the transcription's `text`,
+      #   so it supports only the formats that return an object.
+      # @raise [ArgumentError] when the model is not one `model_config` lists
+      # @example
+      #   client.transcribe_audio(audio_file: File.open("sample.m4a", "rb")).text
       def transcribe_audio(message: +"", audio_file: nil, parameters: {})
-        audio_transcription_handler.create(message:, audio_file:, parameters:)
+        audio_transcription_handler.create(message:, audio_file:, parameters: parameters.dup)
       end
 
-      # Returns StringIO
+      # Speaks text aloud.
+      #
+      # @param message [String] the text to speak
+      # @param parameters [Hash] openai-ruby's speech parameters, with `voice` and `response_format`
+      #   among those `model_config` lists for the model, and this gem's own
+      # @return [StringIO] the audio
+      # @raise [ArgumentError] when the model, voice or format is not one `model_config` lists
+      # @example
+      #   File.binwrite("hello.mp3", client.text_to_speech(message: "Hello").string)
       def text_to_speech(message: "", parameters: {})
-        text_to_speech_handler.create(message:, parameters:)
+        text_to_speech_handler.create(message:, parameters: parameters.dup)
       end
 
     private
@@ -42,6 +118,10 @@ module NitroIntelligence
         @chat_handler ||= Handlers::ChatHandler.new(client: @client)
       end
 
+      def decision_handler
+        @decision_handler ||= Handlers::DecisionHandler.new(client: @client)
+      end
+
       def image_handler
         @image_handler ||= Handlers::ImageHandler.new(client: @client)
       end

data/lib/nitro_intelligence/client/client.rb

@@ -1,11 +1,31 @@
 require "nitro_intelligence/client/factory"
 
 module NitroIntelligence
+  # Inference through the inference gateway: chat, image generation and editing, audio
+  # transcription and text-to-speech. See the README's "Basic Usage".
   module Client
+    # Builds a client, which records every request in Cerebro when given a project to report to.
+    #
+    # A project slug that `observability_projects` does not configure logs a warning and gives a
+    # client without observability rather than raising. Building a client makes no request to
+    # Cerebro, so a configured project with wrong credentials still gives an observed client, and the
+    # error surfaces on the first request that reaches Cerebro, such as a prompt lookup.
+    #
+    # @param observability_project_slug [String, nil] the Cerebro project to record requests in, and
+    #   to fetch prompts from
+    # @param inference_max_retries [Integer, nil] overrides the configured `inference_max_retries`
+    #   for this client
+    # @param inference_timeout [Numeric, nil] overrides the configured `inference_timeout` for this
+    #   client, in seconds
+    # @return [Client::Base]
+    # @example
+    #   client = NitroIntelligence::Client.new(observability_project_slug: "my-feature-project")
+    #   client.chat(message: "Why is the sky blue?")
     def self.new(observability_project_slug: nil, inference_max_retries: nil, inference_timeout: nil)
       Factory.new(observability_project_slug:, inference_max_retries:, inference_timeout:).build
     end
 
+    # @api private
     def self.validate_model(model)
       raise ArgumentError, "Unsupported model: '#{model}'" unless NitroIntelligence.model_catalog.exists?(model)
     end

data/lib/nitro_intelligence/client/factory.rb

@@ -5,6 +5,7 @@ require "nitro_intelligence/observability/project"
 
 module NitroIntelligence
   module Client
+    # @api private
     class Factory
       def initialize(observability_project_slug:, inference_max_retries: nil, inference_timeout: nil)
         @observability_project_slug = observability_project_slug

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

@@ -4,6 +4,7 @@ require "nitro_intelligence/client/handlers/base_handler"
 module NitroIntelligence
   module Client
     module Handlers
+      # @api private
       class AudioTranscriptionHandler < BaseHandler
         ALLOWED_EXTRA_PARAMETERS = OpenAI::Models::Audio::TranscriptionCreateParams.fields.keys.uniq.freeze
 
@@ -12,9 +13,10 @@ module NitroIntelligence
           perform_request(audio_file:, message:, parameters:)
         end
 
-        def perform_request(audio_file:, message: "", parameters: {}, correlation_trace_id: nil)
+        def perform_request(audio_file:, 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.transcriptions.create(
             prompt: message,
             file: audio_file,