nitro_intelligence 3.1.0 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2151383fb66e0292ac5fbf73f16697e32b9c0f7d64263500babdb505275925cc
-  data.tar.gz: 91b5f4bbbb3e87f56e883b710f8af8a6c1900e3c1e733d3eba14258bbc8ebf05
+  metadata.gz: 03f41090e337bd4b4ba8f5caf040355d4b8cfca9d81ffcc9b7a8d91eec2ad64e
+  data.tar.gz: 0f83490e7d57c8935cdda63579126c3a4d93b22849c1f0f6015948b94ccbb6b8
 SHA512:
-  metadata.gz: d058b2fed129d9c85210558afe41b947a44090a5532aca084a6eff04fa2913f4e0d284f0848818ce98195673833e6d675141ee06464bafcf588cfdf29bfea9f8
-  data.tar.gz: 10b6c3213894be249388a5bdbc7cc5ef963b904581d00de2d02ac3175aeb9abc9348e959a2f54c8a27b20cb19b1ecdd4c09fdb974325d331367d25df98be73b7
+  metadata.gz: f908c8f5cfdb7b2b56eb0d4316c1855b6fbdb25ac7355fb0390bbaa42f794e92f44ccc66255c9c8dfcd1b4c552ef8af554f933d3c23f6389a3ec6164b31b6c13
+  data.tar.gz: 55b75e6f31b185d3ade2f8939b8ecae69a41a6c54a3df7a1cc8405424b6762e8a788e3e4c4f8680626f4abe638d8027c69fc3e3a4cb2d590b2c196f7faec16f3

data/docs/README.md

@@ -19,6 +19,8 @@ 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 (optional; defaults to the inference gateway)
+  config.inference_max_retries = 0               # Retries the SDK makes itself (optional; defaults to 0 - see "Retries and Timeouts")
+  config.inference_timeout     = 600             # Request timeout in seconds (optional; defaults to openai-ruby's)
 
   # Observability (Langfuse) settings
   config.observability_base_url = "https://..."  # Base URL for the observability service (optional; defaults to Cerebro)
@@ -84,8 +86,11 @@ end
 | `cache_provider`         | cache store   | `NullCache`           | ActiveSupport-compatible cache store                                                                                                                                                                       |
 | `inference_api_key`      | `String`      | `""`                  | API key for the LLM inference 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                                                                 |
+| `inference_max_retries`  | `Integer`     | `0`                   | Retries the SDK makes itself after a failed request. Off by default — see [Retries and Timeouts](#retries-and-timeouts) |
+| `inference_timeout`      | `Numeric`     | `nil`                 | Request timeout in seconds. `nil` keeps openai-ruby's default of 600 |
 | `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)                                                                                                                                            |
+| `observability_user_id`  | `String`      | `""`                  | User ID recorded on observed traces when a request passes no `user_id` parameter — see [Users](#users) |
 | `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) |
 
