nitro_intelligence 2.3.0 → 2.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2c196d3b804d5a9137a2af97b45df17a137382114b2d592d835d3477af0541e6
-  data.tar.gz: f0fb2d024492cd2f04b52d12f41930fc0ac9ed323aca3681a59016eccc3db7fb
+  metadata.gz: 0bc1642f0475d8292a1e9611003d79e31983fb9afe2fd5e35d5ddf821a191e53
+  data.tar.gz: f61c77b0a3cd8231ba52bd7df317ca715423dc08eb72639e028febf508d52472
 SHA512:
-  metadata.gz: c41e6aa4592a56a75a7a45715ffc2a313f0a1ecf39c227a780334d60b204292790bb715da83783763931da5af95d1e845dffb3addc208329c9dbd01ed2f75d0b
-  data.tar.gz: 7eb926cd024f0b73c2b372e75d65a43cf51a82f7afd487cd589b61be0f4130549d3fe08c3f9a01965668e092f092a5d431423af925533997f863c88f70c7534c
+  metadata.gz: 7603cb32f91bda923f1728c5318db1a1b0e7fb59c1a46bca3a4ac3c01567de9d850b578626dd76f05d17b3348e1cdb5495fa6e98f28a6e9c871323147f02db24
+  data.tar.gz: 251976a344210f499e8b7b0c7c05bec38461fd4d941cd852fe1d5b52bc4d69cc052f992b22fe83a0241845b8d8212773f77e2e5a0ea5addcc7c459d4d65bde2f

data/docs/README.md

@@ -31,8 +31,8 @@ NitroIntelligence.configure do |config|
     },
   ]
 
-  # Agent server settings (optional)
-  config.agent_server_config = {}                # Hash of AgentServer keyword arguments
+  # Nitro Intelligence Assistants settings (optional)
+  config.assistants_config = {}                  # Hash of Assistants keyword arguments
 
   # Model configuration
   config.model_config = {
@@ -80,7 +80,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)                                                                                                                                            |
-| `agent_server_config`    | `Hash`        | `{}`                  | Credentials for `AgentServer.new`. Expected keys: `base_url` (String) — HTTP base URL of the agent server; `api_key` (String) — bearer token; `user_id` (String, default: `"default-user"`) — caller identity |
+| `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 |
 | `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
@@ -489,8 +489,8 @@ client.chat(
 )
 ```
 
-## Agent Server
+## Nitro Intelligence Assistants
 
-The Agent Server 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.
+`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 Agent Server guide, see [AGENT_SERVER.md](AGENT_SERVER.md).
+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).

data/lib/nitro_intelligence/agent_server.rb

@@ -1,272 +1,12 @@
-require "json"
-require "net/http"
-require "uri"
-require "nitro_intelligence/tool_call_review_validator"
+require "active_support/deprecation/constant_accessor"
+require "nitro_intelligence/assistants"
+require "nitro_intelligence/deprecation"
 
 module NitroIntelligence
-  class AgentServer
-    class ConfigurationError < StandardError; end
-    class ThreadInitializationError < StandardError; end
-    class RunError < StandardError; end
-    class ThreadResumptionError < StandardError; end
+  include ActiveSupport::Deprecation::DeprecatedConstantAccessor
 
