nitro_intelligence 2.5.0 → 2.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0bc1642f0475d8292a1e9611003d79e31983fb9afe2fd5e35d5ddf821a191e53
-  data.tar.gz: f61c77b0a3cd8231ba52bd7df317ca715423dc08eb72639e028febf508d52472
+  metadata.gz: 92e09bec20a682ff36923a40ad1dc9d3804c3bea3da199374859d5779034d524
+  data.tar.gz: 303cfc371638d3c14e41ad2610ca2de68944c5f0877db5ab77921ec77b192dd2
 SHA512:
-  metadata.gz: 7603cb32f91bda923f1728c5318db1a1b0e7fb59c1a46bca3a4ac3c01567de9d850b578626dd76f05d17b3348e1cdb5495fa6e98f28a6e9c871323147f02db24
-  data.tar.gz: 251976a344210f499e8b7b0c7c05bec38461fd4d941cd852fe1d5b52bc4d69cc052f992b22fe83a0241845b8d8212773f77e2e5a0ea5addcc7c459d4d65bde2f
+  metadata.gz: 1d7b784fb71aa635ec0f6dc6388b6925312200e4cb757a6598b498ea0c8632bfd1413cbe6dd2a192244bd206d83f335a8865f3387d11d038092beeac65ae5397
+  data.tar.gz: 6225968bb8d513bffe785dbf91aba771bfdf0306571f8d3150489a839e8780c60b1ab7e15608f310ac56305c8dfd643b7b00a312485db3c3ee716d7573f895b7

data/docs/README.md

@@ -32,7 +32,13 @@ NitroIntelligence.configure do |config|
   ]
 
   # Nitro Intelligence Assistants settings (optional)