@@ -121,6 +126,21 @@ client.chat(parameters: { model: "Qwen/Qwen3.8-27B", max_tokens: 1000, temperatu
 
 For a full list of supported parameters, see the [API reference here](https://developers.openai.com/api/reference/resources/completions/methods/create).
 
+#### Retries and Timeouts
+
+The client does not retry failed requests by default. openai-ruby on its own retries a `429`, `408`, `409` or `5xx` twice within about two seconds, but none of those is worth repeating that quickly from here: the inference gateway has already failed over between providers before it answers, and a rate limit or exhausted budget it passes on will not clear within a second. Each retry only adds load, and for billable work such as image generation a retry after a timeout can pay twice. A caller that wants retries decides when, typically in a job with backoff, and can tell a rate limit from an exhausted budget first (see the gateway's [error guidance](https://github.com/powerhome/nitro-intelligence/blob/main/docs/inference-gateway.md)).
+
+To retry anyway, or to change the timeout, set them for every client in the configuration (`inference_max_retries`, `inference_timeout`), for one client with the same names, or for one request with openai-ruby's `request_options`. The narrower setting wins.
+
+```ruby
+# For one client
+client = NitroIntelligence::Client.new(inference_max_retries: 2, inference_timeout: 30)
+
+# For one request, with any method
+client.chat(message: "Why is the sky blue?", parameters: { request_options: { max_retries: 2, timeout: 30 } })
+client.generate_image(message: "A bear installing a window", parameters: { request_options: { timeout: 120 } })
+```
+
 ### Audio Transcription
 
 Nitro Intelligence can be used to transcribe audio from a file into text.
@@ -336,22 +356,38 @@ client.chat(
 )
 ```
 
-### Grouping Traces: Sessions and Tags
+### Grouping Traces: Users, Sessions and Tags
 
-`session_id` groups related traces in the observability platform, and `tags` label
-them for filtering. Both are optional and are only sent when you set them.
+`user_id` attributes traces to a user of your application, `session_id` groups related traces, and `tags` label them for filtering. All three are optional. `session_id` and `tags` are sent only when you set them.
 
 ```ruby
 client = NitroIntelligence::Client.new(observability_project_slug: "fake-feature-project")
 client.chat(
   message: "why did this deploy fail?",
   parameters: {
+    user_id: current_user.id.to_s,
     session_id: "deploy-9f2c1ab",
     tags: ["deployment-failure-analyzer"],
   }
 )
 ```
 
+#### Users
+
+A trace that carries a `user_id` shows up under that user in Cerebro's [Users](https://langfuse.com/docs/observability/features/users) view, which lists each user with their trace count, token usage and cost, and links through to their traces. The trace list can also be filtered by user.
+
+When a request passes no `user_id`, the `observability_user_id` configuration key is used instead, so a host can attribute all of its traces to one identity (the application itself, say) and override it per request for the traces that belong to a person:
+
+```ruby
+NitroIntelligence.configure do |config|
+  config.observability_user_id = "nitro-web"
+end
+```
+
+Use an identifier that is stable and not itself personal data — a database ID rather than an email address or name — since it is stored on every trace and shown in Cerebro. It must be a String of at most 200 characters; langfuse-rb drops any other value with a warning, so convert numeric IDs with `to_s`.
+
+`user_id` is recorded only in Cerebro. It is not sent to the inference gateway, so to attribute gateway spend to a user as well, also put the identifier in `metadata` (see below).
+
 ### Correlating With Application Logs and the Inference Gateway
 
 Every observed request is correlated across three systems automatically:
@@ -369,6 +405,8 @@ Every observed request is correlated across three systems automatically:
 * **Inference gateway → observability platform.** When a request fails, the
   gateway's own request identifier is read from the error response and recorded on
   the observation as `litellm_call_id` metadata.
+* **Application users → observability platform.** Pass `user_id` to see a
+  user's traces, usage and cost together in Cerebro — see [Users](#users).
 * **Application logs → observability platform.** Put whatever your logs are keyed
   by into `metadata` — it lands on the trace *and* in the gateway's spend logs.
 
@@ -562,7 +600,7 @@ client.chat(
 
 ## Nitro Intelligence Assistants
 
-`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.
+`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 what a paused run is waiting on (tool calls or a reply held for review), and resume paused 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).
 
@@ -573,14 +611,18 @@ 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)
+result = assistant.run(thread_id: thread.id, messages: messages)
+result.reply # => nil while the reply is held for review
+assistant.review(thread_id: thread.id, reviewer_id: user.email,
+                 interrupt_id: result.review.interrupt_id, reply: { "action" => "approve" })
 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
+`run`, `review`, and the deprecated `await_run` and `review_tool_calls` (see
+[Upgrading to 4.0](ASSISTANTS.md#upgrading-to-40)), supply the assistant's own id, so a
+caller never passes it -- passing `assistant_id:` to any of them 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

data/lib/nitro_intelligence/assistant.rb

@@ -41,20 +41,30 @@ module NitroIntelligence
       @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.
+    # The calls that identify an assistant take it from here rather than from the caller.
     # Everything else is thread-scoped and delegates untouched.
+    def run(thread_id:, messages:, **kwargs)
+      reject_assistant_id!(kwargs)
+      client.run(thread_id:, assistant_id:, messages:, **kwargs)
+    end
+
     def await_run(thread_id:, messages:, **kwargs)
       reject_assistant_id!(kwargs)
       client.await_run(thread_id:, assistant_id:, messages:, **kwargs)
     end
 
+    def review(thread_id:, **kwargs)
+      reject_assistant_id!(kwargs)
+      client.review(thread_id:, assistant_id:, **kwargs)
+    end
+
     def review_tool_calls(thread_id:, tool_calls:, **kwargs)
       reject_assistant_id!(kwargs)
       client.review_tool_calls(thread_id:, assistant_id:, tool_calls:, **kwargs)
     end
 
     delegate :thread_state, :thread_messages, :tool_calls_pending_review, :tool_calls_under_review,
-             to: :client
+             :under_review, to: :client
 
   private
 

data/lib/nitro_intelligence/assistants.rb

@@ -1,8 +1,9 @@
 require "json"
 require "net/http"
 require "uri"
-require "nitro_intelligence/tool_call_review_interrupt"
-require "nitro_intelligence/tool_call_review_validator"
+require "nitro_intelligence/deprecator"
+require "nitro_intelligence/pending_review"
+require "nitro_intelligence/run_result"
 
 module NitroIntelligence
   class Assistants
@@ -11,10 +12,19 @@ module NitroIntelligence
     class RunError < StandardError; end
     class ThreadResumptionError < StandardError; end
     class ThreadStateError < StandardError; end
+    # The review being answered is no longer the one the thread is paused on. A subclass, so that
+    # callers rescuing ThreadResumptionError still catch it.
+    class ReviewSupersededError < ThreadResumptionError; end
+
+    # What Assistants answers, with a 400, to a resume of a thread that is no longer paused.
+    NOT_INTERRUPTED_REFUSAL = "thread is not in interrupted state".freeze
 
     # Assistants answers with a conflict when `ifExists: "raise"` is sent for a thread that already exists.
     THREAD_CONFLICT_CODE = 409
 
+    # Where a `/runs/wait` response says which run it waited on.
+    RUN_LOCATION = %r{/runs/([^/]+)\z}
+
     # 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.
@@ -31,11 +41,13 @@ module NitroIntelligence
       @base_url = base_url.presence || DEFAULT_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: {})
+    # Runs the last of `messages` on the thread, seeding a new thread with the ones before it, and
+    # waits for the run to end or pause. Returns a RunResult: its `reply` is nil whenever the run
+    # paused, and its `review` says what the run is waiting on.
+    def run(thread_id:, assistant_id:, messages:, context: {})
       raise RunError, "messages cannot be empty" if messages.blank?
 
       initial_state = messages[0..-2]
@@ -45,6 +57,17 @@ module NitroIntelligence
       trigger_run(thread_id:, assistant_id:, context:, last_message:)
     end
 
+    # The run's reply, or nil when it paused for review or ended without one.
+    #
+    # Deprecated: #run says why there is no reply, and how the platform delivered the one there is.
+    def await_run(thread_id:, assistant_id:, messages:, context: {})
+      NitroIntelligence.deprecator.warn(
+        "#await_run is deprecated and is removed in 5.0; use #run(...).reply, and read #run's " \
+        "interrupted? and review for a run paused for review"
+      )
+      run(thread_id:, assistant_id:, messages:, context:).reply
+    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:)
@@ -57,7 +80,17 @@ module NitroIntelligence
       messages_in(thread_state(thread_id:))
     end
 
+    # Every tool call in the thread that has no result yet, whether or not it is held for review,
+    # with the id of the message before it.
+    #
+    # Deprecated: a reviewer decides only the calls the interrupt holds, which #under_review reports.
+    # nitro-web's VirtualConfirmationAgent::Client still reads this, since the VCA's interrupt is not
+    # in the platform's shape; it goes when the VCA moves onto the platform.
     def tool_calls_pending_review(thread_id:)
+      NitroIntelligence.deprecator.warn(
+        "#tool_calls_pending_review is deprecated and is removed in 5.0; use " \
+        "#under_review(thread_id:)&.tool_calls for the tool calls awaiting a reviewer's decision"
+      )
       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"] }
@@ -83,37 +116,95 @@ module NitroIntelligence
     # 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.
+    #
+    # Raises ThreadResumptionError when the state cannot be read, as it always has; #under_review is
+    # the plain read.
+    #
+    # Deprecated in favour of #under_review, which reports a pause on the reply as well.
     def tool_calls_under_review(thread_id:)
-      ToolCallReviewInterrupt.new(get_thread_state(thread_id:)).tool_calls
+      NitroIntelligence.deprecator.warn(
+        "#tool_calls_under_review is deprecated and is removed in 5.0; use " \
+        "#under_review(thread_id:)&.tool_calls.to_a"
+      )
+      PendingReview.from_thread_state(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.
+    # What the thread is paused on -- its tool calls or its reply -- or nil when it is not waiting
+    # on a review.
+    def under_review(thread_id:)
+      PendingReview.from_thread_state(get_thread_state(thread_id:, error: ThreadStateError))
+    end
+
+    # Resumes a paused thread with a reviewer's decision on whatever it is paused on, and returns the
+    # RunResult of the resumed run. Pass exactly one of:
+    #
+    # - `reply:`, a single review of the held draft: `{"action" => "approve"}`,
+    #   `{"action" => "edit", "content" => "..."}` or `{"action" => "reject", "message" => "reason"}`;
+    # - `tool_calls:`, one review per held tool call, as #review_tool_calls takes them.
     #
-    # 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: {})
+    # `reviewer_id` and `reviewed_at` (now, unless given) are sent in the resume run's `config.metadata`,
+    # where the platform reads them; it records them and never checks them.
+    #
+    # Pass the `interrupt_id` the reviewer was shown (`PendingReview#interrupt_id`): a thread no longer
+    # paused on it raises ReviewSupersededError instead of applying the decision to whatever the thread
+    # waits on now. It is required for a reply, since a new message can replace the draft the
+    # reviewer read with another, which an approval without it would decide -- and, with a delivery
+    # tool, send unread. For tool calls it is optional. The resume is keyed by the interrupt read
+    # here, so it never decides a pause that appeared since; reporting such a resume as
+    # ReviewSupersededError is best-effort (see PendingReview#unapplied_resume?), as is reporting one
+    # Assistants refuses because another review resumed the thread first.
+    def review(thread_id:, assistant_id:, reviewer_id:, reply: nil, tool_calls: nil, interrupt_id: nil, # rubocop:disable Metrics/ParameterLists
+               reviewed_at: nil, context: {})
+      kind, reviews = review_subject!(reply:, tool_calls:)
+      raise ArgumentError, "reviewer_id is required" if reviewer_id.blank?
+
+      if kind == :reply && interrupt_id.blank?
+        raise ArgumentError, "interrupt_id is required to review a reply: pass the interrupt_id of the " \
+                             "review the reviewer was shown (PendingReview#interrupt_id)"
+      end
+
+      pending_review = pending_review!(thread_id:, kind:, interrupt_id:)
+      stamp = reviewer_stamp(reviewer_id, reviewed_at)
+
+      RunResult.new(resume_review(thread_id:, assistant_id:, pending_review:, reviews:, stamp:, context:))
+    rescue ThreadResumptionError => e
+      raise unless e.message.include?(NOT_INTERRUPTED_REFUSAL)
+
+      # Assistants refuses a resume once the thread is no longer paused, which is how the first of
+      # two reviews deciding at once wins. The second is superseded.
+      superseded!(thread_id, pending_review&.interrupt_id)
+    end
+
+    # Resumes an interrupted thread with one review per tool call the interrupt is holding: a hash
+    # keyed by tool call id, or a list of reviews that each carry their tool call's `id`. Each 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`, recorded as the reason.
+    #
+    # A thin wrapper over what #review sends for `tool_calls:`: keyed by the interrupt it read, with
+    # `reviewer_id` and `reviewed_at` in `config.metadata` when a reviewer is given, and raising
+    # ReviewSupersededError when the resumed run shows the decisions were not applied. Unlike #review,
+    # a resume Assistants refuses because the thread is no longer paused is raised as it always was, a
+    # ThreadResumptionError carrying the response body, which nitro-web parses. Returns nil.
+    #
+    # Deprecated in favour of #review, which requires the reviewer and returns the resumed run.
+    def review_tool_calls(thread_id:, assistant_id:, tool_calls:, context: {}, reviewer_id: nil, reviewed_at: nil)
+      NitroIntelligence.deprecator.warn(
+        "#review_tool_calls is deprecated and is removed in 5.0; use " \
+        "#review(tool_calls:, reviewer_id:, interrupt_id:), which returns the resumed run's RunResult"
+      )
       thread = get_thread(thread_id:)
       raise ThreadResumptionError, "Thread #{thread_id} is not in the interrupted state" unless interrupted?(thread)
 
-      interrupt = ToolCallReviewInterrupt.new(get_thread_state(thread_id:))
-      tool_calls_under_review = interrupt.tool_calls
+      pending_review = PendingReview.from_thread_state(get_thread_state(thread_id:))
 
-      if tool_calls_under_review.empty?
+      if pending_review.nil? || pending_review.tool_calls.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: { decisions: interrupt.decisions(tool_calls) },
-        context:
-      )
+      stamp = reviewer_id.present? ? reviewer_stamp(reviewer_id, reviewed_at) : nil
+      resume_review(thread_id:, assistant_id:, pending_review:, reviews: tool_calls, stamp:, context:)
 
       nil
     end
@@ -132,7 +223,8 @@ module NitroIntelligence
       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
+
+      check!(thread_response, ThreadInitializationError)
       return if initial_state.blank?
 
       seed_new_thread_state(thread_id:, initial_state:)
@@ -173,11 +265,7 @@ module NitroIntelligence
     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"]
+      graph_id = parse!(get(path: "/assistants/#{assistant_id}"), ThreadInitializationError)["graph_id"]
 
       raise ThreadInitializationError, "Assistant #{assistant_id} has no graph_id" if graph_id.blank?
 
@@ -185,14 +273,8 @@ module NitroIntelligence
     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)
+      parse!(post(path: "/threads/#{thread_id}/state", body: { values: { messages: initial_state } }),
+             ThreadInitializationError)
     end
 
     def thread_already_exists?(response)
@@ -202,39 +284,28 @@ module NitroIntelligence
     # 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)
+      parse!(get(path: "/threads/#{thread_id}/state"), error)
     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)
+      parse!(get(path: "/threads/#{thread_id}"), ThreadResumptionError)
     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, = wait_for_run(thread_id:, body: { assistant_id:, context:, input: { messages: [last_message] } },
+                          error: RunError)
+      RunResult.new(run)
+    end
 
-      run = JSON.parse(run_response.body)
-      raise_run_error!(run, RunError)
+    # Waits on a run of the thread, raising `error` when the request fails or the run reports an
+    # `__error__`. Returns the run and the id Assistants gave it, which the wait reports in its
+    # `Content-Location` (`/threads/{thread_id}/runs/{run_id}`); nil without one.
+    def wait_for_run(thread_id:, body:, error:)
+      response = post(path: "/threads/#{thread_id}/runs/wait", body:)
+      run = parse!(response, error)
+      raise_run_error!(run, error)
 
-      Array(run["messages"]).last&.dig("content")
+      [run, response["Content-Location"].to_s[RUN_LOCATION, 1]]
     end
 
     def raise_run_error!(run, error)
@@ -246,23 +317,66 @@ module NitroIntelligence
     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:,
-        }
-      )
+      wait_for_run(thread_id:, body: { assistant_id:, command: { resume: }, context: }, error: ThreadResumptionError)
+        .first
+    end
+
+    def review_subject!(reply:, tool_calls:)
+      subjects = { reply:, tool_calls: }.compact
+      return subjects.first if subjects.one?
+
+      raise ArgumentError, "pass exactly one of reply: or tool_calls:"
+    end
+
+    # The thread has to be paused, on the interrupt the reviewer was shown when they say which, and
+    # on the kind of review they are answering. A thread whose run is under way again is not
+    # paused, whatever its state still reports.
+    def pending_review!(thread_id:, kind:, interrupt_id:)
+      pending_review = interrupted?(get_thread(thread_id:)) &&
+                       PendingReview.from_thread_state(get_thread_state(thread_id:))
+
+      if !pending_review || (interrupt_id.present? && pending_review.interrupt_id != interrupt_id)
+        superseded!(thread_id, interrupt_id)
+      end
+
+      if pending_review.kind != kind
+        raise ThreadResumptionError,
+              "Thread #{thread_id} is awaiting review of #{PendingReview::KIND_NAMES[pending_review.kind]}, " \
+              "not of #{PendingReview::KIND_NAMES[kind]}"
+      end
+
+      pending_review
+    end
+
+    def reviewer_stamp(reviewer_id, reviewed_at)
+      reviewed_at = (reviewed_at || Time.now).utc.iso8601 unless reviewed_at.is_a?(String)
+
+      { "reviewer_id" => reviewer_id.to_s, "reviewed_at" => reviewed_at }
+    end
+
+    # Sends the decisions for `reviews`, validated against the pause, as the resume keyed by the
+    # pause's interrupt. A reviewer `stamp` goes in the run's `config.metadata`, where the platform
+    # reads it for replies and tool calls alike (LangChain drops extra keys in a tool decision).
+    # Raises ReviewSupersededError when the run shows the decisions were not applied.
+    def resume_review(thread_id:, assistant_id:, pending_review:, reviews:, stamp:, context:)
+      decisions = pending_review.decisions(reviews)
 