-    # Aegra answers with a conflict when `ifExists: "raise"` is sent for a thread that already exists.
-    THREAD_CONFLICT_CODE = 409
-
-    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?
-      raise ConfigurationError, "api_key is required" if api_key.blank?
-      raise ConfigurationError, "user_id is required" if user_id.blank?
-
-      @base_url = base_url
-      @api_key = api_key
-      @user_id = user_id
-      @tool_call_review_validator = ToolCallReviewValidator.new
-      @graph_ids = {}
-    end
-
-    def await_run(thread_id:, assistant_id:, messages:, context: {})
-      raise RunError, "messages cannot be empty" if messages.blank?
-
-      initial_state = messages[0..-2]
-      last_message = messages.last
-
-      initialize_thread_if_needed(thread_id:, assistant_id:, initial_state:)
-      trigger_run(thread_id:, assistant_id:, context:, last_message:)
-    end
-
-    def tool_calls_pending_review(thread_id:)
-      thread_state = get_thread_state(thread_id:)
-      messages = thread_messages(thread_state)
-      reviewed_tool_call_ids = tool_messages(messages).map { |message| message["tool_call_id"] }
-
-      messages.each_with_index.flat_map do |message, index|
-        next [] unless message["type"] == "ai"
-
-        pending_tool_calls(message, reviewed_tool_call_ids).map do |tool_call|
-          {
-            "previous_message_id" => index.zero? ? nil : messages[index - 1]&.dig("id"),
-            "id" => tool_call["id"],
-            "name" => tool_call["name"],
-            "args" => tool_call["args"] || {},
-          }
-        end
-      end
-    end
-
-    def review_tool_calls(thread_id:, assistant_id:, reviewer_id:, tool_calls:, reviewed_at: DateTime.current.iso8601)
-      resume = { reviewer_id:, reviewed_at:, tool_calls: }.with_indifferent_access
-      thread = get_thread(thread_id:)
-      raise ThreadResumptionError, "Thread #{thread_id} is not in the interrupted state" unless interrupted?(thread)
-
-      thread_state = get_thread_state(thread_id:)
-
-      @tool_call_review_validator.validate!(
-        thread_state:,
-        tool_calls: resume[:tool_calls],
-        pending_tool_calls: tool_calls_pending_review(thread_id:)
-      )
-
-      resume_run(
-        thread_id:,
-        assistant_id:,
-        resume:,
-        context: interrupt_context(thread_state)
-      )
-
-      nil
-    end
-
-  private
-
-    # Aegra 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.
-    def initialize_thread_if_needed(thread_id:, assistant_id:, initial_state:)
-      thread_response = create_thread(thread_id:, assistant_id:)
-
-      return if thread_already_exists?(thread_response)
-      raise ThreadInitializationError, thread_response.body if thread_response.code.to_i != 200
-      return if initial_state.blank?
-
-      seed_new_thread_state(thread_id:, initial_state:)
-    end
-
-    # Creating the thread and seeding its state are separate requests, so a failure between them leaves
-    # an empty thread behind. A retry would find that thread, take it for one already under way, skip
-    # seeding and run without the history -- losing the very thing seeding exists for, without an error.
-    # Discard the thread instead, so a retry starts over from a clean slate.
-    def seed_new_thread_state(thread_id:, initial_state:)
-      seed_thread_state(thread_id:, initial_state:)
-    rescue
-      discard_thread(thread_id:)
-      raise
-    end
-
-    def discard_thread(thread_id:)
-      delete(path: "/threads/#{thread_id}")
-    rescue
-      # Best effort. The seeding failure is the one worth surfacing, and it is raised either way.
-    end
-
-    def create_thread(thread_id:, assistant_id:)
-      post(
-        path: "/threads",
-        body: {
-          threadId: thread_id.to_s,
-          ifExists: "raise",
-          # Without a graph_id, the thread state cannot be updated before the thread's first run.
-          metadata: { graph_id: graph_id_for(assistant_id) },
-          user_id:,
-        }
-      )
-    end
-
-    def graph_id_for(assistant_id)
-      @graph_ids[assistant_id] ||= fetch_graph_id(assistant_id)
-    end
-
-    def fetch_graph_id(assistant_id)
-      assistant_response = get(path: "/assistants/#{assistant_id}")
-
-      raise ThreadInitializationError, assistant_response.body if assistant_response.code.to_i != 200
-
-      graph_id = JSON.parse(assistant_response.body)["graph_id"]
-
-      raise ThreadInitializationError, "Assistant #{assistant_id} has no graph_id" if graph_id.blank?
-
-      graph_id
-    end
-
-    def seed_thread_state(thread_id:, initial_state:)
-      state_response = post(
-        path: "/threads/#{thread_id}/state",
-        body: { values: { messages: initial_state } }
-      )
-
-      raise ThreadInitializationError, state_response.body if state_response.code.to_i != 200
-
-      JSON.parse(state_response.body)
-    end
-
-    def thread_already_exists?(response)
-      response.code.to_i == THREAD_CONFLICT_CODE
-    end
-
-    def get_thread_state(thread_id:)
-      state_response = get(path: "/threads/#{thread_id}/state")
-
-      raise ThreadResumptionError, state_response.body if state_response.code.to_i != 200
-
-      JSON.parse(state_response.body)
-    end
-
-    def get_thread(thread_id:)
-      thread_response = get(path: "/threads/#{thread_id}")
-
-      raise ThreadResumptionError, thread_response.body if thread_response.code.to_i != 200
-
-      JSON.parse(thread_response.body)
-    end
-
-    def trigger_run(thread_id:, assistant_id:, last_message:, context: {})
-      run_response = post(
-        path: "/threads/#{thread_id}/runs/wait",
-        body: {
-          assistant_id:,
-          context:,
-          input: {
-            messages: [last_message],
-          },
-        }
-      )
-
-      raise RunError, run_response.body if run_response.code.to_i != 200
-
-      run = JSON.parse(run_response.body)
-      Array(run["messages"]).last&.dig("content")
-    end
-
-    def resume_run(thread_id:, assistant_id:, resume:, context:)
-      run_response = post(
-        path: "/threads/#{thread_id}/runs/wait",
-        body: {
-          assistant_id:,
-          command: {
-            resume:,
-          },
-          context:,
-        }
-      )
-
-      raise ThreadResumptionError, run_response.body if run_response.code.to_i != 200
-
-      JSON.parse(run_response.body)
-    end
-
-    def interrupted?(thread)
-      thread["status"] == "interrupted"
-    end
-
-    def interrupt_context(thread_state)
-      thread_state.dig("interrupts", 0, "value", "context") || {}
-    end
-
-    def thread_messages(thread_state)
-      Array(thread_state.dig("values", "messages"))
-    end
-
-    def tool_messages(messages)
-      messages.select { |message| message["type"] == "tool" }
-    end
-
-    def pending_tool_calls(message, reviewed_tool_call_ids)
-      Array(message["tool_calls"]).reject do |tool_call|
-        reviewed_tool_call_ids.include?(tool_call["id"])
-      end
-    end
-
-    def get(path:)
-      uri = URI("#{base_url}#{path}")
-      http = Net::HTTP.new(uri.host, uri.port)
-      http.use_ssl = uri.scheme == "https"
-
-      request = Net::HTTP::Get.new(uri)
-      request_headers.each { |k, v| request[k] = v }
-
-      http.request(request)
-    end
-
-    def delete(path:)
-      uri = URI("#{base_url}#{path}")
-      http = Net::HTTP.new(uri.host, uri.port)
-      http.use_ssl = uri.scheme == "https"
-
-      request = Net::HTTP::Delete.new(uri)
-      request_headers.each { |k, v| request[k] = v }
-
-      http.request(request)
-    end
-
-    def post(path:, body:)
-      uri = URI("#{base_url}#{path}")
-      http = Net::HTTP.new(uri.host, uri.port)
-      http.use_ssl = uri.scheme == "https"
-
-      request = Net::HTTP::Post.new(uri)
-      request_headers.each { |k, v| request[k] = v }
-      request.body = body.to_json
-
-      http.request(request)
-    end
-
-    def request_headers
-      {
-        "Content-Type" => "application/json",
-        "Authorization" => "Bearer #{@api_key}",
-      }
-    end
-  end
+  # Deprecated: the agent server is now Nitro Intelligence Assistants. Resolved through
+  # `const_missing` so that the old name returns the real class rather than a stand-in for it,
+  # keeping `is_a?`, `===`, `rescue` and the nested error constants working on upgrade.
+  deprecate_constant :AgentServer, "NitroIntelligence::Assistants", deprecator:
 end

