nitro_intelligence 2.4.0 → 2.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b9041d12c07ae072e5a7a5a2c5fccbec275d260dfd2c99cba7a5bc92337eab4d
-  data.tar.gz: 496aed9a03587308b2af556fa846686edfee3e3a1aaf4a7a3a686cf4f08b322b
+  metadata.gz: 92e09bec20a682ff36923a40ad1dc9d3804c3bea3da199374859d5779034d524
+  data.tar.gz: 303cfc371638d3c14e41ad2610ca2de68944c5f0877db5ab77921ec77b192dd2
 SHA512:
-  metadata.gz: ffa988435a0128d981e79a94f28530d1525b82c231f44e6a3cd87f15d459bcdd27ad2ef19b57499153a0a583256bb7bec2c711f51bd3cf519d9c9827cb080937
-  data.tar.gz: 18e594810e1c4815f759375f4692cb726dbc5415c00495aa03b3943d16c77d0079aa115f5aeb9ed368d715429aaafff6967f986c4b1496984160c7cb95c8aeea
+  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/client/handlers/base_handler.rb

@@ -16,12 +16,73 @@ module NitroIntelligence
         # supplied, so cap it rather than turning a large hash into a failed request.
         MAX_SPEND_LOGS_METADATA_BYTES = 4096
 
+        # Cost the inference gateway calculated for a response.
+        # See https://docs.litellm.ai/docs/proxy/response_headers
+        #
+        # The gateway is the only component that knows which deployment actually
+        # served a request, and the same model group can be served by internal
+        # capacity or by any of several third-party providers at different rates.
+        # Recomputing cost downstream from token counts therefore means maintaining
+        # a second price table that silently drifts from the one doing the billing.
+        RESPONSE_COST_HEADER = "x-litellm-response-cost".freeze
+        RESPONSE_COST_INPUT_HEADER = "x-litellm-response-cost-input".freeze
+        RESPONSE_COST_OUTPUT_HEADER = "x-litellm-response-cost-output".freeze
+
         def initialize(client:)
           @client = client
         end
 
+        # Cost breakdown for an observation, or nil when the gateway did not price
+        # the request.
+        #
+        # A deployment the gateway has no price for sends no cost header at all
+        # rather than a zero one, so absence has to mean "unknown" here. Recording
+        # nil leaves the generation without a cost; recording 0.0 would assert the
+        # request was free and quietly understate spend for every model still
+        # awaiting a price.
+        #
+        # Only the total is guaranteed. Where the cost comes from the upstream
+        # provider rather than the gateway's own calculation - OpenRouter reports a
+        # real per-request cost of its own, which the gateway passes through - there
+        # is no component breakdown, so input and output appear only when sent.
+        def cost_details(response)
+          headers = response_headers(response)
+          return nil if headers.nil?
+
+          total = header_amount(headers, RESPONSE_COST_HEADER)
+          return nil if total.nil?
+
+          {
+            total:,
+            input: header_amount(headers, RESPONSE_COST_INPUT_HEADER),
+            output: header_amount(headers, RESPONSE_COST_OUTPUT_HEADER),
+          }.compact
+        end
+
       private
 
+        # `last_response` carries the HTTP metadata of the response a typed model was
+        # built from. The client leaves it unset on nested and locally constructed
+        # models, and on endpoints returning raw or binary payloads, so both the
+        # method and its value are optional.
+        def response_headers(response)
+          return nil unless response.respond_to?(:last_response)
+
+          response.last_response&.headers
+        end
+
+        # Header values arrive as strings. A malformed one is worth ignoring rather
+        # than raising: a trace missing its cost is a far smaller problem than an
+        # inference call failing because the gateway sent something unexpected.
+        def header_amount(headers, name)
+          value = headers[name]
+          return nil if value.blank?
+
+          Float(value)
+        rescue ArgumentError, TypeError
+          nil
+        end
+
         def add_request_headers(parameters, headers)
           request_options = (parameters[:request_options] ||= {})
           (request_options[:extra_headers] ||= {}).merge!(headers.compact)

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

@@ -79,6 +79,7 @@ module NitroIntelligence
                 output_tokens: audio_transcription.usage.output_tokens,
                 total_tokens: audio_transcription.usage.total_tokens,
               },