-      raise ThreadResumptionError, run_response.body if run_response.code.to_i != 200
+      body = { assistant_id:, command: { resume: pending_review.resume(decisions) } }
+      body[:config] = { metadata: stamp } if stamp
+      body[:context] = context
 
-      run = JSON.parse(run_response.body)
-      raise_run_error!(run, ThreadResumptionError)
+      run, run_id = wait_for_run(thread_id:, body:, error: ThreadResumptionError)
+      return run unless pending_review.unapplied_resume?(run:, run_id:) { get_thread_state(thread_id:) }
 
-      run
+      superseded!(thread_id, pending_review.interrupt_id, now_paused_on: PendingReview.from_run(run).interrupt_id)
+    end
+
+    def superseded!(thread_id, interrupt_id, now_paused_on: nil)
+      message = "Thread #{thread_id} is no longer paused on #{interrupt_id.presence || 'a review'}: " \
+                "another review already resumed it, or a new message superseded it"
+      message += "; it is now paused on #{now_paused_on}, and the decision was not applied" if now_paused_on
+
+      raise ReviewSupersededError, message
     end
 
     def interrupted?(thread)
@@ -284,37 +398,39 @@ module NitroIntelligence
     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, path:)
+    end
 
-      request = Net::HTTP::Get.new(uri)
-      request_headers.each { |k, v| request[k] = v }
+    def delete(path:)
+      request(Net::HTTP::Delete, path:)
+    end
 