data/lib/nitro_intelligence/assistants.rb

@@ -0,0 +1,287 @@
+require "json"
+require "net/http"
+require "uri"
+require "nitro_intelligence/tool_call_review_validator"
+
+module NitroIntelligence
+  class Assistants
+    class ConfigurationError < StandardError; end
+    class ThreadInitializationError < StandardError; end
+    class RunError < StandardError; end
+    class ThreadResumptionError < StandardError; end
+    class ThreadStateError < StandardError; end
+
+    # Assistants answers with a conflict when `ifExists: "raise"` is sent for a thread that already exists.
+    THREAD_CONFLICT_CODE = 409
+
+    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?
+      raise ConfigurationError, "api_key is required" if api_key.blank?
+      raise ConfigurationError, "user_id is required" if user_id.blank?
+
+      @base_url = base_url
+      @api_key = api_key
+      @user_id = user_id
+      @tool_call_review_validator = ToolCallReviewValidator.new
+      @graph_ids = {}
+    end
+
+    def await_run(thread_id:, assistant_id:, messages:, context: {})
+      raise RunError, "messages cannot be empty" if messages.blank?
+
+      initial_state = messages[0..-2]
+      last_message = messages.last
+
+      initialize_thread_if_needed(thread_id:, assistant_id:, initial_state:)
+      trigger_run(thread_id:, assistant_id:, context:, last_message:)
+    end
+
+    # The thread's state as Assistants reports it, unformatted. Callers that only want the
+    # conversation should reach for #thread_messages instead.
+    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.
+    def thread_messages(thread_id:)
+      messages_in(thread_state(thread_id:))
+    end
+
+    def tool_calls_pending_review(thread_id:)
+      thread_state = get_thread_state(thread_id:)
+      messages = messages_in(thread_state)
+      reviewed_tool_call_ids = tool_messages(messages).map { |message| message["tool_call_id"] }
+
+      messages.each_with_index.flat_map do |message, index|
+        next [] unless message["type"] == "ai"
+
+        pending_tool_calls(message, reviewed_tool_call_ids).map do |tool_call|
+          {
+            "previous_message_id" => index.zero? ? nil : messages[index - 1]&.dig("id"),
+            "id" => tool_call["id"],
+            "name" => tool_call["name"],
+            "args" => tool_call["args"] || {},
+          }
+        end
+      end
+    end
+
+    def review_tool_calls(thread_id:, assistant_id:, reviewer_id:, tool_calls:, reviewed_at: DateTime.current.iso8601)
+      resume = { reviewer_id:, reviewed_at:, tool_calls: }.with_indifferent_access
+      thread = get_thread(thread_id:)
+      raise ThreadResumptionError, "Thread #{thread_id} is not in the interrupted state" unless interrupted?(thread)
+
+      thread_state = get_thread_state(thread_id:)
+
+      @tool_call_review_validator.validate!(
+        thread_state:,
+        tool_calls: resume[:tool_calls],
+        pending_tool_calls: tool_calls_pending_review(thread_id:)
+      )
+
+      resume_run(
+        thread_id:,
+        assistant_id:,
+        resume:,
+        context: interrupt_context(thread_state)
+      )
+
+      nil
+    end
+
+  private
+
+    # 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.
+    def initialize_thread_if_needed(thread_id:, assistant_id:, initial_state:)
+      thread_response = create_thread(thread_id:, assistant_id:)
+
+      return if thread_already_exists?(thread_response)
+      raise ThreadInitializationError, thread_response.body if thread_response.code.to_i != 200
+      return if initial_state.blank?
+
+      seed_new_thread_state(thread_id:, initial_state:)
+    end
+
+    # Creating the thread and seeding its state are separate requests, so a failure between them leaves
+    # an empty thread behind. A retry would find that thread, take it for one already under way, skip
+    # seeding and run without the history -- losing the very thing seeding exists for, without an error.
+    # Discard the thread instead, so a retry starts over from a clean slate.
+    def seed_new_thread_state(thread_id:, initial_state:)
+      seed_thread_state(thread_id:, initial_state:)
+    rescue
+      discard_thread(thread_id:)
+      raise
+    end
+
+    def discard_thread(thread_id:)
+      delete(path: "/threads/#{thread_id}")
+    rescue
+      # Best effort. The seeding failure is the one worth surfacing, and it is raised either way.
+    end
+
+    def create_thread(thread_id:, assistant_id:)
+      post(
+        path: "/threads",
+        body: {
+          threadId: thread_id.to_s,
+          ifExists: "raise",
+          # Without a graph_id, the thread state cannot be updated before the thread's first run.
+          metadata: { graph_id: graph_id_for(assistant_id) },
+          user_id:,
+        }
+      )
+    end
+
+    def graph_id_for(assistant_id)
+      @graph_ids[assistant_id] ||= fetch_graph_id(assistant_id)
+    end
+
+    def fetch_graph_id(assistant_id)
+      assistant_response = get(path: "/assistants/#{assistant_id}")
+
+      raise ThreadInitializationError, assistant_response.body if assistant_response.code.to_i != 200
+
+      graph_id = JSON.parse(assistant_response.body)["graph_id"]
+
+      raise ThreadInitializationError, "Assistant #{assistant_id} has no graph_id" if graph_id.blank?
+
+      graph_id
+    end
+
+    def seed_thread_state(thread_id:, initial_state:)
+      state_response = post(
+        path: "/threads/#{thread_id}/state",
+        body: { values: { messages: initial_state } }
+      )
+
+      raise ThreadInitializationError, state_response.body if state_response.code.to_i != 200
+
+      JSON.parse(state_response.body)
+    end
+
+    def thread_already_exists?(response)
+      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)
+      state_response = get(path: "/threads/#{thread_id}/state")
+
+      raise error, state_response.body if state_response.code.to_i != 200
+
+      JSON.parse(state_response.body)
+    end
+
+    def get_thread(thread_id:)
+      thread_response = get(path: "/threads/#{thread_id}")
+
+      raise ThreadResumptionError, thread_response.body if thread_response.code.to_i != 200
+
+      JSON.parse(thread_response.body)
+    end
+
+    def trigger_run(thread_id:, assistant_id:, last_message:, context: {})
+      run_response = post(
+        path: "/threads/#{thread_id}/runs/wait",
+        body: {
+          assistant_id:,
+          context:,
+          input: {
+            messages: [last_message],
+          },
+        }
+      )
+
+      raise RunError, run_response.body if run_response.code.to_i != 200
+
+      run = JSON.parse(run_response.body)
+      Array(run["messages"]).last&.dig("content")
+    end
+
+    def resume_run(thread_id:, assistant_id:, resume:, context:)
+      run_response = post(
+        path: "/threads/#{thread_id}/runs/wait",
+        body: {
+          assistant_id:,
+          command: {
+            resume:,
+          },
+          context:,
+        }
+      )
+
+      raise ThreadResumptionError, run_response.body if run_response.code.to_i != 200
+
+      JSON.parse(run_response.body)
+    end
+
+    def interrupted?(thread)
+      thread["status"] == "interrupted"
+    end
+
+    def interrupt_context(thread_state)
+      thread_state.dig("interrupts", 0, "value", "context") || {}
+    end
+
+    def messages_in(thread_state)
+      Array(thread_state.dig("values", "messages"))
+    end
+
+    def tool_messages(messages)
+      messages.select { |message| message["type"] == "tool" }
+    end
+
+    def pending_tool_calls(message, reviewed_tool_call_ids)
+      Array(message["tool_calls"]).reject do |tool_call|
+        reviewed_tool_call_ids.include?(tool_call["id"])
+      end
+    end
+
+    def get(path:)
+      uri = URI("#{base_url}#{path}")
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+
+      request = Net::HTTP::Get.new(uri)
+      request_headers.each { |k, v| request[k] = v }
+
+      http.request(request)
+    end
+
+    def delete(path:)
+      uri = URI("#{base_url}#{path}")
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+
+      request = Net::HTTP::Delete.new(uri)
+      request_headers.each { |k, v| request[k] = v }
+
+      http.request(request)
+    end
+
+    def post(path:, body:)
+      uri = URI("#{base_url}#{path}")
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+
+      request = Net::HTTP::Post.new(uri)
+      request_headers.each { |k, v| request[k] = v }
+      request.body = body.to_json
+
+      http.request(request)
+    end
+
+    def request_headers
+      {
+        "Content-Type" => "application/json",
+        "Authorization" => "Bearer #{@api_key}",
+      }
+    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/configuration.rb

