nitro_intelligence 2.0.0 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9c03a8a4c436205c01d926c024c1bcd12542553f36e3998b10462653cec4cdc1
-  data.tar.gz: 58f340818e47d7b6e36dd84f44b4072bf8636a83d4fd6931e65e62ec1ed29ab5
+  metadata.gz: 1181b17cc855ffa2f039b1401fd5dd2040c262d2878e6d265e65f9a581f6106e
+  data.tar.gz: 28b3a022b8d6d7e8e8472930fcf089fa5a3ead8a6c0d917e7587a73b69b8fba5
 SHA512:
-  metadata.gz: 70eab830245ab3c7bd4a6835c080770ee324dca9c440ba200f0ac29fc528e9b4be5579091259a9abed7c35ce51372da82d4452d1df71ee26c51a61bdb342acaa
-  data.tar.gz: 549cd0d2477d1382cff28d866266797983b0ddd860396c10ff5edd8087f5538a4834b1194d1ae6d5d16d497825bf660308bcacfcb3da12846e2f69ef611264a4
+  metadata.gz: e5fd5911aa6740d71f9dc5564766fe80137d7c2da6e7195ee406649387a22a8387bc02db78671e643d90445c6b8578e2b7b47d7573d4abdf677b35edcc41c6a3
+  data.tar.gz: d11585c4f9731911910660e67eb8702634475fd7bbf523b7313c81910d2775852f918a789a669719840196d64c474c1452842f6948e7618563ee1d5b2a1cd5e1

data/docs/README.md

@@ -254,6 +254,49 @@ client.chat(
 
 If no `prompt_label` or `prompt_version` is provided, the 'production' prompt is used by default.
 
+### Prompt Fallbacks
+
+Pass `prompt_fallback_name` to name a second prompt to use when the one you asked for isn't there. The prompt in `prompt_name` is tried first; if it doesn't exist, or its lookup fails, the fallback is used instead:
+
+```ruby
+client = NitroIntelligence::Client.new(observability_project_slug: "fake-feature-project")
+client.chat(
+  message: "Why is the sky blue?",
+  parameters: {
+    prompt_name: "My Prompt - Scheduling", # used when it exists
+    prompt_fallback_name: "My Prompt",     # used when it doesn't
+    # prompt_fallback_label: "debug",
+    # prompt_fallback_version: "v2",
+    prompt_variables: {
+      appointment_id: "1234",
+    },
+  }
+)
+```
+
+This is for shipping a variant of a prompt — per domain, per locale, per experiment — without having to create one for every caller. Build the specific name however your feature likes; the fallback is just the prompt you'd have asked for anyway.
+
+In practice the caller composes the specific name from something it already knows. Summarising a call, for example: each queue holds a different kind of conversation, so a queue that needs its own wording can have its own prompt while the rest use the general one.
+
+```ruby
+base = "call_summary"
+queue = call.queue.slug # "sales", "support", "collections", ...
+
+client.chat(
+  parameters: {
+    prompt_name: [base, queue].compact.join("."), # call_summary.collections
+    prompt_fallback_name: base,
+    prompt_variables: { transcript: call.transcript },
+  }
+)
+```
+
+The fallback is looked up at its own `prompt_fallback_label` and `prompt_fallback_version`, and inherits neither from the prompt you asked for first. They describe a different prompt: a version number is minted per prompt, so version 3 of one name is an unrelated revision of another, and a label the first prompt carries need not exist on the fallback at all.
+
+That means an omitted `prompt_fallback_label` resolves the fallback the same way any unlabelled lookup does — at the 'production' label. **If you want both prompts to come from the same label, name it for both.**
+
+Whichever prompt is used is the one linked to the trace and merged into your request. If the fallback is missing too, the error is raised rather than swallowed — a request that asked for a prompt shouldn't quietly run without one.
+
 ### Custom Trace Names
 
 To provide custom trace names to the observability platform, you can pass 'trace_name' in parameters. Example:

data/lib/nitro_intelligence/agent_server.rb

@@ -10,6 +10,9 @@ module NitroIntelligence
     class RunError < StandardError; end
     class ThreadResumptionError < StandardError; end
 
+    # Aegra answers with a conflict when `ifExists: "raise"` is sent for a thread that already exists.
+    THREAD_CONFLICT_CODE = 409
+
     attr_reader :base_url, :user_id
 
     def initialize(base_url:, api_key:, user_id: "default-user")
@@ -21,6 +24,7 @@ module NitroIntelligence
       @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: {})
@@ -29,7 +33,7 @@ module NitroIntelligence
       initial_state = messages[0..-2]
       last_message = messages.last
 