-      http.request(request)
+    def post(path:, body:)
+      request(Net::HTTP::Post, path:, body:)
     end
 
-    def delete(path:)
+    def request(verb, path:, body: nil)
       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 = verb.new(uri)
       request_headers.each { |k, v| request[k] = v }
+      request.body = body.to_json unless body.nil?
 
       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"
+    # Anything but a 200 is a failure, raised as `error` with the response body as its message.
+    # Thread creation tells a conflict apart before it gets here.
+    def check!(response, error)
+      raise error, response.body if response.code.to_i != 200
 
-      request = Net::HTTP::Post.new(uri)
-      request_headers.each { |k, v| request[k] = v }
-      request.body = body.to_json
+      response
+    end
 
-      http.request(request)
+    def parse!(response, error)
+      JSON.parse(check!(response, error).body)
     end
 
     def request_headers

data/lib/nitro_intelligence/client/client.rb

@@ -2,8 +2,8 @@ require "nitro_intelligence/client/factory"
 
 module NitroIntelligence
   module Client
-    def self.new(observability_project_slug: nil)
-      Factory.new(observability_project_slug:).build
+    def self.new(observability_project_slug: nil, inference_max_retries: nil, inference_timeout: nil)
+      Factory.new(observability_project_slug:, inference_max_retries:, inference_timeout:).build
     end
 
     def self.validate_model(model)

