nitro_intelligence 2.7.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d87085d656ea4f0e2ee7ee00f1d1e360de33aa91257847a7c127ba65082b5e7c
-  data.tar.gz: f7587153b62be7ab17a60302ce8438ab483d35e9b499aee634c69cd1388cf2a9
+  metadata.gz: a6f2f9a233086c2c5b63e91124dd8ff9f6a838ba3eb1a7e08b382029efaf6c8a
+  data.tar.gz: d4b72f0693e8c10ad97d6ead9eebb469f69043d1323e49c097811530e17c5d90
 SHA512:
-  metadata.gz: ea8307af597a82b4e7511589eb5258ab1006805a63e3cc358dc7db6b2ca55882b0e522701667d7b98f5d851e89b214b9290d3c9330ff27a8957290c3c00584c8
-  data.tar.gz: 9a891b5281ec8f6f34b4611ab8a0204027b5c14a9b63ea02999f273386a06ab9b4d2a5410b18be0041b6acb4ad7ace1f8146c2115148dc81d70c12b2372a37a6
+  metadata.gz: caf47b70030388d5a3aaaa31e4fa9aa217b401e740fdd41a166539c12bfae0e9c4342e57543510a83af4c8c9788e7c50b752324273ee4a7302c903f754a5b14e
+  data.tar.gz: 426c37a3551965cee7946631d27b00b9e84e79620640cf1575a60d827a15f5e3b2ae1f40cde95e2df39efa15ec6c2a730ee3f66fbf1dcb4e4c0c148c037e5be2

data/lib/nitro_intelligence/assistant.rb

@@ -48,12 +48,13 @@ module NitroIntelligence
       client.await_run(thread_id:, assistant_id:, messages:, **kwargs)
     end
 
-    def review_tool_calls(thread_id:, reviewer_id:, tool_calls:, **kwargs)
+    def review_tool_calls(thread_id:, tool_calls:, **kwargs)
       reject_assistant_id!(kwargs)
-      client.review_tool_calls(thread_id:, assistant_id:, reviewer_id:, tool_calls:, **kwargs)
+      client.review_tool_calls(thread_id:, assistant_id:, tool_calls:, **kwargs)
     end
 
-    delegate :thread_state, :thread_messages, :tool_calls_pending_review, to: :client
+    delegate :thread_state, :thread_messages, :tool_calls_pending_review, :tool_calls_under_review,
+             to: :client
 
   private
 

data/lib/nitro_intelligence/assistants.rb

@@ -1,6 +1,7 @@
 require "json"
 require "net/http"
 require "uri"
+require "nitro_intelligence/tool_call_review_interrupt"
 require "nitro_intelligence/tool_call_review_validator"
 
 module NitroIntelligence
@@ -75,29 +76,53 @@ module NitroIntelligence
       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
+    # The tool calls the thread's interrupt is holding, in the order the platform wants decisions
+    # for them, each with the `allowed_decisions` a reviewer may take on it. Empty when the thread
+    # is not waiting on a review.
+    #
+    # A tool the assistant is not configured to interrupt on runs without review, so an AI message
+    # can mix calls under review with calls that are only waiting to be executed. This reports the
+    # former; #tool_calls_pending_review reports both.
+    def tool_calls_under_review(thread_id:)
+      ToolCallReviewInterrupt.new(get_thread_state(thread_id:)).tool_calls
+    end
+
+    # Resumes an interrupted thread with one review per tool call the interrupt is holding. Each
+    # review is keyed by tool call id and names an `action` -- `approve`, `edit`, `reject` or
+    # `respond` -- from the decisions the interrupt allows for that tool. `edit` carries `args`,
+    # merged over the arguments the model asked for; `respond` carries the `message` returned to the
+    # model as the tool's result; `reject` may carry a `message` explaining the refusal.
+    #
+    # Assistants records nothing about who reviewed a tool call, and the resume payload it accepts
+    # has nowhere to carry it, so there is no reviewer argument to pass.
+    def review_tool_calls(thread_id:, assistant_id:, tool_calls:, context: {})
       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:)