-      initialize_thread_if_needed(thread_id:, initial_state:)
+      initialize_thread_if_needed(thread_id:, assistant_id:, initial_state:)
       trigger_run(thread_id:, assistant_id:, context:, last_message:)
     end
 
@@ -77,20 +81,78 @@ module NitroIntelligence
 
   private
 
-    def initialize_thread_if_needed(thread_id:, initial_state:)
-      thread_response = post(
+    # Aegra accepts `initial_state` on thread creation but never applies it, so a brand new thread is
+    # seeded through the thread state endpoint instead. A thread that already exists is left untouched:
+    # its state was seeded when it was created and has been built up by every run since.
+    def initialize_thread_if_needed(thread_id:, assistant_id:, initial_state:)
+      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
+      return if initial_state.blank?
+
+      seed_new_thread_state(thread_id:, initial_state:)
+    end
+
+    # Creating the thread and seeding its state are separate requests, so a failure between them leaves
+    # an empty thread behind. A retry would find that thread, take it for one already under way, skip
+    # seeding and run without the history -- losing the very thing seeding exists for, without an error.
+    # Discard the thread instead, so a retry starts over from a clean slate.
+    def seed_new_thread_state(thread_id:, initial_state:)
+      seed_thread_state(thread_id:, initial_state:)
+    rescue
+      discard_thread(thread_id:)
+      raise
+    end
+
+    def discard_thread(thread_id:)
+      delete(path: "/threads/#{thread_id}")
+    rescue
+      # Best effort. The seeding failure is the one worth surfacing, and it is raised either way.
+    end
+
+    def create_thread(thread_id:, assistant_id:)
+      post(
         path: "/threads",
         body: {
           threadId: thread_id.to_s,
-          ifExists: "do_nothing",
-          initial_state: { messages: initial_state },
+          ifExists: "raise",
+          # Without a graph_id, the thread state cannot be updated before the thread's first run.
+          metadata: { graph_id: graph_id_for(assistant_id) },
           user_id:,
         }
       )
+    end
 
-      raise ThreadInitializationError, thread_response.body if thread_response.code.to_i != 200
+    def graph_id_for(assistant_id)
+      @graph_ids[assistant_id] ||= fetch_graph_id(assistant_id)
+    end
 
-      JSON.parse(thread_response.body)
+    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"]
+
+      raise ThreadInitializationError, "Assistant #{assistant_id} has no graph_id" if graph_id.blank?
+
+      graph_id
+    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)
+    end
+
+    def thread_already_exists?(response)
+      response.code.to_i == THREAD_CONFLICT_CODE
     end
 
     def get_thread_state(thread_id:)
@@ -177,6 +239,17 @@ module NitroIntelligence
       http.request(request)
     end
 
+    def delete(path:)
+      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_headers.each { |k, v| request[k] = v }
+
+      http.request(request)
+    end
+
     def post(path:, body:)
       uri = URI("#{base_url}#{path}")
       http = Net::HTTP.new(uri.host, uri.port)

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

@@ -1,21 +1,19 @@
 require "openai"
+require "nitro_intelligence/client/handlers/base_handler"
 
 module NitroIntelligence
   module Client
     module Handlers
-      class AudioTranscriptionHandler
+      class AudioTranscriptionHandler < BaseHandler
         ALLOWED_EXTRA_PARAMETERS = OpenAI::Models::Audio::TranscriptionCreateParams.fields.keys.uniq.freeze
 
-        def initialize(client:)
-          @client = client
-        end
-
         def create(audio_file:, message: "", parameters: {})
           validate_and_resolve!(parameters)
           perform_request(audio_file:, message:, parameters:)
         end
 
         def perform_request(audio_file:, message: "", parameters: {})