-  config.assistants_config = {}                  # Hash of Assistants keyword arguments
+  config.assistants_config = {                   # See "Assistants" below
+    "base_url" => "https://nip-assistants.example.com",
+    "user_id" => "my-app",
+    "definitions" => {
+      "candidate-concierge" => {},
+    }
+  }
 
   # Model configuration
   config.model_config = {
@@ -80,7 +86,7 @@ end
 | `inference_base_url`     | `String`      | `""`                  | Base URL for the LLM inference service                                                                                                                                                                     |
 | `observability_base_url` | `String`      | `""`                  | Base URL for the Langfuse observability service                                                                                                                                                            |
 | `observability_projects` | `Array<Hash>` | `[]`                  | Langfuse project credentials (slug, id, public_key, secret_key)                                                                                                                                            |
-| `assistants_config`      | `Hash`        | `{}`                  | Credentials for `Assistants.new`. Expected keys: `base_url` (String) — HTTP base URL of Nitro Intelligence Assistants; `api_key` (String) — bearer token; `user_id` (String, default: `"default-user"`) — caller identity |
+| `assistants_config`      | `Hash`        | `{}`                  | Assistants to make addressable by key. `base_url` (String) and `user_id` (String, default: `"default-user"`) are shared by every entry; `definitions` (Hash) holds one entry per assistant, keyed by what it is looked up with, each able to override a shared value. Without `definitions` the hash is read as credentials for a single `Assistants.new` — see [Assistants](#assistants) |
 | `model_config`           | `Hash`        | `{}`                  | Model defaults and per-model settings. Top-level keys: `default_text_model`, `default_audio_transcription_model`, `default_image_model`, `default_text_to_speech_model`, and `models` (array of per-model hashes keyed by `name` and `type`, with type-specific options like `aspect_ratios`/`resolutions` for images or `voices`/`response_formats` for TTS) |
 
 ## Basic Usage
@@ -494,3 +500,71 @@ client.chat(
 `NitroIntelligence::Assistants` is Nitro Intelligence's lightweight SDK for working with hosted agent threads, runs, and human review flows. It is mainly used to initialize conversation threads, trigger agent runs, inspect agent tool calls pending human approval, and resume interrupted threads after human reviews.
 
 For the full guide, see [ASSISTANTS.md](ASSISTANTS.md). For the service this SDK talks to, see the [Nitro Intelligence Assistants documentation](https://portal.powerapp.cloud/docs/default/system/nip-assistants).
+
+## Assistants
+
+An assistant is addressed by the key it is configured under:
+
+```ruby
+assistant = NitroIntelligence.assistants["candidate-concierge"]
+
+assistant.await_run(thread_id: thread.id, messages: messages)
+assistant.thread_state(thread_id: thread.id)
+```
+
+`await_run` and `review_tool_calls` supply the assistant's own id, so a caller never passes
+it -- passing `assistant_id:` to either raises `ArgumentError` rather than quietly sending the
+call to a different assistant, which is what a migrated caller carrying its old argument would
+otherwise do. Everything else is thread-scoped and delegates to the client untouched. Reach
+the client directly with `assistant.client` if you need it.
+
+### Configuration
+
+Connection settings shared by every assistant sit at the top level; `definitions` holds one
+entry per assistant, keyed by what you look it up with:
+
+```ruby
+config.assistants_config = {
+  "base_url" => "https://nip-assistants.example.com",
+  "user_id" => "my-app",
+  "definitions" => {
+    "candidate-concierge" => {},
+    "home-studio" => {
+      # Overrides the shared value for this assistant only.
+      "base_url" => "https://pr306.nip-assistants.example.com"
+    }
+  }
+}
+```
+
+An entry may carry keys this gem has no use for — a graph id, or the Cerebro project an
+assistant reports to — and they are ignored, so one structure can serve both a deployment and
+the application reading it. That includes a `name` of its own: an entry's `name` is a
+human-readable label for the assistant's record, distinct from the key it is filed under.
+`Assistant#key` returns the latter.
+
+### Credentials
+
+Each entry supplies its own `api_key` and `assistant_id`:
+
+```ruby
+"definitions" => {
+  "candidate-concierge" => {
+    "api_key" => "...",
+    "assistant_id" => "..."
+  }
+}
+```
+
+Where a host gets them is its own business — an environment variable its deployment mounts, a
+secrets store, a literal for local work. This gem reads no environment and assumes no naming
+convention, so nothing here is tied to one deployment's wiring.
+
+A key that resolves without them raises `Assistant::ConfigurationError`, naming every field it
+is missing at once so a host resolving them from elsewhere can see which lookup failed.
+
+### Without `definitions`
+
+`assistants_config` lacking `definitions` is read as keyword arguments for a single
+`Assistants` client, and `NitroIntelligence.assistants` returns that client rather than a
+registry. This is the shape that predates lookup by key; a host still on it is left alone.

data/lib/nitro_intelligence/assistant.rb

@@ -0,0 +1,76 @@
+module NitroIntelligence
+  # One assistant resolved by name: the client for its deployment, plus the id every run has to
+  # carry.
+  #
+  # 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.
+  class Assistant
+    class ConfigurationError < StandardError; end
+
+    DEFAULT_USER_ID = "default-user".freeze
+    REQUIRED = %w[base_url 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.
+    attr_reader :key
+
+    attr_reader :assistant_id, :base_url, :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.
+    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
+      @api_key = api_key.presence
+      @assistant_id = assistant_id.presence
+      @user_id = user_id.presence || DEFAULT_USER_ID
+
+      validate!
+    end
+
+    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.
+    # Everything else is thread-scoped and delegates untouched.
+    def await_run(thread_id:, messages:, **kwargs)
+      reject_assistant_id!(kwargs)
+      client.await_run(thread_id:, assistant_id:, messages:, **kwargs)
+    end
+
+    def review_tool_calls(thread_id:, reviewer_id:, tool_calls:, **kwargs)
+      reject_assistant_id!(kwargs)
+      client.review_tool_calls(thread_id:, assistant_id:, reviewer_id:, tool_calls:, **kwargs)
+    end
+
+    delegate :thread_state, :thread_messages, :tool_calls_pending_review, to: :client
+
+  private
+
+    # An assistant supplies its own id, so a caller has no business passing one. It would land
+    # in the trailing splat, which Ruby applies last, and quietly replace the configured id --
+    # routing the call to a different assistant with nothing to show for it. Refuse instead.
+    def reject_assistant_id!(kwargs)
+      return unless kwargs.key?(:assistant_id)
+
+      raise ArgumentError,
+            "assistant #{@key.inspect} supplies its own assistant_id; remove it from the call"
+    end
+
+    # Reported together and named, since a host resolving these from somewhere else needs to
+    # know which one it failed to supply.
+    def validate!
+      values = { "base_url" => @base_url, "api_key" => @api_key, "assistant_id" => @assistant_id }
+      missing = REQUIRED.select { |field| values[field].blank? }
+      return if missing.empty?
+
+      raise ConfigurationError, "assistant #{@key.inspect} is missing #{missing.join(', ')}"
+    end
+  end
+end

data/lib/nitro_intelligence/assistant_registry.rb

@@ -0,0 +1,66 @@
+require "nitro_intelligence/assistant"
+
+module NitroIntelligence
+  # Assistants addressable by name.
+  #
+  #   NitroIntelligence.assistants["candidate-concierge"].await_run(...)
+  #
+  # Built from `assistants_config`: connection settings shared by every assistant sit at the
+  # top level, and each entry under `definitions` overrides them where it needs to. The key an
+  # entry is filed under is what it is looked up by, distinct from any `name` it carries.
+  #
+  #   {
+  #     "base_url" => "https://nip-assistants.example.com",
+  #     "user_id" => "nitro-web",
+  #     "definitions" => {
+  #       "candidate-concierge" => { "graph_id" => "react-agent" },
+  #     },
+  #   }
+  class AssistantRegistry
+    class UnknownAssistantError < StandardError; end
+
+    DEFINITIONS_KEY = "definitions".freeze
+    SHARED_KEYS = %w[base_url user_id].freeze
+
+    def initialize(config = {})
+      @config = config.to_h.deep_stringify_keys
+      @assistants = {}
+    end
+
+    def [](key)
+      fetch(key)
+    end
+
+    def fetch(key)
+      key = key.to_s
+      @assistants[key] ||= build(key)
+    end
+
+    def key?(key)
+      definitions.key?(key.to_s)
+    end
+
+    def keys
+      definitions.keys
+    end
+
+  private
+
+    def definitions
+      @config[DEFINITIONS_KEY] || {}
+    end
+
+    def build(key)
+      definition = definitions[key]
+
+      unless definition
+        raise UnknownAssistantError,
+              "No assistant configured for #{key.inspect}. " \
+              "Configured: #{keys.sort.join(', ').presence || '(none)'}"
+      end
+
+      attributes = @config.slice(*SHARED_KEYS).merge(definition.to_h.deep_stringify_keys)
+      Assistant.new(key, **attributes.symbolize_keys)
+    end
+  end
+end

data/lib/nitro_intelligence/version.rb

@@ -1,3 +1,3 @@
 module NitroIntelligence
-  VERSION = "2.5.0".freeze
+  VERSION = "2.6.0".freeze
 end

data/lib/nitro_intelligence.rb

@@ -7,6 +7,7 @@ require "openai"
 
 require "nitro_intelligence/version"
 require "nitro_intelligence/agent_server"
+require "nitro_intelligence/assistant_registry"
 require "nitro_intelligence/assistants"
 require "nitro_intelligence/client/base"
 require "nitro_intelligence/client/client"
@@ -23,8 +24,15 @@ module NitroIntelligence
   class << self
     delegate :configure, :config, :logger, :environment, to: :configuration
 
+    # A registry addressable by name when `assistants_config` carries `definitions`, and the
+    # single pre-registry client otherwise. The two shapes are mutually exclusive, so the
+    # configuration decides which one a host gets: one that has not reshaped its config keeps
+    # the client it already had.
     def assistants
-      Assistants.new(**assistants_config.symbolize_keys)
+      current = assistants_config.to_h.deep_stringify_keys
+      return AssistantRegistry.new(current) if current.key?(AssistantRegistry::DEFINITIONS_KEY)
+
+      Assistants.new(**current.symbolize_keys)
     end
 
     # Deprecated: use `NitroIntelligence.assistants`.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nitro_intelligence
 version: !ruby/object:Gem::Version
-  version: 2.5.0
+  version: 2.6.0
 platform: ruby
 authors:
 - Igor Artemenko
@@ -76,6 +76,8 @@ files:
 - docs/README.md
 - lib/nitro_intelligence.rb
 - lib/nitro_intelligence/agent_server.rb
+- lib/nitro_intelligence/assistant.rb
+- lib/nitro_intelligence/assistant_registry.rb
 - lib/nitro_intelligence/assistants.rb
 - lib/nitro_intelligence/client/base.rb
 - lib/nitro_intelligence/client/client.rb