data/lib/nitro_intelligence/client/factory.rb

@@ -6,8 +6,10 @@ require "nitro_intelligence/observability/project"
 module NitroIntelligence
   module Client
     class Factory
-      def initialize(observability_project_slug:)
+      def initialize(observability_project_slug:, inference_max_retries: nil, inference_timeout: nil)
         @observability_project_slug = observability_project_slug
+        @inference_max_retries = inference_max_retries
+        @inference_timeout = inference_timeout
       end
 
       def build
@@ -42,10 +44,16 @@ module NitroIntelligence
         project_client
       end
 
+      # The gateway owns failover between providers, and an upstream 429 it passes
+      # on has already been decided there, so the SDK's own retries default to off
+      # rather than to openai-ruby's two. A nil timeout keeps openai-ruby's default.
       def inference_client
+        config = NitroIntelligence.config
         @inference_client ||= OpenAI::Client.new(
-          api_key: NitroIntelligence.config.inference_api_key,
-          base_url: NitroIntelligence.config.inference_base_url
+          api_key: config.inference_api_key,
+          base_url: config.inference_base_url,
+          max_retries: @inference_max_retries.nil? ? config.inference_max_retries : @inference_max_retries,
+          **{ timeout: @inference_timeout || config.inference_timeout }.compact
         )
       end
     end

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

@@ -40,7 +40,9 @@ module NitroIntelligence
               },
             },
           }
-          parameters.replace(default_parameters.merge(parameters))
+          # Deep, so that request options a caller passes (headers, max_retries,
+          # timeout) sit alongside the image config rather than replacing it.
+          parameters.replace(default_parameters.deep_merge(parameters))
           Client.validate_model(parameters[:model])
         end
 

data/lib/nitro_intelligence/configuration.rb

@@ -13,6 +13,8 @@ module NitroIntelligence
     config_accessor :assistants_config, default: {}
     config_accessor :inference_api_key, default: ""
     config_accessor :inference_base_url, default: "https://inference.powerhome.ai"
+    config_accessor :inference_max_retries, default: 0
+    config_accessor :inference_timeout, default: nil
     config_accessor :model_config, default: {}
     config_accessor :observability_base_url, default: "https://cerebro.powerhome.ai"
     config_accessor :observability_projects, default: []

data/lib/nitro_intelligence/deprecator.rb

@@ -0,0 +1,10 @@
+require "active_support/deprecation"
+
+module NitroIntelligence
+  # Removed in the next major release. A Rails host has it registered with its own deprecators by
+  # the Railtie, so its `config.active_support` deprecation settings (log, raise, silence) apply;
+  # elsewhere it warns on stderr.
+  def self.deprecator
+    @deprecator ||= ActiveSupport::Deprecation.new("5.0", "nitro_intelligence")
+  end
+end

data/lib/nitro_intelligence/pending_review.rb

