nitro_intelligence 3.1.0 → 4.1.0

data/lib/nitro_intelligence/run_result.rb

@@ -0,0 +1,160 @@
+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.
+    #
+    # @!attribute [r] status
+    #   @return [String, nil] `"delivered"`, `"failed"` or `"pending"`
+    # @!attribute [r] tool
+    #   @return [String, nil] the delivery tool's name
+    # @!attribute [r] attempts
+    #   @return [Integer, nil] how many times the platform called the tool
+    # @!attribute [r] error
+    #   @return [String, nil] the tool's error, when delivery failed
+    # @!attribute [r] result
+    #   @return [Object, nil] what the tool returned, when it succeeded
+    # @!attribute [r] delivered_at
+    #   @return [String, nil] when the reply was delivered, as an ISO 8601 timestamp
+    # @!attribute [r] failed_at
+    #   @return [String, nil] when delivery gave up, as an ISO 8601 timestamp
+    Delivery = Struct.new(:status, :tool, :attempts, :error, :result, :delivered_at, :failed_at,
+                          keyword_init: true) do
+      # @return [Boolean] whether the platform delivered the reply
+      def delivered?
+        status == "delivered"
+      end
+
+      # @return [Boolean] whether delivery failed
+      def failed?
+        status == "failed"
+      end
+
+      # @return [Boolean] whether delivery was cut off before it recorded an outcome
+      def pending?
+        status == "pending"
+      end
+    end
+
+    # @api private
+    # 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.
+    #
+    # @return [Hash]
+    attr_reader :raw
+
+    # @api private
+    def initialize(run)
+      @raw = run.to_h
+    end
+
+    # @return [Boolean] whether the run paused for review
+    def interrupted?
+      Array(raw["__interrupt__"]).any?
+    end
+
+    # What the paused run is waiting on, or nil when it did not pause.
+    #
+    # @return [PendingReview, nil]
+    def review
+      return @review if defined?(@review)
+
+      @review = PendingReview.from_run(raw)
+    end
+
+    # The run's messages as Assistants reports them, oldest first.
+    #
+    # @return [Array<Hash>]
+    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.
+    #
+    # @return [String, nil]
+    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.
+    #
+    # @return [Delivery, nil]
+    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.
@@ -10,6 +11,8 @@ module NitroIntelligence
   # Action requests carry no tool call id, and ids are what a review interface works in, so each is
   # matched back onto the tool calls of the thread's last AI message -- the ones the middleware built
   # them from -- to recover the id. The order of `#tool_calls` is the order `decisions` must be in.
+  #
+  # @api private
   class ToolCallReviewInterrupt
     def initialize(thread_state)
       @thread_state = thread_state
@@ -68,14 +71,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 +83,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
@@ -7,6 +8,8 @@ module NitroIntelligence
   # Internal to `Assistants#review_tool_calls`, which builds the only instance there is. What
   # `#validate!` takes follows what that method needs and has changed with it before, so it carries
   # no promise to anything calling it directly.
+  #
+  # @api private
   class ToolCallReviewValidator
     def validate!(tool_calls:, tool_calls_under_review:)
       tool_calls = normalize_tool_calls(tool_calls)
@@ -72,15 +75,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/trace.rb

@@ -1,5 +1,13 @@
 module NitroIntelligence
+  # Trace IDs, for correlating an observed request with what else a host records about it.
   module Trace
+    # The ID of the trace a request passing `trace_seed: seed` is recorded under. The same seed
+    # always gives the same ID.
+    #
+    # @param seed [String] the request's `trace_seed`, such as a document's ID
+    # @return [String] the trace ID
+    # @example
+    #   NitroIntelligence::Trace.create_id(seed: "document-123")
     def self.create_id(seed:)
       Langfuse::TraceId.create(seed:)
     end

data/lib/nitro_intelligence/version.rb

@@ -1,3 +1,4 @@
 module NitroIntelligence
-  VERSION = "3.1.0".freeze
+  # The gem's version.
+  VERSION = "4.1.0".freeze
 end

data/lib/nitro_intelligence.rb

@@ -11,21 +11,54 @@ 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"
 require "nitro_intelligence/reporter"
 
