nitro_intelligence 2.5.0 → 2.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0bc1642f0475d8292a1e9611003d79e31983fb9afe2fd5e35d5ddf821a191e53
-  data.tar.gz: f61c77b0a3cd8231ba52bd7df317ca715423dc08eb72639e028febf508d52472
+  metadata.gz: d87085d656ea4f0e2ee7ee00f1d1e360de33aa91257847a7c127ba65082b5e7c
+  data.tar.gz: f7587153b62be7ab17a60302ce8438ab483d35e9b499aee634c69cd1388cf2a9
 SHA512:
-  metadata.gz: 7603cb32f91bda923f1728c5318db1a1b0e7fb59c1a46bca3a4ac3c01567de9d850b578626dd76f05d17b3348e1cdb5495fa6e98f28a6e9c871323147f02db24
-  data.tar.gz: 251976a344210f499e8b7b0c7c05bec38461fd4d941cd852fe1d5b52bc4d69cc052f992b22fe83a0241845b8d8212773f77e2e5a0ea5addcc7c459d4d65bde2f
+  metadata.gz: ea8307af597a82b4e7511589eb5258ab1006805a63e3cc358dc7db6b2ca55882b0e522701667d7b98f5d851e89b214b9290d3c9330ff27a8957290c3c00584c8
+  data.tar.gz: 9a891b5281ec8f6f34b4611ab8a0204027b5c14a9b63ea02999f273386a06ab9b4d2a5410b18be0041b6acb4ad7ace1f8146c2115148dc81d70c12b2372a37a6

data/docs/README.md

@@ -18,10 +18,10 @@ NitroIntelligence.configure do |config|
 
   # Inference (LLM) settings
   config.inference_api_key  = "..."              # API key for the inference service
-  config.inference_base_url = "https://..."      # Base URL for the inference service
+  config.inference_base_url = "https://..."      # Base URL for the inference service (optional; defaults to the inference gateway)
 
   # Observability (Langfuse) settings
-  config.observability_base_url = "https://..."  # Base URL for the observability service
+  config.observability_base_url = "https://..."  # Base URL for the observability service (optional; defaults to Cerebro)
   config.observability_projects = [              # Array of project credential hashes
     {
       "slug"       => "my-feature-project",
@@ -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 = {
@@ -77,10 +83,10 @@ end
 | `environment`            | `String`      | `"test"`              | Runtime environment name                                                                                                                                                                                   |
 | `cache_provider`         | cache store   | `NullCache`           | ActiveSupport-compatible cache store                                                                                                                                                                       |
 | `inference_api_key`      | `String`      | `""`                  | API key for the LLM inference service                                                                                                                                                                      |
-| `inference_base_url`     | `String`      | `""`                  | Base URL for the LLM inference service                                                                                                                                                                     |
-| `observability_base_url` | `String`      | `""`                  | Base URL for the Langfuse observability service                                                                                                                                                            |
+| `inference_base_url`     | `String`      | `"https://inference.powerhome.ai"` | Base URL for the LLM inference service. Defaults to the shared inference gateway, so only a host talking to a different one needs to set it                                                                 |
+| `observability_base_url` | `String`      | `"https://cerebro.powerhome.ai"` | Base URL for the Langfuse observability service. Defaults to Cerebro, so only a host talking to a different one needs to set it                                                                             |
 | `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, default: `"https://assistants.powerhome.ai"`) 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`, which takes the same two defaults — 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,77 @@ 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 = {
+  # Optional. Defaults to the shared Assistants deployment.
+  "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.
+`base_url` is not among them: an entry that says nothing about where to reach its assistant
+gets `https://assistants.powerhome.ai`, so only a host talking to a different deployment — a
+review environment, a local server — sets it.
+
+### 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.
+`base_url` is optional here too, and a configuration without one reaches the same shared
+deployment.

data/lib/nitro_intelligence/assistant.rb

@@ -0,0 +1,80 @@
+require "nitro_intelligence/assistants"
+
+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 = Assistants::DEFAULT_USER_ID
+
+    # `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.
+    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 || Assistants::DEFAULT_BASE_URL
+      @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 = { "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,70 @@
+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
+
+      # Blank entry values are dropped rather than merged, so a definition built from a source
+      # that writes an unset field as null falls back to the shared setting instead of shadowing
+      # it with nothing.
+      entry = definition.to_h.deep_stringify_keys.compact_blank
+      attributes = @config.slice(*SHARED_KEYS).merge(entry)
+      Assistant.new(key, **attributes.symbolize_keys)
+    end
+  end
+end

data/lib/nitro_intelligence/assistants.rb

@@ -14,14 +14,20 @@ module NitroIntelligence
     # Assistants answers with a conflict when `ifExists: "raise"` is sent for a thread that already exists.
     THREAD_CONFLICT_CODE = 409
 
+    # 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
+
+    DEFAULT_USER_ID = "default-user".freeze
+
     attr_reader :base_url, :user_id
 
-    def initialize(base_url:, api_key:, user_id: "default-user")
-      raise ConfigurationError, "base_url is required" if base_url.blank?
+    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?
 
-      @base_url = base_url
+      @base_url = base_url.presence || DEFAULT_BASE_URL
       @api_key = api_key
       @user_id = user_id
       @tool_call_review_validator = ToolCallReviewValidator.new

data/lib/nitro_intelligence/configuration.rb

@@ -12,9 +12,9 @@ module NitroIntelligence
     config_accessor :environment, default: "test"
     config_accessor :assistants_config, default: {}
     config_accessor :inference_api_key, default: ""
-    config_accessor :inference_base_url, default: ""
+    config_accessor :inference_base_url, default: "https://inference.powerhome.ai"
     config_accessor :model_config, default: {}
-    config_accessor :observability_base_url, default: ""
+    config_accessor :observability_base_url, default: "https://cerebro.powerhome.ai"
     config_accessor :observability_projects, default: []
     config_accessor :observability_user_id, default: ""
 

data/lib/nitro_intelligence/version.rb

@@ -1,3 +1,3 @@
 module NitroIntelligence
-  VERSION = "2.5.0".freeze
+  VERSION = "2.7.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.7.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