+      interrupt = ToolCallReviewInterrupt.new(get_thread_state(thread_id:))
+      tool_calls_under_review = interrupt.tool_calls
 
-      @tool_call_review_validator.validate!(
-        thread_state:,
-        tool_calls: resume[:tool_calls],
-        pending_tool_calls: tool_calls_pending_review(thread_id:)
-      )
+      if tool_calls_under_review.empty?
+        raise ThreadResumptionError, "Thread #{thread_id} has no tool calls awaiting review"
+      end
+
+      @tool_call_review_validator.validate!(tool_calls:, tool_calls_under_review:)
 
       resume_run(
         thread_id:,
         assistant_id:,
-        resume:,
-        context: interrupt_context(thread_state)
+        resume: { decisions: interrupt.decisions(tool_calls) },
+        context:
       )
 
       nil
     end
 
+    # ContactCenter::VirtualConfirmationAgent::Client in nitro-web subclasses this to speak the
+    # VCA's own review protocol, and its override reaches `get_thread`, `interrupted?`,
+    # `get_thread_state` and `resume_run` below. Renaming any of the four breaks that override --
+    # loudly, in nitro-web's suite at bump time rather than in anything here. The subclass goes when
+    # the VCA moves onto this platform, and this note with it.
   private
 
     # Assistants accepts `initial_state` on thread creation but never applies it, so a brand new thread is
@@ -207,9 +232,19 @@ module NitroIntelligence
       raise RunError, run_response.body if run_response.code.to_i != 200
 
       run = JSON.parse(run_response.body)
+      raise_run_error!(run, RunError)
+
       Array(run["messages"]).last&.dig("content")
     end
 