@@ -0,0 +1,222 @@
+require "active_support/core_ext/hash/indifferent_access"
+require "nitro_intelligence/review_decision"
+require "nitro_intelligence/tool_call_review_interrupt"
+require "nitro_intelligence/tool_call_review_validator"
+
+module NitroIntelligence
+  # What a paused run is waiting on: the interrupt the thread is holding, and the decisions that
+  # answer it.
+  #
+  # Assistants pauses for two kinds of review, never mixed in one interrupt:
+  #
+  # - tool calls, held by LangChain's `HumanInTheLoopMiddleware`, one action per call;
+  # - the run's final reply, a single action named `__reply__` whose `args` carry the draft's
+  #   `content`.
+  #
+  # A turn with tool calls only ever pauses on its tool calls, and the reply is the run's final
+  # message, so `#tool_calls` and `#reply` are never both present.
+  #
+  # Built from a thread state (`GET /threads/{id}/state`, which reports `interrupts`) or from the
+  # response of a paused `/runs/wait` (which reports `__interrupt__`); both carry the messages the
+  # tool calls are matched back onto.
+  class PendingReview
+    REPLY_ACTION = "__reply__".freeze
+
+    # What a reviewer may do with a reply. LangChain's `respond` supplies a tool's result, which a
+    # reply does not have, so it is never offered for one, whatever the interrupt lists.
+    REPLY_DECISIONS = %w[approve edit reject].freeze
+
+    KIND_NAMES = { tool_calls: "tool calls", reply: "a reply" }.freeze
+
+    # The draft reply a reviewer is asked to approve, edit or reject.
+    Reply = Struct.new(:content, :allowed_decisions, :description, :interrupt_id, keyword_init: true)
+
+    # The pending review in a thread state, or nil when the thread is not paused.
+    def self.from_thread_state(thread_state)
+      interrupt = Array(thread_state["interrupts"]).first
+      interrupt && new(interrupt:, messages: Array(thread_state.dig("values", "messages")))
+    end
+
+    # The pending review in a `/runs/wait` response, or nil when the run did not pause.
+    def self.from_run(run)
+      interrupt = Array(run["__interrupt__"]).first
+      interrupt && new(interrupt:, messages: Array(run["messages"]))
+    end
+
+    def initialize(interrupt:, messages:)
+      @interrupt = interrupt.to_h
+      @messages = messages
+    end
+
+    # Identifies this pause. A thread that has moved on -- a new message superseded the review, or
+    # another reviewer decided it first -- reports a different interrupt, or none.
+    def interrupt_id
+      @interrupt["id"] || @interrupt["interrupt_id"]
+    end
+
+    # `:tool_calls` or `:reply`.
+    def kind
+      action_name == REPLY_ACTION ? :reply : :tool_calls
+    end
+
+    def tool_calls?
+      kind == :tool_calls
+    end
+
+    def reply?
+      kind == :reply
+    end
+
+    # The tool calls the interrupt is holding, as `Assistants#tool_calls_under_review` reports them.
+    # Empty when the pause is on a reply.
+    def tool_calls
+      return [] unless tool_calls?
+
+      tool_call_interrupt.tool_calls
+    end
+
+    # The held draft, or nil when the pause is not on a reply.
+    def reply
+      return nil unless reply?
+
+      @reply ||= Reply.new(
+        content: action_args["content"],
+        allowed_decisions:,
+        description: action_requests.first["description"],
+        interrupt_id:
+      )
+    end
+
+    # The `command.resume` that sends `decisions` to this pause, keyed by its interrupt. LangGraph
+    # applies a keyed resume to that interrupt only: keyed by one that is no longer pending -- the
+    # thread moved on between reading this pause and resuming it -- it decides nothing, and the
+    # thread stays paused on the newer interrupt. An interrupt reported without an id can only be
+    # resumed unkeyed.
+    def resume(decisions)
+      interrupt_id.blank? ? { decisions: } : { interrupt_id => { decisions: } }
+    end
+
+    # Whether `run`, the response to a keyed resume of this pause, decided nothing because the
+    # interrupt was gone by the time the resume arrived. `run_id` is the run Assistants created for
+    # the resume, and the block reads the thread's state, only when it is needed.
+    #
+    # Such a resume comes back paused on the newer interrupt, exactly as a resume that was applied
+    # and paused again does -- a turn's tool calls decided, then the run's reply held. What tells
+    # them apart is who wrote the thread's latest checkpoint: Assistants records each run's id in
+    # the metadata of the checkpoints it writes, and a resume that decided nothing writes none, so
+    # the pause it reports still sits on a checkpoint an earlier run wrote.
+    #
+    # Best-effort, and only ever true on that evidence: without the run's id, the checkpoint's, or a
+    # state still on the reported pause (a new message may already have moved it on), or when the
+    # state cannot be read, it is false and the result stands as returned. That a stale decision is
+    # never applied is guaranteed by the keyed resume, not by this.
+    def unapplied_resume?(run:, run_id:)
+      paused_on = self.class.from_run(run)&.interrupt_id
+      return false if interrupt_id.blank? || run_id.blank? || paused_on.blank? || paused_on == interrupt_id
+
+      state = yield
+      writer = state.dig("metadata", "run_id")
+      self.class.from_thread_state(state)&.interrupt_id == paused_on && writer.present? && writer != run_id
+    rescue
+      false
+    end
+
+    # The `command.resume` decisions for a review of this pause, validated against what the
+    # interrupt allows before anything is built, raising `Assistants::ThreadResumptionError`.
+    #
+    # For a reply, `reviews` is a single review hash. For tool calls, it is either a hash of reviews
+    # keyed by tool call id, as `Assistants#review_tool_calls` has always taken them, or a list of
+    # reviews that each carry their tool call's `id`.
+    def decisions(reviews)
+      return [reply_decision(reviews)] if reply?
+
+      reviews = tool_call_reviews(reviews)
+      ToolCallReviewValidator.new.validate!(tool_calls: reviews, tool_calls_under_review: tool_calls)
+      tool_call_interrupt.decisions(reviews)
+    end
+
+  private
+
+    def tool_call_interrupt
+      @tool_call_interrupt ||= ToolCallReviewInterrupt.new(
+        "interrupts" => [@interrupt],
+        "values" => { "messages" => @messages }
+      )
+    end
+
+    def interrupt_value
+      @interrupt["value"] || {}
+    end
+
+    def action_requests
+      Array(interrupt_value["action_requests"])
+    end
+
+    def action_name
+      action_requests.first&.dig("name")
+    end
+
+    def action_args
+      action_requests.first["args"] || {}
+    end
+
+    def allowed_decisions
+      review_config = Array(interrupt_value["review_configs"]).find do |config|
+        config["action_name"] == action_name
+      end
+
+      Array(review_config&.dig("allowed_decisions")).map(&:to_s) & REPLY_DECISIONS
+    end
+
+    def tool_call_reviews(reviews)
+      return reviews unless reviews.is_a?(Array)
+
+      reviews.each_with_object({}) do |review, by_id|
+        unless review.is_a?(Hash) && review.with_indifferent_access[:id].present?
+          raise_error!("Each tool call review in a list must be a hash with the tool call's `id`")
+        end
+
+        review = review.with_indifferent_access
+        id = review[:id].to_s
+        raise_error!("Tool call `#{id}` is reviewed more than once") if by_id.key?(id)
+
+        by_id[id] = review.except(:id)
+      end
+    end
+
+    # A reply is a single action, so it is reviewed with a single hash.
+    def reply_decision(review)
+      raise_error!("The reply review must be a hash") unless review.is_a?(Hash)
+
+      review = review.with_indifferent_access
+      action = review[:action].to_s
+
+      unless allowed_decisions.include?(action)
+        raise_error!("Invalid review action `#{action}` for the reply; allowed: #{allowed_decisions.join(', ')}")
+      end
+
+      case action
+      when "approve" then ReviewDecision.approve
+      when "edit"
+        ReviewDecision.edit(REPLY_ACTION, { "content" => text!(review, :content, action:, required: true) })
+      when "reject" then ReviewDecision.reject(text!(review, :message, action:, required: false))
+      end
+    end
+
+    # A required field must be non-blank text; an optional one may be absent, but not something other
+    # than a String.
+    def text!(review, field, action:, required:)
+      value = review[field]
+      case ReviewDecision.message_problem(value, required:)
+      when :missing then raise_error!("A `#{action}` review of the reply must include a non-empty `#{field}`")
+      when :not_string then raise_error!("`#{field}` for the reply review must be a string")
+      end
+
+      value
+    end
+
+    def raise_error!(message)
+      raise Assistants::ThreadResumptionError, message
+    end
+  end
+end