+          add_request_headers(parameters, MODALITY_HEADER => "audio", REQUESTED_MODEL_HEADER => parameters[:model])
           @client.audio.transcriptions.create(
             prompt: message,
             file: audio_file,

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

@@ -0,0 +1,22 @@
+module NitroIntelligence
+  module Client
+    module Handlers
+      class BaseHandler
+        MODALITY_HEADER = "nip-modality".freeze
+        REQUESTED_MODEL_HEADER = "nip-requested-model".freeze
+
+        def initialize(client:)
+          @client = client
+        end
+
+      private
+
+        def add_request_headers(parameters, headers)
+          request_options = (parameters[:request_options] ||= {})
+          (request_options[:extra_headers] ||= {}).merge!(headers.compact)
+          parameters
+        end
+      end
+    end
+  end
+end

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

@@ -1,21 +1,19 @@
 require "openai"
+require "nitro_intelligence/client/handlers/base_handler"
 
 module NitroIntelligence
   module Client
     module Handlers
-      class ChatHandler
+      class ChatHandler < BaseHandler
         ALLOWED_EXTRA_PARAMETERS = OpenAI::Models::Chat::CompletionCreateParams.fields.keys.uniq.freeze
 
-        def initialize(client:)
-          @client = client
-        end
-
         def create(message: "", parameters: {})
           validate_and_resolve!(parameters, message)
           perform_request(parameters:)
         end
 
         def perform_request(parameters: {})
+          add_request_headers(parameters, REQUESTED_MODEL_HEADER => parameters[:model])
           @client.chat.completions.create(**parameters.slice(*ALLOWED_EXTRA_PARAMETERS))
         end
 
@@ -29,7 +27,6 @@ module NitroIntelligence
             metadata: {},
             messages: [],
             model: NitroIntelligence.model_catalog.default_text_model&.name,
-            extra_headers: { "Prefer" => "wait" },
           }
 
           parameters.replace(default_parameters.merge(parameters))

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

@@ -1,16 +1,13 @@
 require "openai"
+require "nitro_intelligence/client/handlers/base_handler"
 require "nitro_intelligence/media/image_generation"
 
 module NitroIntelligence
   module Client
     module Handlers
-      class ImageHandler
+      class ImageHandler < BaseHandler
         ALLOWED_EXTRA_PARAMETERS = OpenAI::Models::Chat::CompletionCreateParams.fields.keys.uniq.freeze
 
-        def initialize(client:)
-          @client = client
-        end
-
         def create(message: "", target_image: nil, reference_images: [], parameters: {})
           image_generation = build_image_generation(message:, target_image:, reference_images:, parameters:)
 
@@ -23,6 +20,7 @@ module NitroIntelligence
         end
 
         def perform_request(parameters: {})
+          add_request_headers(parameters, MODALITY_HEADER => "image", REQUESTED_MODEL_HEADER => parameters[:model])
           @client.chat.completions.create(**parameters.slice(*ALLOWED_EXTRA_PARAMETERS))
         end
 
@@ -32,7 +30,6 @@ module NitroIntelligence
             metadata: {},
             messages: image_generation.messages,
             model: image_generation.config.model,
