nitro_intelligence 3.0.2 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: feb0fe8d0b4ae0d1da8564f048fa7130dc78318622a23a86163edc65d2f37dbf
-  data.tar.gz: 122277bfc6b70b0aeb67166624458f37f50b1ed2b1a77044ade87575ea101bb1
+  metadata.gz: 03f41090e337bd4b4ba8f5caf040355d4b8cfca9d81ffcc9b7a8d91eec2ad64e
+  data.tar.gz: 0f83490e7d57c8935cdda63579126c3a4d93b22849c1f0f6015948b94ccbb6b8
 SHA512:
-  metadata.gz: bf69e4777017afa0be7457612c42aadf434921c083b3a199e13a0682959b6579494793069e2548c592dd022ac5a96d342155549cfa5d36fdf798bd0a05bd647f
-  data.tar.gz: 18854e89e04d994bddc0315296d5f21ad2551dd9b7d64d01efda6aadc25dbcd0858d1e8f24dacb2f2b261b2b65ab1bb3fe747956f5064ce6ef176b017e59b712
+  metadata.gz: f908c8f5cfdb7b2b56eb0d4316c1855b6fbdb25ac7355fb0390bbaa42f794e92f44ccc66255c9c8dfcd1b4c552ef8af554f933d3c23f6389a3ec6164b31b6c13
+  data.tar.gz: 55b75e6f31b185d3ade2f8939b8ecae69a41a6c54a3df7a1cc8405424b6762e8a788e3e4c4f8680626f4abe638d8027c69fc3e3a4cb2d590b2c196f7faec16f3

data/Rakefile

@@ -1,6 +1,8 @@
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
+require "rubocop/rake_task"
 
 RSpec::Core::RakeTask.new(:spec)
+RuboCop::RakeTask.new
 
-task default: :spec
+task default: %i[spec rubocop]

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.
@@ -323,7 +343,7 @@ client.chat(
 
 ### Custom Trace IDs
 
-To generate a deterministic trace ID in the observability platform, you can pass `trace_seed` as a parameter. This is useful when you want a stable identifier that is derived from a specific domain value (e.g., document ID). The same `trace_seed` will produce the same trace ID, making it easier to correlate multiple events.
+To generate a deterministic trace ID in the observability platform, you can pass `trace_seed` as a parameter. This is useful when you want a stable identifier that is derived from a specific domain value (e.g., document ID). The same `trace_seed` will produce the same trace ID, making it easier to correlate multiple events. Each seeded call creates a root observation in that trace, including when another observation is active. With Langfuse v4 event reads, trace input and output come from the most recently ingested root observation. Calls without a seed keep their active parent observation.
 
 ```ruby
 document_id = "document-123"
@@ -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.
 
@@ -424,6 +462,16 @@ trace_id = NitroIntelligence::Trace.create_id(seed: document_id)
 reporter.score(name: "precision", value: 0.5, trace_id:)
 ```
 
+#### Using different data types for scoring
+
+By default, scores submitted on a trace are numeric, but you can use the `data_type` keyword to change it to `:boolean` or `:categorical`. For example:
+
+```ruby
+reporter.score(name: "precision", value: "Partially Correct", trace_id:, data_type: :categorical)
+```
+
+Numeric data is helpful for scores that happen on a sliding scale, like success rate or percent similarity. Boolean data is helpful to convey something that either passes or fails. Categorical data is helpful for scores that have pre-defined categories, like "Correct", "Partially Correct", and "Incorrect".
+
 ### Prompts
 
 #### Message Shape
@@ -552,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).
 
@@ -563,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)