+    def raise_run_error!(run, error)
+      failure = run["__error__"]
+      return if failure.blank?
+
+      detail = failure.is_a?(Hash) ? [failure["error"], failure["message"]].compact.join(": ") : failure.to_s
+      raise error, detail
+    end
+
     def resume_run(thread_id:, assistant_id:, resume:, context:)
       run_response = post(
         path: "/threads/#{thread_id}/runs/wait",
@@ -224,17 +259,16 @@ module NitroIntelligence
 
       raise ThreadResumptionError, run_response.body if run_response.code.to_i != 200
 
-      JSON.parse(run_response.body)
+      run = JSON.parse(run_response.body)
+      raise_run_error!(run, ThreadResumptionError)
+
+      run
     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

data/lib/nitro_intelligence/client/handlers/base_handler.rb

@@ -61,10 +61,9 @@ module NitroIntelligence
 
       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.
+        # `last_response` carries the HTTP metadata of the response a model was built
+        # from. The client leaves it unset on nested and locally constructed models,
+        # so both the method and its value are optional.
         def response_headers(response)
           return nil unless response.respond_to?(:last_response)
 

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

@@ -79,11 +79,13 @@ module NitroIntelligence
               output = handle_text_to_speech_upload(tempfile, trace_id)
             end
 
-            # We only get StringIO object as a response, so there are no usage details
-            # and no resolved model to record. The requested model and the input are
-            # already on the observation from before the request ran.
+            # Usage details and the resolved model are read off a response body, and
+            # this endpoint's body is audio, so neither is available here. The
+            # requested model and the input are already on the observation from
+            # before the request ran.
             trace_attributes = {
               output:,
+              cost_details: @base_handler.cost_details(tts),
             }
 
             [tts, trace_attributes]

data/lib/nitro_intelligence/configuration.rb

@@ -18,10 +18,6 @@ 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/tool_call_review_interrupt.rb

@@ -0,0 +1,135 @@
+require "active_support/core_ext/hash/indifferent_access"
+
+module NitroIntelligence
+  # The tool calls one interrupt is holding, and the resume payload that answers them.
+  #
+  # LangChain's `HumanInTheLoopMiddleware` publishes `action_requests` -- a tool name, its arguments
+  # and a description -- alongside a `review_configs` entry per tool naming the decisions a reviewer
+  # may take. It resumes with `decisions`, one per action request, matched to them by position.
+  #
+  # Action requests carry no tool call id, and ids are what a review interface works in, so each is
+  # matched back onto the tool calls of the thread's last AI message -- the ones the middleware built
+  # them from -- to recover the id. The order of `#tool_calls` is the order `decisions` must be in.
+  class ToolCallReviewInterrupt
+    def initialize(thread_state)
+      @thread_state = thread_state
+    end
+
+    def tool_calls
+      @tool_calls ||= build_tool_calls
+    end
+
+    # The `command.resume` payload for the reviews, ordered to match the action requests. Callers
+    # key their reviews by tool call id; the platform wants a positional list.
+    def decisions(reviews)
+      reviews = reviews.with_indifferent_access
+
+      tool_calls.map { |tool_call| decision_for(tool_call, reviews[tool_call["id"]]) }
+    end
+
+  private
+
+    def build_tool_calls
+      unmatched = last_ai_tool_calls.dup
+
+      action_requests.map do |action_request|
+        tool_call = take_matching_tool_call(unmatched, action_request)
+
+        {
+          "previous_message_id" => previous_message_id,
+          "id" => tool_call["id"],
+          "name" => tool_call["name"],
+          "args" => tool_call["args"] || {},
+          "allowed_decisions" => allowed_decisions_by_tool_name.fetch(action_request["name"], []),
+        }
+      end
+    end
+
+    # Arguments distinguish two calls to the same tool, and a name-only match covers a platform that
+    # reformats them on the way into the interrupt.
+    def take_matching_tool_call(unmatched, action_request)
+      name = action_request["name"]
+      index = unmatched.index { |tool_call| tool_call["name"] == name && tool_call["args"] == action_request["args"] }
+      index ||= unmatched.index { |tool_call| tool_call["name"] == name }
+
+      unless index
+        raise Assistants::ThreadResumptionError,
+              "No tool call on the thread matches the interrupt's action request for `#{name}`"
+      end
+
+      unmatched.delete_at(index)
+    end
+
+    # An action this does not recognise is refused rather than read as an approval. #review_tool_calls
+    # validates before it gets here, so this fires for a caller building a resume payload itself --
+    # or for a decision the platform gains and this does not, where running the tool for a reviewer
+    # who asked for something else is the one outcome human review exists to prevent.
+    def decision_for(tool_call, review)
+      review = (review || {}).with_indifferent_access
+
+      case review[:action].to_s
+      when "approve"
+        { "type" => "approve" }
+      when "edit"
+        { "type" => "edit", "edited_action" => edited_action(tool_call, review) }
+      when "reject"
+        review[:message].nil? ? { "type" => "reject" } : { "type" => "reject", "message" => review[:message] }
+      when "respond"
+        { "type" => "respond", "message" => review[:message] }
+      else
+        raise Assistants::ThreadResumptionError,
+              "Tool call #{tool_call['id']} has no review naming `approve`, `edit`, `reject` or `respond`"
+      end
+    end
+
+    # Edited arguments are merged over the call the model made, so a reviewer changing one of them
+    # does not have to restate the rest -- and cannot drop one by omitting it.
+    def edited_action(tool_call, review)
+      {
+        "name" => tool_call["name"],
+        "args" => tool_call["args"].merge(review[:args] || {}),
+      }
+    end
+
+    def interrupt_value
+      @interrupt_value ||= @thread_state.dig("interrupts", 0, "value") || {}
+    end
+
+    def action_requests
+      Array(interrupt_value["action_requests"])
+    end
+
+    def allowed_decisions_by_tool_name
+      @allowed_decisions_by_tool_name ||= Array(interrupt_value["review_configs"]).to_h do |review_config|
+        [review_config["action_name"], Array(review_config["allowed_decisions"]).map(&:to_s)]
+      end
+    end
+
+    def last_ai_tool_calls
+      Array(last_ai_message&.dig("tool_calls"))
+    end
+
+    # An interrupt only ever holds the tool calls of the message the model has just produced.
+    def last_ai_message_index
+      @last_ai_message_index ||= messages.rindex do |message|
+        message["type"] == "ai" && Array(message["tool_calls"]).any?
+      end
+    end
+
+    def last_ai_message
+      last_ai_message_index && messages[last_ai_message_index]
+    end
+
+    # The message the reviewer needs to read to judge the call, as #tool_calls_pending_review
+    # reports it: the one immediately before the tool-call attempt.
+    def previous_message_id
+      return nil if last_ai_message_index.nil? || last_ai_message_index.zero?
+
+      messages[last_ai_message_index - 1]&.dig("id")
+    end
+
+    def messages
+      @messages ||= Array(@thread_state.dig("values", "messages"))
+    end
+  end
+end

data/lib/nitro_intelligence/tool_call_review_validator.rb

@@ -1,29 +1,34 @@
 require "active_support/core_ext/hash/indifferent_access"
 
 module NitroIntelligence
+  # The reviews a caller submitted, checked against the tool calls the interrupt is holding, before
+  # anything is sent. Raises `Assistants::ThreadResumptionError` on the first problem it finds.
+  #
+  # Internal to `Assistants#review_tool_calls`, which builds the only instance there is. What
+  # `#validate!` takes follows what that method needs and has changed with it before, so it carries
+  # no promise to anything calling it directly.
   class ToolCallReviewValidator
-    def validate!(thread_state:, tool_calls:, pending_tool_calls:)
+    def validate!(tool_calls:, tool_calls_under_review:)
       tool_calls = normalize_tool_calls(tool_calls)
-      pending_tool_calls_by_id = Array(pending_tool_calls).index_by { |tool_call| tool_call["id"] }
-      review_actions = Array(thread_state.dig("interrupts", 0, "value", "review_actions"))
+      tool_calls_under_review_by_id = Array(tool_calls_under_review).index_by { |tool_call| tool_call["id"] }
 
       tool_calls.each do |tool_call_id, review|
-        pending_tool_call = pending_tool_calls_by_id[tool_call_id]&.with_indifferent_access
-        raise_error!("Unknown tool call ids: #{tool_call_id}") unless pending_tool_call
+        tool_call_under_review = tool_calls_under_review_by_id[tool_call_id]&.with_indifferent_access
+        raise_error!("Unknown tool call ids: #{tool_call_id}") unless tool_call_under_review
 
         review = normalize_review(tool_call_id, review)
         review_action = review[:action].to_s
 
-        unless review_actions.include?(review_action)
+        unless Array(tool_call_under_review[:allowed_decisions]).include?(review_action)
           raise_error!("Invalid review action `#{review_action}` for tool call #{tool_call_id}")
         end
 
-        validate_edited_args!(tool_call_id:, review:, pending_tool_call:) if review_action == "edit"
+        validate_review_details!(tool_call_id:, review:, review_action:, tool_call_under_review:)
       end
 
       validate_completeness!(
         submitted_tool_call_ids: tool_calls.keys,
-        pending_tool_calls:
+        tool_calls_under_review:
       )
     end
 
@@ -41,19 +46,45 @@ module NitroIntelligence
       review.with_indifferent_access
     end
 
-    def validate_edited_args!(tool_call_id:, review:, pending_tool_call:)
+    def validate_review_details!(tool_call_id:, review:, review_action:, tool_call_under_review:)
+      case review_action
+      when "edit"
+        validate_edited_args!(tool_call_id:, review:, tool_call_under_review:)
+      when "reject"
+        # The middleware falls back to its own wording when a rejection carries no reason.
+        validate_message!(tool_call_id:, review:, required: false)
+      when "respond"
+        # The message is returned to the model as the tool's result, so there is nothing to send
+        # without it.
+        validate_message!(tool_call_id:, review:, required: true)
+      end
+    end
+
+    def validate_edited_args!(tool_call_id:, review:, tool_call_under_review:)
       provided_args = review[:args]
       raise_error!("Edited args for tool call #{tool_call_id} must be a hash") unless provided_args.is_a?(Hash)
 
-      valid_arg_names = pending_tool_call.fetch(:args, {}).keys.map(&:to_s)
+      valid_arg_names = tool_call_under_review.fetch(:args, {}).keys.map(&:to_s)
       invalid_arg_names = provided_args.keys.map(&:to_s) - valid_arg_names
       return if invalid_arg_names.empty?
 
       raise_error!("Invalid edited args for tool call #{tool_call_id}: #{invalid_arg_names.join(', ')}")
     end
 
-    def validate_completeness!(submitted_tool_call_ids:, pending_tool_calls:)
-      missing_tool_call_ids = Array(pending_tool_calls).filter_map do |tool_call|
+    def validate_message!(tool_call_id:, review:, required:)
+      message = review[:message]
+
+      if message.nil?
+        raise_error!("Review for tool call #{tool_call_id} must include a message") if required
+        return
+      end
+
+      raise_error!("Message for tool call #{tool_call_id} must be a string") unless message.is_a?(String)
+      raise_error!("Review for tool call #{tool_call_id} must include a message") if required && message.blank?
+    end
+
+    def validate_completeness!(submitted_tool_call_ids:, tool_calls_under_review:)
+      missing_tool_call_ids = Array(tool_calls_under_review).filter_map do |tool_call|
         tool_call_id = tool_call["id"].to_s
         tool_call_id unless submitted_tool_call_ids.include?(tool_call_id)
       end

data/lib/nitro_intelligence/version.rb

@@ -1,3 +1,3 @@
 module NitroIntelligence
-  VERSION = "2.7.0".freeze
+  VERSION = "3.0.0".freeze
 end

data/lib/nitro_intelligence.rb

@@ -6,13 +6,11 @@ require "langfuse"
 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"
 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"
@@ -29,18 +27,12 @@ module NitroIntelligence
     # configuration decides which one a host gets: one that has not reshaped its config keeps
     # the client it already had.
     def assistants
-      current = assistants_config.to_h.deep_stringify_keys
+      current = configuration.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`.
-    def agent_server
-      deprecator.warn("`NitroIntelligence.agent_server` is deprecated. Use `NitroIntelligence.assistants` instead.")
-      assistants
-    end
-
     def cache
       configuration.cache_provider
     end
@@ -54,20 +46,5 @@ 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.7.0
+  version: 3.0.0
 platform: ruby
 authors:
 - Igor Artemenko
@@ -57,14 +57,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.79'
+        version: '0.86'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.79'
+        version: '0.86'
 description: The Ruby client for Nitro Intelligence
 email:
 - igor.artemenko@powerhrg.com
@@ -75,7 +75,6 @@ files:
 - Rakefile
 - 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
@@ -94,7 +93,6 @@ 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
@@ -113,6 +111,7 @@ files:
 - lib/nitro_intelligence/observability/prompt_store.rb
 - lib/nitro_intelligence/observability/upload_handler.rb
 - lib/nitro_intelligence/reporter.rb
+- lib/nitro_intelligence/tool_call_review_interrupt.rb
 - lib/nitro_intelligence/tool_call_review_validator.rb
 - lib/nitro_intelligence/trace.rb
 - lib/nitro_intelligence/version.rb

data/lib/nitro_intelligence/agent_server.rb

@@ -1,12 +0,0 @@
-require "active_support/deprecation/constant_accessor"
-require "nitro_intelligence/assistants"
-require "nitro_intelligence/deprecation"
-
-module NitroIntelligence
-  include ActiveSupport::Deprecation::DeprecatedConstantAccessor
-
-  # 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/deprecation.rb

@@ -1,11 +0,0 @@
-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