nitro_intelligence 3.1.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,24 +54,86 @@ 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 two calls that identify an assistant take it from here rather than from the caller.
+    # 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,
-             to: :client
+             :under_review, to: :client
 
   private
 

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