data/lib/nitro_intelligence/railtie.rb

@@ -0,0 +1,9 @@
+require "nitro_intelligence/deprecator"
+
+module NitroIntelligence
+  class Railtie < ::Rails::Railtie
+    initializer "nitro_intelligence.deprecator" do |app|
+      app.deprecators[:nitro_intelligence] = NitroIntelligence.deprecator
+    end
+  end
+end

data/lib/nitro_intelligence/review_decision.rb

@@ -0,0 +1,34 @@
+module NitroIntelligence
+  # The `command.resume` decisions a review sends, and the check on the `message` a decision
+  # carries, shared by tool call reviews and reply reviews. Each caller keeps its own
+  # error wording, so this reports what is wrong rather than raising.
+  module ReviewDecision
+  module_function
+
+    def approve
+      { "type" => "approve" }
+    end
+
+    def edit(name, args)
+      { "type" => "edit", "edited_action" => { "name" => name, "args" => args } }
+    end
+
+    # The middleware falls back to its own wording when a rejection carries no reason.
+    def reject(message)
+      message.nil? ? { "type" => "reject" } : { "type" => "reject", "message" => message }
+    end
+
+    def respond(message)
+      { "type" => "respond", "message" => message }
+    end
+
+    # What is wrong with a decision's `message`, or nil: `:missing` when a required one is absent
+    # or blank, `:not_string` when one is given as anything but a String.
+    def message_problem(message, required:)
+      return (:missing if required) if message.nil?
+      return :not_string unless message.is_a?(String)
+
+      :missing if required && message.blank?
+    end
+  end
+end

data/lib/nitro_intelligence/run_result.rb

@@ -0,0 +1,129 @@
+require "nitro_intelligence/pending_review"
+
+module NitroIntelligence
+  # The outcome of one `/runs/wait`: either the run ended, possibly with a reply, or it paused on a
+  # review.
+  #
+  # A run has at most one reply: its final message, an AI message with text and no tool calls. Text
+  # the model writes alongside tool calls is working text, never the reply. A paused run's last AI
+  # message is a draft awaiting review, so `#reply` is nil whenever the run paused; a reply is final
+  # only once a run ends without `__interrupt__`.
+  class RunResult
+    # How the platform delivered the reply through the assistant's delivery tool, read from the
+    # reply's `response_metadata.delivery` stamp. `status` is "delivered" (with `result`, what the
+    # tool returned, and `delivered_at`), "failed" (with the tool's `error` and `failed_at`), or
+    # "pending": the platform stamps a settled reply "pending" just before it delivers it, so a
+    # finished run still showing it was cut off before delivery recorded an outcome. Treat a
+    # pending reply as not sent; the next customer message removes it and the model answers both. A
+    # field the stamp does not carry, or carries as the wrong type, is nil.
+    Delivery = Struct.new(:status, :tool, :attempts, :error, :result, :delivered_at, :failed_at,
+                          keyword_init: true) do
+      def delivered?
+        status == "delivered"
+      end
+
+      def failed?
+        status == "failed"
+      end
+
+      def pending?
+        status == "pending"
+      end
+    end
+
+    # The `response_metadata.review` type the platform stamps on a draft when it pauses on it.
+    PENDING_REVIEW = "pending".freeze
+
+    # The response exactly as Assistants returned it.
+    attr_reader :raw
+
+    def initialize(run)
+      @raw = run.to_h
+    end
+
+    def interrupted?
+      Array(raw["__interrupt__"]).any?
+    end
+
+    # What the paused run is waiting on, or nil when it did not pause.
+    def review
+      return @review if defined?(@review)
+
+      @review = PendingReview.from_run(raw)
+    end
+
+    # The run's messages as Assistants reports them, oldest first.
+    def messages
+      Array(raw["messages"])
+    end
+
+    # The text of the run's reply, always a String: content given as blocks is reduced to its text.
+    # Nil while the run is paused, and when it ended without one: a rejected draft is removed,
+    # leaving a tool result or the human's message last, and an earlier turn's text is never the
+    # reply. Blank text is no reply.
+    def reply
+      reply_message && text(reply_message["content"]).presence
+    end
+
+    # The reply's delivery, or nil when the reply carries no delivery stamp: no reply, or no
+    # delivery tool configured for the assistant.
+    def delivery
+      return @delivery if defined?(@delivery)
+
+      stamp = reply_message&.dig("response_metadata", "delivery")
+      @delivery = stamp.is_a?(Hash) ? build_delivery(stamp) : nil
+    end
+
+  private
+
+    # The run's last message, when the run ended and that message is the assistant's reply: an AI
+    # message with no tool calls. A draft still stamped as awaiting review is never the reply, even
+    # in a response that reports no pause.
+    def reply_message
+      return nil if interrupted?
+
+      message = messages.last
+      return nil unless message.is_a?(Hash)
+      return nil if message["type"].present? && message["type"] != "ai"
+      return nil if Array(message["tool_calls"]).any?
+      return nil if awaiting_review?(message)
+
+      message
+    end
+
+    def awaiting_review?(message)
+      review = message.dig("response_metadata", "review")
+      review.is_a?(Hash) && review["type"] == PENDING_REVIEW
+    end
+
+    # A message's content is a string, or a list of content blocks. Its text is the string, or the
+    # bare strings and `text` blocks joined, as the platform reads it (LangChain's `message.text`);
+    # other blocks -- tool use, reasoning, images -- are not part of the reply.
+    def text(content)
+      return content if content.is_a?(String)
+      return nil unless content.is_a?(Array)
+
+      content.filter_map do |block|
+        next block if block.is_a?(String)
+
+        block["text"] if block.is_a?(Hash) && block["type"] == "text" && block["text"].is_a?(String)
+      end.join
+    end
+
+    def build_delivery(stamp)
+      Delivery.new(
+        status: string_or_nil(stamp["status"]),
+        tool: string_or_nil(stamp["tool"]),
+        attempts: stamp["attempts"].is_a?(Integer) ? stamp["attempts"] : nil,
+        error: string_or_nil(stamp["error"]),
+        result: stamp["result"],
+        delivered_at: string_or_nil(stamp["delivered_at"]),
+        failed_at: string_or_nil(stamp["failed_at"])
+      )
+    end
+
+    def string_or_nil(value)
+      value.is_a?(String) ? value : nil
+    end
+  end
+end