@@ -10,7 +10,7 @@ module NitroIntelligence
     config_accessor :cache_provider, default: NitroIntelligence::NullCache.new
     config_accessor :current_revision, default: ""
     config_accessor :environment, default: "test"
-    config_accessor :agent_server_config, default: {}
+    config_accessor :assistants_config, default: {}
     config_accessor :inference_api_key, default: ""
     config_accessor :inference_base_url, default: ""
     config_accessor :model_config, default: {}
@@ -18,6 +18,10 @@ module NitroIntelligence
     config_accessor :observability_projects, default: []
     config_accessor :observability_user_id, default: ""
 
+    # Deprecated: configure `assistants_config` instead. Keeps its original `{}` default through the
+    # deprecation window, so a host building the hash up in place still has one to build on.
+    config_accessor :agent_server_config, default: {}
+
     class << self
       def configure
         yield config

data/lib/nitro_intelligence/deprecation.rb

@@ -0,0 +1,11 @@
+require "active_support/deprecation"
+
+module NitroIntelligence
+  class << self
+    # Deprecations introduced while the agent server was renamed to Nitro Intelligence Assistants.
+    # The names they cover are removed in 3.0.
+    def deprecator
+      @deprecator ||= ActiveSupport::Deprecation.new("3.0", "Nitro Intelligence")
+    end
+  end
+end

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/tool_call_review_validator.rb

