nitro_intelligence 3.0.0 → 3.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a6f2f9a233086c2c5b63e91124dd8ff9f6a838ba3eb1a7e08b382029efaf6c8a
-  data.tar.gz: d4b72f0693e8c10ad97d6ead9eebb469f69043d1323e49c097811530e17c5d90
+  metadata.gz: feb0fe8d0b4ae0d1da8564f048fa7130dc78318622a23a86163edc65d2f37dbf
+  data.tar.gz: 122277bfc6b70b0aeb67166624458f37f50b1ed2b1a77044ade87575ea101bb1
 SHA512:
-  metadata.gz: caf47b70030388d5a3aaaa31e4fa9aa217b401e740fdd41a166539c12bfae0e9c4342e57543510a83af4c8c9788e7c50b752324273ee4a7302c903f754a5b14e
-  data.tar.gz: 426c37a3551965cee7946631d27b00b9e84e79620640cf1575a60d827a15f5e3b2ae1f40cde95e2df39efa15ec6c2a730ee3f66fbf1dcb4e4c0c148c037e5be2
+  metadata.gz: bf69e4777017afa0be7457612c42aadf434921c083b3a199e13a0682959b6579494793069e2548c592dd022ac5a96d342155549cfa5d36fdf798bd0a05bd647f
+  data.tar.gz: 18854e89e04d994bddc0315296d5f21ad2551dd9b7d64d01efda6aadc25dbcd0858d1e8f24dacb2f2b261b2b65ab1bb3fe747956f5064ce6ef176b017e59b712

data/docs/README.md