+# The Ruby client for the Nitro Intelligence Platform.
+#
+# The public API is everything in this reference not marked `@api private`, and follows Semantic
+# Versioning. `docs/README.md` and `docs/ASSISTANTS.md` are guides to using it, not a list of
+# everything public. What the reference leaves out may change in any release.
 module NitroIntelligence
+  # @!attribute [rw] configuration
+  #   @api private
+  #   @return [Class<Configuration>]
   mattr_accessor :configuration, default: Configuration
 
   class << self
+    # @!method configure
+    #   Sets the configuration, normally once, from an initializer.
+    #   @yieldparam config [ActiveSupport::Configurable::Configuration] the settings that
+    #     {Configuration} lists
+    #   @return [void]
+    #   @example
+    #     NitroIntelligence.configure do |config|
+    #       config.inference_api_key = ENV.fetch("NITRO_INTELLIGENCE_API_KEY")
+    #     end
+    # @!method config
+    #   The current configuration.
+    #   @return [ActiveSupport::Configurable::Configuration] the settings that {Configuration} lists
+    # @!method logger
+    #   @api private
+    # @!method environment
+    #   @api private
     delegate :configure, :config, :logger, :environment, to: :configuration
 
     # A registry addressable by name when `assistants_config` carries `definitions`, and the
     # single pre-registry client otherwise. The two shapes are mutually exclusive, so the
     # configuration decides which one a host gets: one that has not reshaped its config keeps
     # the client it already had.
+    #
+    # @return [AssistantRegistry, Assistants]
+    # @raise [ArgumentError] without `definitions`, when `assistants_config` has no `api_key`, as
+    #   it does by default
+    # @raise [Assistants::ConfigurationError] without `definitions`, when `assistants_config`
+    #   has a blank `api_key` or `user_id`
+    # @example
+    #   NitroIntelligence.assistants["candidate-concierge"].run(thread_id:, messages:)
     def assistants
       current = configuration.assistants_config.to_h.deep_stringify_keys
       return AssistantRegistry.new(current) if current.key?(AssistantRegistry::DEFINITIONS_KEY)
@@ -33,14 +66,19 @@ module NitroIntelligence
       Assistants.new(**current.symbolize_keys)
     end
 
+    # @api private
     def cache
       configuration.cache_provider
     end
 
+    # @api private
     def model_catalog
       @model_catalog ||= ModelCatalog.new(configuration.model_config)
     end
 
+    # Each Cerebro project's client.
+    #
+    # @return [Observability::ProjectClientRegistry]
     def project_client_registry
       @project_client_registry ||= Observability::ProjectClientRegistry.new(
         base_url: configuration.observability_base_url
@@ -48,3 +86,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.1.0
 platform: ruby
 authors:
 - Igor Artemenko
@@ -72,7 +72,10 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".yardopts"
 - Rakefile
+- docs/ASSISTANTS.md
+- docs/CHANGELOG.md
 - docs/README.md
 - lib/nitro_intelligence.rb
 - lib/nitro_intelligence/assistant.rb
@@ -84,15 +87,19 @@ files:
 - lib/nitro_intelligence/client/handlers/audio_transcription_handler.rb
 - lib/nitro_intelligence/client/handlers/base_handler.rb
 - lib/nitro_intelligence/client/handlers/chat_handler.rb
+- lib/nitro_intelligence/client/handlers/decision_handler.rb
 - lib/nitro_intelligence/client/handlers/image_handler.rb
 - lib/nitro_intelligence/client/handlers/observed/audio_transcription_handler.rb
 - lib/nitro_intelligence/client/handlers/observed/chat_handler.rb
+- lib/nitro_intelligence/client/handlers/observed/decision_handler.rb
 - lib/nitro_intelligence/client/handlers/observed/image_handler.rb
 - lib/nitro_intelligence/client/handlers/observed/text_to_speech_handler.rb
 - lib/nitro_intelligence/client/handlers/text_to_speech_handler.rb
 - lib/nitro_intelligence/client/observed.rb
 - lib/nitro_intelligence/client/observers/langfuse_observer.rb
 - lib/nitro_intelligence/configuration.rb
+- lib/nitro_intelligence/decision.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 +117,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