data/lib/nitro_intelligence/tool_call_review_interrupt.rb

@@ -1,4 +1,5 @@
 require "active_support/core_ext/hash/indifferent_access"
+require "nitro_intelligence/review_decision"
 
 module NitroIntelligence
   # The tool calls one interrupt is holding, and the resume payload that answers them.
@@ -68,14 +69,10 @@ module NitroIntelligence
       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] }
+      when "approve" then ReviewDecision.approve
+      when "edit" then ReviewDecision.edit(tool_call["name"], edited_args(tool_call, review))
+      when "reject" then ReviewDecision.reject(review[:message])
+      when "respond" then ReviewDecision.respond(review[:message])
       else
         raise Assistants::ThreadResumptionError,
               "Tool call #{tool_call['id']} has no review naming `approve`, `edit`, `reject` or `respond`"
@@ -84,11 +81,8 @@ module NitroIntelligence
 
     # 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] || {}),
-      }
+    def edited_args(tool_call, review)
+      tool_call["args"].merge(review[:args] || {})
     end
 
     def interrupt_value

data/lib/nitro_intelligence/tool_call_review_validator.rb

@@ -1,4 +1,5 @@
 require "active_support/core_ext/hash/indifferent_access"
+require "nitro_intelligence/review_decision"
 
 module NitroIntelligence
   # The reviews a caller submitted, checked against the tool calls the interrupt is holding, before
@@ -72,15 +73,10 @@ module NitroIntelligence
     end
 
     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
+      case ReviewDecision.message_problem(review[:message], required:)
+      when :missing then raise_error!("Review for tool call #{tool_call_id} must include a message")
+      when :not_string then raise_error!("Message for tool call #{tool_call_id} must be a string")
       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:)

data/lib/nitro_intelligence/version.rb

@@ -1,3 +1,3 @@
 module NitroIntelligence
-  VERSION = "3.1.0".freeze
+  VERSION = "4.0.0".freeze
 end

data/lib/nitro_intelligence.rb

@@ -11,6 +11,7 @@ require "nitro_intelligence/assistants"
 require "nitro_intelligence/client/base"
 require "nitro_intelligence/client/client"
 require "nitro_intelligence/configuration"
+require "nitro_intelligence/deprecator"
 require "nitro_intelligence/media/image_generation"
 require "nitro_intelligence/models/model_catalog"
 require "nitro_intelligence/observability/project_client_registry"
@@ -48,3 +49,5 @@ module NitroIntelligence
     end
   end
 end
+
+require "nitro_intelligence/railtie" if defined?(Rails::Railtie)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nitro_intelligence
 version: !ruby/object:Gem::Version
-  version: 3.1.0
+  version: 4.0.0
 platform: ruby
 authors:
 - Igor Artemenko
@@ -93,6 +93,7 @@ files:
 - lib/nitro_intelligence/client/observed.rb
 - lib/nitro_intelligence/client/observers/langfuse_observer.rb
 - lib/nitro_intelligence/configuration.rb
+- lib/nitro_intelligence/deprecator.rb
 - lib/nitro_intelligence/langfuse_extension.rb
 - lib/nitro_intelligence/langfuse_tracer_provider.rb
 - lib/nitro_intelligence/media/audio.rb
@@ -110,7 +111,11 @@ files:
 - lib/nitro_intelligence/observability/prompt_resolver.rb
 - lib/nitro_intelligence/observability/prompt_store.rb
 - lib/nitro_intelligence/observability/upload_handler.rb
+- lib/nitro_intelligence/pending_review.rb
+- lib/nitro_intelligence/railtie.rb
 - lib/nitro_intelligence/reporter.rb
+- lib/nitro_intelligence/review_decision.rb
+- lib/nitro_intelligence/run_result.rb
 - lib/nitro_intelligence/tool_call_review_interrupt.rb
 - lib/nitro_intelligence/tool_call_review_validator.rb
 - lib/nitro_intelligence/trace.rb