nitro_intelligence 3.0.0 → 3.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a6f2f9a233086c2c5b63e91124dd8ff9f6a838ba3eb1a7e08b382029efaf6c8a
-  data.tar.gz: d4b72f0693e8c10ad97d6ead9eebb469f69043d1323e49c097811530e17c5d90
+  metadata.gz: 7653522a1c44214cfec271be7416e5b2520df8411cc59fb729bbd4fe9c09a9ea
+  data.tar.gz: 626d6c64b382520afe8a01f6ab4d9e8d622fd4abd671ec53c0a355a2668c8ff2
 SHA512:
-  metadata.gz: caf47b70030388d5a3aaaa31e4fa9aa217b401e740fdd41a166539c12bfae0e9c4342e57543510a83af4c8c9788e7c50b752324273ee4a7302c903f754a5b14e
-  data.tar.gz: 426c37a3551965cee7946631d27b00b9e84e79620640cf1575a60d827a15f5e3b2ae1f40cde95e2df39efa15ec6c2a730ee3f66fbf1dcb4e4c0c148c037e5be2
+  metadata.gz: d2b91cce36b7524319ebc37b126424d0c63da854fc4da6bd8678d9519c8301d72166c6fe70c93e808809e3eba0c1b7926fa99ac5666bbf54981e7b49a0666fbd
+  data.tar.gz: cd1399a043ba90a041264693463d21fd1957e94dcf7da2c6adb9487a31ae8b9fce62af0ba0abfed2533118614c2133f15120e0bf12fc80a93f6d7f168b4ba4ee

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/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.1".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.1
 platform: ruby
 authors:
 - Igor Artemenko