@@ -424,7 +424,62 @@ trace_id = NitroIntelligence::Trace.create_id(seed: document_id)
 reporter.score(name: "precision", value: 0.5, trace_id:)
 ```
 
-### Prompt Variables and Config
+### Prompts
+
+#### Message Shape
+
+A chat completion needs a user message in order for the model to answer. What you have to supply depends on the type of the prompt you name, and the two types behave differently.
+
+##### Text prompts
+
+A text prompt in Cerebro is equivalent to the system prompt. System prompts are used to pre-load initial context into the model needed for following call executions.
+
+Pure text prompts require a user message to be supplied. For example:
+
+```ruby
+#  Wrong - Raises ObservedChatPromptError - A prompt alone, provides a system message alone with nothing to answer
+client.chat(parameters: { prompt_name: "Assistant" })
+
+# Correct - The prompt supplies the system message, you supply the user message
+client.chat(message: "Why is the sky blue?", parameters: { prompt_name: "Assistant" })
+```
+
+##### Chat prompts
+
+A chat prompt in Cerebro holds a list of role-tagged messages rather than a single string, so it can carry its own user turn. Define one when the prompt structure should represent a conversation flow vs. a single block of static text, e.g. pre-modeling an interaction you want to continue:
+
+```yaml
+[
+  {
+    "role": "system",
+    "content": "You are a helpful support agent for an online bookstore. Be concise and friendly. Our return window is 30 days."
+  },
+  {
+    "role": "user",
+    "content": "Hi, do you ship to Canada?"
+  },
+  {
+    "role": "assistant",
+    "content": "Yes! We ship to Canada. Delivery usually takes 5–8 business days."
+  },
+  {
+    "role": "user",
+    "content": "{{question}}"
+  }
+]
+```
+
+That prompt is self-sufficient, so no additional `message:` is needed:
+
+```ruby
+client.chat(parameters: { prompt_name: "Appointment Extractor", prompt_variables: { document: text } })
+```
+
+Any messages you do pass are appended after the prompt's own system message, so a chat prompt can also serve as a preamble to a live conversation.
+
+A chat prompt containing only a system message has the same problem as a text prompt, and is refused in the same way. If you find yourself writing one, either add a user message to it in Cerebro or make it a text prompt and pass the turn from the caller via the `message` keyword.
+
+#### Prompt Variables and Config
 
 Prompts are often created with "variables". These variables can be supplied and compiled into the prompt. For example:
 

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

@@ -74,16 +74,25 @@ module NitroIntelligence
             # (OpenAI::Models::Audio::Transcription), so neither is set again here.
             trace_attributes = {
               output: audio_transcription.text,
-              usage_details: {
-                input_tokens: audio_transcription.usage.input_tokens,
-                output_tokens: audio_transcription.usage.output_tokens,
-                total_tokens: audio_transcription.usage.total_tokens,
-              },
+              usage_details: usage_details(audio_transcription.usage),
               cost_details: @base_handler.cost_details(audio_transcription),
             }
 
             [audio_transcription, trace_attributes]
           end
+
+          def usage_details(usage)
+            case usage
+            when OpenAI::Models::Audio::Transcription::Usage::Tokens
+              {
+                input_tokens: usage.input_tokens,
+                output_tokens: usage.output_tokens,
+                total_tokens: usage.total_tokens,
+              }
+            when OpenAI::Models::Audio::Transcription::Usage::Duration
+              { input_audio_seconds: usage.seconds.ceil }
+            end
+          end
         end
       end
     end

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

@@ -5,6 +5,8 @@ module NitroIntelligence
     module Handlers
       module Observed
         class ChatHandler
+          class ObservedChatPromptError < StandardError; end
+
           def initialize(base_handler:, observer:)
             @base_handler = base_handler
             @observer = observer
@@ -14,6 +16,8 @@ module NitroIntelligence
             @base_handler.validate_and_resolve!(parameters, message)
 
             prompt = handle_prompt(parameters:)
+            validate_message_shape!(parameters:, prompt:)
+
             trace_name = parameters[:trace_name] || prompt&.name || @observer.project_client.project.slug
 
             @observer.observe(
@@ -30,6 +34,46 @@ module NitroIntelligence
 
         private
 
+          # A chat completion needs a turn for the model to answer, and it is the model's own
+          # chat template that insists on one: Qwen's raises "No user query found in
+          # messages." Left to the gateway that costs a round trip and comes back as a 400
+          # whose body the caller cannot read, so it is caught here instead, while the prompt
+          # is still in hand and the advice can name what to do about it.
+          #
+          # Presence of the turn is what is checked, not its usefulness. A template may well
+          # accept an empty user message -- Qwen's does -- but a caller who sent one almost
+          # never meant to, so blank content is refused rather than forwarded. Content
+          # arriving as an array of parts is taken at face value, since a message carrying
+          # only an image is a legitimate turn.
+          def validate_message_shape!(parameters:, prompt:)
+            return if parameters[:messages].any? { |message| user_turn?(message) }
+
+            raise ObservedChatPromptError, missing_user_message_error(prompt)
+          end
+
+          def user_turn?(message)
+            role = message[:role] || message["role"]
+            return false unless role.to_s == "user"
+
+            (message[:content] || message["content"]).present?
+          end
+
+          def missing_user_message_error(prompt)
+            case prompt&.type
+            when "text"
+              "The prompt #{prompt.name.inspect} is a text prompt, so it contributes only a system message and " \
+              "this request carries no turn for the model to answer. Pass a `message:`, or define " \
+              "#{prompt.name.inspect} as a chat prompt in Cerebro so that it carries its own user message."
+            when "chat"
+              "The chat prompt #{prompt.name.inspect} contains no user message and none was supplied, so this " \
+              "request carries no turn for the model to answer. Add a user message to #{prompt.name.inspect} " \
+              "in Cerebro, or pass a `message:`."
+            else
+              "This request carries no user message, so there is no turn for the model to answer. Pass a " \
+              "`message:`, or supply `parameters[:messages]` including a message with the `user` role."
+            end
+          end
+
           def handle_prompt(parameters:)
             prompt = NitroIntelligence::Observability::PromptResolver.for(
               store: @observer.project_client.project.prompt_store,

data/lib/nitro_intelligence/version.rb

@@ -1,3 +1,3 @@
 module NitroIntelligence
-  VERSION = "3.0.0".freeze
+  VERSION = "3.0.2".freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nitro_intelligence
 version: !ruby/object:Gem::Version
-  version: 3.0.0
+  version: 3.0.2
 platform: ruby
 authors:
 - Igor Artemenko