@@ -63,7 +63,7 @@ module NitroIntelligence
     end
 
     def raise_error!(message)
-      raise NitroIntelligence::AgentServer::ThreadResumptionError, message
+      raise NitroIntelligence::Assistants::ThreadResumptionError, message
     end
   end
 end

data/lib/nitro_intelligence/version.rb

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

data/lib/nitro_intelligence.rb

@@ -7,9 +7,11 @@ require "openai"
 
 require "nitro_intelligence/version"
 require "nitro_intelligence/agent_server"
+require "nitro_intelligence/assistants"
 require "nitro_intelligence/client/base"
 require "nitro_intelligence/client/client"
 require "nitro_intelligence/configuration"
+require "nitro_intelligence/deprecation"
 require "nitro_intelligence/media/image_generation"
 require "nitro_intelligence/models/model_catalog"
 require "nitro_intelligence/observability/project_client_registry"
@@ -21,8 +23,14 @@ module NitroIntelligence
   class << self
     delegate :configure, :config, :logger, :environment, to: :configuration
 
+    def assistants
+      Assistants.new(**assistants_config.symbolize_keys)
+    end
+
+    # Deprecated: use `NitroIntelligence.assistants`.
     def agent_server
-      AgentServer.new(**configuration.agent_server_config.symbolize_keys)
+      deprecator.warn("`NitroIntelligence.agent_server` is deprecated. Use `NitroIntelligence.assistants` instead.")
+      assistants
     end
 
     def cache
