nitro_intelligence 4.0.0 → 4.1.0

data/lib/nitro_intelligence/observability/upload_handler.rb

@@ -7,6 +7,7 @@ require "uri"
 
 module NitroIntelligence
   module Observability
+    # @api private
     class UploadHandler
       attr_reader :uploaded_media
 
@@ -58,7 +59,7 @@ module NitroIntelligence
         payload
       end
 
-      def upload(trace_id, upload_queue: Queue.new)
+      def upload(trace_id, observation_id:, upload_queue: Queue.new)
         until upload_queue.empty?
           media = upload_queue.pop
 
@@ -68,6 +69,7 @@ module NitroIntelligence
           # returns {"mediaId" -> "", "uploadUrl" => ""}
           upload_url_response = get_upload_url({
                                                  traceId: trace_id,
+                                                 observationId: observation_id,
                                                  contentType: media.mime_type,
                                                  contentLength: content_length,
                                                  sha256Hash: content_sha256,

data/lib/nitro_intelligence/pending_review.rb

@@ -20,29 +20,46 @@ module NitroIntelligence
   # response of a paused `/runs/wait` (which reports `__interrupt__`); both carry the messages the
   # tool calls are matched back onto.
   class PendingReview
+    # @api private
     REPLY_ACTION = "__reply__".freeze
 
+    # @api private
     # 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
 
+    # @api private
     KIND_NAMES = { tool_calls: "tool calls", reply: "a reply" }.freeze
 
     # The draft reply a reviewer is asked to approve, edit or reject.
+    #
+    # @!attribute [r] content
+    #   @return [String] the draft
+    # @!attribute [r] allowed_decisions
+    #   @return [Array<String>] what the reviewer may do, from `approve`, `edit` and `reject`
+    # @!attribute [r] description
+    #   @return [String, nil] the guidance the pause gives the reviewer
+    # @!attribute [r] interrupt_id
+    #   @return [String] the pause, as {PendingReview#interrupt_id}
     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.
+    #
+    # @api private
     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.
+    #
+    # @api private
     def self.from_run(run)
       interrupt = Array(run["__interrupt__"]).first
       interrupt && new(interrupt:, messages: Array(run["messages"]))
     end
 
+    # @api private
     def initialize(interrupt:, messages:)
       @interrupt = interrupt.to_h
       @messages = messages
@@ -50,25 +67,35 @@ module NitroIntelligence
 
     # 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.
+    #
+    # @return [String, nil] nil for a tool-call pause the service reported without an id, which
+    #   {Assistants#review} then resumes without checking that it is still the same pause
     def interrupt_id
       @interrupt["id"] || @interrupt["interrupt_id"]
     end
 
-    # `:tool_calls` or `:reply`.
+    # What the run is paused on.
+    #
+    # @return [Symbol] `:tool_calls` or `:reply`
     def kind
       action_name == REPLY_ACTION ? :reply : :tool_calls
     end
 
+    # @return [Boolean] whether the run is paused on its tool calls
     def tool_calls?
       kind == :tool_calls
     end
 
+    # @return [Boolean] whether the run is paused on its reply
     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.
+    #
+    # @return [Array<Hash>] each with `previous_message_id`, `id`, `name`, `args` and
+    #   `allowed_decisions`
     def tool_calls
       return [] unless tool_calls?
 
@@ -76,6 +103,8 @@ module NitroIntelligence
     end
 
     # The held draft, or nil when the pause is not on a reply.
+    #
+    # @return [Reply, nil]
     def reply
       return nil unless reply?
 
@@ -92,6 +121,8 @@ module NitroIntelligence
     # 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.
+    #
+    # @api private
     def resume(decisions)
       interrupt_id.blank? ? { decisions: } : { interrupt_id => { decisions: } }
     end
@@ -110,6 +141,8 @@ module NitroIntelligence
     # 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.
+    #
+    # @api private
     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
@@ -127,6 +160,8 @@ module NitroIntelligence
     # 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`.
+    #
+    # @api private
     def decisions(reviews)
       return [reply_decision(reviews)] if reply?
 

data/lib/nitro_intelligence/railtie.rb

@@ -1,6 +1,7 @@
 require "nitro_intelligence/deprecator"
 
 module NitroIntelligence
+  # @api private
   class Railtie < ::Rails::Railtie
     initializer "nitro_intelligence.deprecator" do |app|
       app.deprecators[:nitro_intelligence] = NitroIntelligence.deprecator

data/lib/nitro_intelligence/reporter.rb

@@ -3,15 +3,33 @@ require "net/http"
 require "uri"
 
 module NitroIntelligence
+  # Records evaluations of traces in Cerebro.
+  #
+  # @example
+  #   reporter = NitroIntelligence::Reporter.new(observability_project_slug: "my-feature-project")
+  #   reporter.score(name: "precision", value: 0.5, trace_id:)
   class Reporter
+    # Raised by {#create_dataset_item} when Cerebro does not store the item. The message carries the
+    # response's status and body.
     class DatasetItemError < StandardError; end
 
+    # @param observability_project_slug [String] the Cerebro project the traces are recorded in
+    # @raise [Observability::Project::NotFoundError] when `observability_projects` does not configure
+    #   the project
     def initialize(observability_project_slug:)
       @observability_project_slug = observability_project_slug
       @project_client = fetch_project_client
       @host = NitroIntelligence.config.observability_base_url
     end
 
+    # Adds an item to a dataset in the project, for evaluating prompts against later.
+    #
+    # @param attributes [Hash] the item, as Langfuse's `POST /api/public/dataset-items` takes it:
+    #   `datasetName`, `input`, `expectedOutput`, `metadata`, `sourceTraceId` and the rest
+    # @return [Net::HTTPSuccess] the response
+    # @raise [DatasetItemError] when Cerebro does not store the item
+    # @example
+    #   reporter.create_dataset_item({ datasetName: "sms-screening", input: { message: }, expectedOutput: "yes" })
     def create_dataset_item(attributes)
       uri = URI("#{@host}/api/public/dataset-items")
       http = Net::HTTP.new(uri.host, uri.port)
@@ -35,6 +53,17 @@ module NitroIntelligence
       response
     end
 
+    # Scores a trace. Scoring it again under the same `id` replaces the score.
+    #
+    # @param trace_id [String] the trace, such as {Trace.create_id} gives for a seed
+    # @param name [String] what the score measures
+    # @param value [Numeric, String, Boolean] the score: a number, `true` or `false` for `:boolean`,
+    #   or the category's name for `:categorical`
+    # @param id [String] identifies the score, so that recording it again replaces it. Defaults to
+    #   one per trace and name.
+    # @param data_type [Symbol] `:numeric`, `:boolean` or `:categorical`
+    # @return [void]
+    # @raise [ArgumentError] when `value` does not suit `data_type`
     def score(trace_id:, name:, value:, id: "#{trace_id}-#{name}", data_type: :numeric)
       @project_client.observability_client.create_score(
         id:,

data/lib/nitro_intelligence/review_decision.rb

@@ -2,6 +2,8 @@ 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.
+  #
+  # @api private
   module ReviewDecision
   module_function
 

data/lib/nitro_intelligence/run_result.rb

@@ -16,36 +16,61 @@ module NitroIntelligence
     # 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)
 
@@ -53,6 +78,8 @@ module NitroIntelligence
     end
 
     # The run's messages as Assistants reports them, oldest first.
+    #
+    # @return [Array<Hash>]
     def messages
       Array(raw["messages"])
     end
@@ -61,12 +88,16 @@ module NitroIntelligence
     # 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)
 

data/lib/nitro_intelligence/tool_call_review_interrupt.rb

@@ -11,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

data/lib/nitro_intelligence/tool_call_review_validator.rb

@@ -8,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)

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 = "4.0.0".freeze
+  # The gem's version.
+  VERSION = "4.1.0".freeze
 end

data/lib/nitro_intelligence.rb

@@ -17,16 +17,48 @@ 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)
@@ -34,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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nitro_intelligence
 version: !ruby/object:Gem::Version
-  version: 4.0.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,18 @@ 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