-            extra_headers: { "Prefer" => "wait" },
             request_options: {
               extra_body: {
                 image_config: {

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

@@ -1,5 +1,6 @@
 require "base64"
 require "nitro_intelligence/media/audio"
+require "nitro_intelligence/observability/prompt_resolver"
 
 module NitroIntelligence
   module Client
@@ -34,26 +35,21 @@ module NitroIntelligence
         private
 
           def handle_prompt(message:, parameters:)
-            return nil if parameters[:prompt_name].blank?
-
-            prompt = @observer.project_client.project.prompt_store.get_prompt(
-              prompt_name: parameters[:prompt_name],
-              prompt_label: parameters[:prompt_label],
-              prompt_version: parameters[:prompt_version]
+            prompt = NitroIntelligence::Observability::PromptResolver.for(
+              store: @observer.project_client.project.prompt_store,
+              parameters:
             )
-            prompt_variables = parameters[:prompt_variables] || {}
-
-            if prompt.present?
-              # Prompts for audio transcriptions should only be text
-              if prompt.type != "text"
-                raise ObservedAudioTranscriptionPromptError,
-                      "Prompt type for audio transcription must be text: #{prompt.name}"
-              end
-              interpolated_prompt = prompt.compile(**prompt_variables)
+            return nil if prompt.blank?
 
-              message.prepend("#{interpolated_prompt} ").strip!
-              parameters.merge!(prompt.config) unless parameters[:prompt_config_disabled]
+            # Prompts for audio transcriptions should only be text
+            if prompt.type != "text"
+              raise ObservedAudioTranscriptionPromptError,
+                    "Prompt type for audio transcription must be text: #{prompt.name}"
             end
+            interpolated_prompt = prompt.compile(**(parameters[:prompt_variables] || {}))
+
+            message.prepend("#{interpolated_prompt} ").strip!
+            parameters.merge!(prompt.config) unless parameters[:prompt_config_disabled]
 
             prompt
           end

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

@@ -1,3 +1,5 @@
+require "nitro_intelligence/observability/prompt_resolver"
+
 module NitroIntelligence
   module Client
     module Handlers
@@ -28,23 +30,18 @@ module NitroIntelligence
         private
 
           def handle_prompt(parameters:)
-            return nil if parameters[:prompt_name].blank?
-
-            prompt = @observer.project_client.project.prompt_store.get_prompt(
-              prompt_name: parameters[:prompt_name],
-              prompt_label: parameters[:prompt_label],
-              prompt_version: parameters[:prompt_version]
+            prompt = NitroIntelligence::Observability::PromptResolver.for(
+              store: @observer.project_client.project.prompt_store,
+              parameters:
             )
-            prompt_variables = parameters[:prompt_variables] || {}
+            return nil if prompt.blank?
 
-            if prompt.present?
-              parameters[:messages] = prompt.interpolate(
-                messages: parameters[:messages],
-                variables: prompt_variables
-              )
+            parameters[:messages] = prompt.interpolate(
+              messages: parameters[:messages],
+              variables: parameters[:prompt_variables] || {}
+            )
 
-              parameters.merge!(prompt.config) unless parameters[:prompt_config_disabled]
-            end
+            parameters.merge!(prompt.config) unless parameters[:prompt_config_disabled]
 
             prompt
           end

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

@@ -1,4 +1,5 @@
 require "nitro_intelligence/media/image_generation"
+require "nitro_intelligence/observability/prompt_resolver"
 
 module NitroIntelligence
   module Client
@@ -58,23 +59,18 @@ module NitroIntelligence
           end
 
           def handle_prompt(parameters:)
-            return nil if parameters[:prompt_name].blank?
-
-            prompt = @observer.project_client.project.prompt_store.get_prompt(
-              prompt_name: parameters[:prompt_name],
-              prompt_label: parameters[:prompt_label],
-              prompt_version: parameters[:prompt_version]
+            prompt = NitroIntelligence::Observability::PromptResolver.for(
+              store: @observer.project_client.project.prompt_store,
+              parameters:
             )
-            prompt_variables = parameters[:prompt_variables] || {}
+            return nil if prompt.blank?
 
-            if prompt.present?
-              parameters[:messages] = prompt.interpolate(
-                messages: parameters[:messages],
-                variables: prompt_variables
-              )
+            parameters[:messages] = prompt.interpolate(
+              messages: parameters[:messages],
+              variables: parameters[:prompt_variables] || {}
+            )
 
-              parameters.merge!(prompt.config) unless parameters[:prompt_config_disabled]
-            end
+            parameters.merge!(prompt.config) unless parameters[:prompt_config_disabled]
 
             prompt
           end

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

@@ -1,4 +1,5 @@
 require "nitro_intelligence/media/audio"
+require "nitro_intelligence/observability/prompt_resolver"
 
 module NitroIntelligence
   module Client
@@ -33,26 +34,21 @@ module NitroIntelligence
         private
 
           def handle_prompt(parameters:)
-            return nil if parameters[:prompt_name].blank?
-
-            prompt = @observer.project_client.project.prompt_store.get_prompt(
-              prompt_name: parameters[:prompt_name],
-              prompt_label: parameters[:prompt_label],
-              prompt_version: parameters[:prompt_version]
+            prompt = NitroIntelligence::Observability::PromptResolver.for(
+              store: @observer.project_client.project.prompt_store,
+              parameters:
             )
-            prompt_variables = parameters[:prompt_variables] || {}
-
-            if prompt.present?
-              # Prompts for tts should only be text
-              if prompt.type != "text"
-                raise ObservedTextToSpeechPromptError,
-                      "Prompt type for text-to-speech must be text: #{prompt.name}"
-              end
-              interpolated_prompt = prompt.compile(**prompt_variables)
-
-              parameters.merge!(prompt.config) unless parameters[:prompt_config_disabled]
-              parameters[:instructions] = interpolated_prompt
+            return nil if prompt.blank?
+
+            # Prompts for tts should only be text
+            if prompt.type != "text"
+              raise ObservedTextToSpeechPromptError,
+                    "Prompt type for text-to-speech must be text: #{prompt.name}"
             end
+            interpolated_prompt = prompt.compile(**(parameters[:prompt_variables] || {}))
+
+            parameters.merge!(prompt.config) unless parameters[:prompt_config_disabled]
+            parameters[:instructions] = interpolated_prompt
 
             prompt
           end

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

@@ -1,21 +1,19 @@
 require "openai"
+require "nitro_intelligence/client/handlers/base_handler"
 
 module NitroIntelligence
   module Client
     module Handlers
-      class TextToSpeechHandler
+      class TextToSpeechHandler < BaseHandler
         ALLOWED_EXTRA_PARAMETERS = OpenAI::Models::Audio::SpeechCreateParams.fields.keys.uniq.freeze
 
-        def initialize(client:)
-          @client = client
-        end
-
         def create(message: "", parameters: {})
           validate_and_resolve!(parameters)
           perform_request(message:, parameters:)
         end
 
         def perform_request(message: "", parameters: {})
+          add_request_headers(parameters, MODALITY_HEADER => "audio", REQUESTED_MODEL_HEADER => parameters[:model])
           @client.audio.speech.create(
             input: message,
             **parameters.slice(*ALLOWED_EXTRA_PARAMETERS)
@@ -25,8 +23,6 @@ module NitroIntelligence
         def validate_and_resolve!(parameters)
           model_name = parameters[:model] || NitroIntelligence.model_catalog.default_text_to_speech_model&.name
           model = NitroIntelligence.model_catalog.lookup_by_name(model_name)
-
-          # Check model supported
           raise ArgumentError, "Unsupported model: '#{model_name}'" unless model
 
           default_parameters = {
@@ -35,17 +31,19 @@ module NitroIntelligence
             voice: model.default_voice,
             response_format: model.default_response_format,
           }
-
           parameters.replace(default_parameters.merge(parameters))
+          validate_voice_and_format!(model, parameters)
+        end
+
+      private
 
-          # Check voice supported
+        def validate_voice_and_format!(model, parameters)
           unless model.voices.include?(parameters[:voice])
             raise ArgumentError,
                   "Unsupported voice: '#{parameters[:voice]}'. " \
                   "Supported voices for #{model.name} are: #{model.voices}"
           end
 
-          # Check format supported
           return if model.response_formats.include?(parameters[:response_format])
 
           raise ArgumentError,

data/lib/nitro_intelligence/observability/prompt_resolver.rb

@@ -0,0 +1,69 @@
+require "nitro_intelligence/observability/prompt_store"
+
+module NitroIntelligence
+  module Observability
+    # Resolves a managed prompt from the lookups a request asks for, most specific first. A lookup that is
+    # missing -- or that fails -- yields to the next; the last one's failure propagates.
+    class PromptResolver
+      # One prompt lookup: the name asked for, at a label or a version.
+      Lookup = Data.define(:name, :label, :version)
+
+      def self.for(store:, parameters:)
+        new(store: store, lookups: lookups_for(parameters)).prompt
+      end
+
+      # The fallback names its own label and version and inherits neither: a version is minted per prompt,
+      # and a label the requested prompt carries need not exist on the fallback at all.
+      def self.lookups_for(parameters)
+        [
+          Lookup.new(
+            name: parameters[:prompt_name],
+            label: parameters[:prompt_label],
+            version: parameters[:prompt_version]
+          ),
+          Lookup.new(
+            name: parameters[:prompt_fallback_name],
+            label: parameters[:prompt_fallback_label],
+            version: parameters[:prompt_fallback_version]
+          ),
+        ]
+      end
+
+      def initialize(store:, lookups:)
+        @store = store
+        @lookups = lookups.select { |lookup| lookup.name.present? }.uniq
+      end
+
+      def prompt
+        *optional, final = @lookups
+        return nil if final.nil?
+
+        optional.each do |lookup|
+          resolved = fetch_optional(lookup)
+          return resolved if resolved
+        end
+
+        fetch(final)
+      end
+
+    private
+
+      def fetch(lookup)
+        @store.get_prompt(
+          prompt_name: lookup.name,
+          prompt_label: lookup.label,
+          prompt_version: lookup.version
+        )
+      end
+
+      def fetch_optional(lookup)
+        fetch(lookup)
+      rescue => e
+        NitroIntelligence.logger.info(
+          "#{self.class} #{e} - Falling back to the next prompt name after a failed lookup: #{lookup.name}"
+        )
+        nil
+      end
+    end
+  end
+end

data/lib/nitro_intelligence/version.rb

@@ -1,3 +1,3 @@
 module NitroIntelligence
-  VERSION = "2.0.0".freeze
+  VERSION = "2.2.0".freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nitro_intelligence
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.2.0
 platform: ruby
 authors:
 - Igor Artemenko
@@ -80,6 +80,7 @@ files:
 - lib/nitro_intelligence/client/client.rb
 - lib/nitro_intelligence/client/factory.rb
 - 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/image_handler.rb
 - lib/nitro_intelligence/client/handlers/observed/audio_transcription_handler.rb
@@ -104,6 +105,7 @@ files:
 - lib/nitro_intelligence/observability/project_client.rb
 - lib/nitro_intelligence/observability/project_client_registry.rb
 - lib/nitro_intelligence/observability/prompt.rb
+- lib/nitro_intelligence/observability/prompt_resolver.rb
 - lib/nitro_intelligence/observability/prompt_store.rb
 - lib/nitro_intelligence/observability/upload_handler.rb
 - lib/nitro_intelligence/reporter.rb