@@ -38,5 +46,20 @@ module NitroIntelligence
         base_url: configuration.observability_base_url
       )
     end
+
+  private
+
+    # A host that has migrated is left alone, so a stale `agent_server_config` cannot override the
+    # configuration it was replaced by.
+    def assistants_config
+      current_config = configuration.assistants_config
+      legacy_config = configuration.agent_server_config
+      return current_config if current_config.present? || legacy_config.blank?
+
+      deprecator.warn(
+        "`agent_server_config` is deprecated. Configure `assistants_config` instead."
+      )
+      legacy_config
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nitro_intelligence
 version: !ruby/object:Gem::Version
-  version: 2.3.0
+  version: 2.5.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,7 @@ files:
 - docs/README.md
 - lib/nitro_intelligence.rb
 - lib/nitro_intelligence/agent_server.rb
+- lib/nitro_intelligence/assistants.rb
 - lib/nitro_intelligence/client/base.rb
 - lib/nitro_intelligence/client/client.rb
 - lib/nitro_intelligence/client/factory.rb
@@ -91,6 +92,7 @@ files:
 - lib/nitro_intelligence/client/observed.rb
 - lib/nitro_intelligence/client/observers/langfuse_observer.rb
 - lib/nitro_intelligence/configuration.rb
+- lib/nitro_intelligence/deprecation.rb
 - lib/nitro_intelligence/langfuse_extension.rb
 - lib/nitro_intelligence/langfuse_tracer_provider.rb
 - lib/nitro_intelligence/media/audio.rb