+              cost_details: @base_handler.cost_details(audio_transcription),
             }
 
             [audio_transcription, trace_attributes]

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

@@ -59,6 +59,7 @@ module NitroIntelligence
                 completion_tokens: chat_completion.usage.completion_tokens,
                 total_tokens: chat_completion.usage.total_tokens,
               },
+              cost_details: @base_handler.cost_details(chat_completion),
             }
 
             [chat_completion, trace_attributes]

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

@@ -94,6 +94,7 @@ module NitroIntelligence
                 completion_tokens: chat_completion.usage.completion_tokens,
                 total_tokens: chat_completion.usage.total_tokens,
               },
+              cost_details: @base_handler.cost_details(chat_completion),
             }
 
             [chat_completion, trace_attributes]

data/lib/nitro_intelligence/client/observers/langfuse_observer.rb

@@ -42,17 +42,7 @@ module NitroIntelligence
               record_input(generation, input)
 
               result, trace_attributes = observe_failures(generation) { yield(generation) }
-
-              if trace_attributes
-                handle_truncation(trace_attributes[:input], trace_attributes[:output], trace_attributes[:model])
-
-                generation.model = trace_attributes[:model] if trace_attributes[:model]
-                generation.usage_details = trace_attributes[:usage_details] if trace_attributes[:usage_details]
-                generation.input = trace_attributes[:input] if trace_attributes[:input]
-                generation.output = trace_attributes[:output] if trace_attributes[:output]
-
-                generation.update_trace(input: trace_attributes[:input], output: trace_attributes[:output])
-              end
+              record_result(generation, trace_attributes)
 
               result
             end
@@ -61,6 +51,27 @@ module NitroIntelligence
 
       private
 
+        # 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
+        # asserting a value the response never carried. Cost is the clearest case -
+        # the gateway omits the header entirely for a deployment it has no price for,
+        # and writing a zero there would read as a free request rather than an
+        # unpriced one.
+        def record_result(generation, trace_attributes)
+          return unless trace_attributes
+
+          handle_truncation(trace_attributes[:input], trace_attributes[:output], trace_attributes[:model])
+
+          generation.model = trace_attributes[:model] if trace_attributes[:model]
+          generation.usage_details = trace_attributes[:usage_details] if trace_attributes[:usage_details]
+          generation.cost_details = trace_attributes[:cost_details] if trace_attributes[:cost_details]
+          generation.input = trace_attributes[:input] if trace_attributes[:input]
+          generation.output = trace_attributes[:output] if trace_attributes[:output]
+
+          generation.update_trace(input: trace_attributes[:input], output: trace_attributes[:output])
+        end
+
         # Recorded before the request is made so that a request which raises still
         # shows what was sent. Handlers whose input is not safe to record twice
         # (image generation sends base64 payloads that are replaced with media

data/lib/nitro_intelligence/reporter.rb

@@ -4,6 +4,8 @@ require "uri"
 
 module NitroIntelligence
   class Reporter
+    class DatasetItemError < StandardError; end
+
     def initialize(observability_project_slug:)
       @observability_project_slug = observability_project_slug
       @project_client = fetch_project_client
@@ -20,7 +22,17 @@ module NitroIntelligence
       request["Authorization"] = "Basic #{@project_client.project.auth_token}"
       request.body = attributes.to_json
 
-      http.request(request)
+      response = http.request(request)
+
+      # Every other request in this gem raises on an unsuccessful response. Without this a
+      # rejected write - bad credentials, a malformed item, a dataset that does not exist -
+      # is indistinguishable from a successful one, and a caller building a dataset ends up
+      # with a run against items that were never stored.
+      unless response.is_a?(Net::HTTPSuccess)
+        raise DatasetItemError, "#{response.code} creating dataset item: #{response.body}"
+      end
+
+      response
     end
 
     def score(trace_id:, name:, value:, id: "#{trace_id}-#{name}")

data/lib/nitro_intelligence/version.rb

@@ -1,3 +1,3 @@
 module NitroIntelligence
-  VERSION = "2.4.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.4.0
+  version: 2.6.0
 platform: ruby
 authors:
 - Igor Artemenko
@@ -57,14 +57,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.58'
+        version: '0.79'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.58'
+        version: '0.79'
 description: The Ruby client for Nitro Intelligence
 email:
 - igor.artemenko@powerhrg.com
@@ -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