nitro_intelligence 2.1.0 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7d1c0e6c9ddffc032a989ebffb001d58aefabf86e50f92966a6d384a5218628f
-  data.tar.gz: 60b9ae5ef4fd8c7a79bc45f13a1b965c9d9a0792f38bc285e361822b7d91a8ad
+  metadata.gz: 1181b17cc855ffa2f039b1401fd5dd2040c262d2878e6d265e65f9a581f6106e
+  data.tar.gz: 28b3a022b8d6d7e8e8472930fcf089fa5a3ead8a6c0d917e7587a73b69b8fba5
 SHA512:
-  metadata.gz: a13a9b1a0a58f58c142ab87ec89f491f409341717b3101b9bb1579c88b8ed9335413ea73d621c489749b7d151d62672e9277e3d39da80c4721008cad28a301b0
-  data.tar.gz: 1c498a0a4ec99af32f039dd43272ad61650da433c4f4d3b4297aadd473fba4c93af8d9ed08db0d2faf5012ed3a721e6d47587bf5429eb16368161d224f773cf7
+  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/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/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.1.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.1.0
+  version: 2.2.0
 platform: ruby
 authors:
 - Igor Artemenko
@@ -105,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