Skip to content

The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:

Send finish-reason length for a Gemini MAX_TOKENS truncation (#80959)

applebye023152e9006
diff --git a/src/metabase/metabot/self/google/stream_generate_content.clj b/src/metabase/metabot/self/google/stream_generate_content.clj
index 4b68649fc0c..5d615dacea5 100644
--- a/src/metabase/metabot/self/google/stream_generate_content.clj
+++ b/src/metabase/metabot/self/google/stream_generate_content.clj
@@ -11,6 +11,7 @@
[metabase.metabot.self.schema :as schema]
[metabase.util :as u]
[metabase.util.json :as json]
+ [metabase.util.log :as log]
[metabase.util.malli :as mu]))
(set! *warn-on-reflection* true)
@@ -163,26 +164,61 @@
"The one `finishReason` that means the model said all it had to say."
"STOP")
-(def ^:private finish-reason-details
- "Explanations for the `finishReason` values whose names do not carry their meaning.
- https://docs.cloud.google.com/gemini-enterprise-agent-platform/reference/rest/v1/GenerateContentResponse#FinishReason"
- {"MAX_TOKENS" "the output token limit was reached"
- "MALFORMED_FUNCTION_CALL" "the model emitted a tool call it could not parse"
- "SAFETY" "the response was blocked by Google's safety filters"
- "RECITATION" "the response was blocked as recitation of copyrighted material"
- "BLOCKLIST" "the response was blocked by a term blocklist"
- "PROHIBITED_CONTENT" "the response was blocked as prohibited content"
- "SPII" "the response was blocked as sensitive personally identifiable information"
- "IMAGE_SAFETY" "the generated image was blocked by Google's safety filters"
- "UNEXPECTED_TOOL_CALL" "the model called a tool that the request did not declare"})
+(def ^:private finish-reason-truncated
+ "The `finishReason` for a turn the model cut off at its output-token limit."
+ "MAX_TOKENS")
+
+(def ^:private stop-reasons
+ "Gemini `finishReason` → AI SDK v5 `FinishReason`.
+ Covers both Gemini surfaces: every reason Vertex documents, plus four exclusive to the Gemini Developer API. We
+ only ever call Vertex today, so those four are here in case we ever add Gemini API support or in case these ever
+ wind up making their way into Vertex.
+ https://docs.cloud.google.com/gemini-enterprise-agent-platform/reference/rest/v1/GenerateContentResponse#FinishReason
+ https://ai.google.dev/api/generate-content#FinishReason"
+ {finish-reason-completed "stop"
+ finish-reason-truncated "length"
+ "BLOCKLIST" "content-filter"
+ "ESCALATION" "content-filter" ; Gemini API only
+ "IMAGE_PROHIBITED_CONTENT" "content-filter"
+ "IMAGE_RECITATION" "content-filter"
+ "IMAGE_SAFETY" "content-filter"
+ "LANGUAGE" "content-filter"
+ "MODEL_ARMOR" "content-filter"
+ "PROHIBITED_CONTENT" "content-filter"
+ "RECITATION" "content-filter"
+ "SAFETY" "content-filter"
+ "SPII" "content-filter"
+ "IMAGE_OTHER" "other"
+ "NO_IMAGE" "other"
+ "OTHER" "other"
+ "FINISH_REASON_UNSPECIFIED" "other"
+ "MALFORMED_FUNCTION_CALL" "error"
+ "MALFORMED_RESPONSE" "error" ; Gemini API only
+ "MISSING_THOUGHT_SIGNATURE" "error" ; Gemini API only
+ "TOO_MANY_TOOL_CALLS" "error" ; Gemini API only
+ "UNEXPECTED_TOOL_CALL" "error"})
+
+(def ^:private early-stops-without-error
+ "The `finishReason` values that end the turn early but emit no :error chunk.
+ The client already renders a message of its own for the AI SDK finish reason they translate to: \"length\" offers to
+ continue the truncated answer, and \"content-filter\" says the response was filtered and suggests rephrasing. Every
+ other early stop still needs an :error chunk, because nothing downstream would otherwise say what went wrong."
+ (into #{}
+ (keep (fn [[reason finish-reason]]
+ (when (#{"length" "content-filter"} finish-reason)
+ reason)))
+ stop-reasons))
+
+(def ^:private finish-reasons-without-error
+ "The `finishReason` values that emit no :error chunk: the early stops that speak for themselves, plus STOP, the one
+ reason that is not a failure at all."
+ (conj early-stops-without-error finish-reason-completed))
(defn- finish-reason-error
- "Returns the error text for a `finishReason` that ended the turn early, or nil for a complete answer."
+ "Returns the error text for a `finishReason` that needs one, or nil for the reasons that do not."
[reason]
- (when-not (= reason finish-reason-completed)
- (str "Gemini stopped early (" reason ")"
- (when-let [detail (finish-reason-details reason)]
- (str ": " detail)))))
+ (when-not (finish-reasons-without-error reason)
+ (str "Gemini stopped early (" reason ")")))
(defn reasoning-model?
"Whether `model-id` streams its reasoning back to us.
@@ -209,21 +245,25 @@
Unlike Claude, there are no content-block start and stop events. Text streams as consecutive parts, and one open
text block holds them all. Each functionCall part arrives with complete args, thus its start, delta, and available
chunks go out together. Parts with `:thought true` (thinking summaries) are ignored, as in the other adapters. A
- `finishReason` closes the open text block, and any reason but STOP also emits an :error chunk (see
- [[finish-reason-error]]). Usage is buffered, the last value wins, and it goes out once at the end of the stream,
- because an event in the middle can have partial usageMetadata."
+ `finishReason` closes the open text block and is added to the :usage chunk as :finish-reason and :raw-finish-reason;
+ the reasons that need one also emit an :error chunk (see [[finish-reason-error]]). Usage is buffered, the last value
+ wins, and it goes out once at the end of the stream, because an event in the middle can have partial usageMetadata."
[]
(fn [rf]
(let [message-id (volatile! nil)
model-name (volatile! nil)
text-id (volatile! nil) ; Non-nil while a text block is open.
usage-acc (volatile! nil)
+ stop-reason (volatile! nil)
close-text! (fn [result]
(if-let [id @text-id]
(do (vreset! text-id nil)
(rf result {:type :text-end :id id}))
result))
finish! (fn [result reason]
+ (vreset! stop-reason reason)
+ (when-not (= reason finish-reason-completed)
+ (log/info "Gemini stopped early" {:finishReason reason}))
(let [result (close-text! result)]
(if-let [error-text (finish-reason-error reason)]
(rf result {:type :error :errorText error-text})
@@ -267,13 +307,23 @@
result))]
(fn
([result]
- (-> result
- (close-text!)
- (cond-> @usage-acc (rf {:type :usage
- :usage @usage-acc
- :id @message-id
- :model @model-name}))
- (rf)))
+ ;; An early stop that emits no :error chunk still needs a :usage chunk when the stream carried no
+ ;; usageMetadata, so a truncated or filtered turn is never misinterpreted as a complete answer. The
+ ;; reasons that do emit an :error chunk already say what went wrong, so they get no synthetic usage.
+ (let [reason @stop-reason
+ usage (or @usage-acc
+ (when (early-stops-without-error reason)
+ (usage->aisdk-usage nil)))]
+ (-> result
+ (close-text!)
+ (cond-> usage
+ (rf (cond-> {:type :usage
+ :usage usage
+ :id @message-id
+ :model @model-name}
+ reason (assoc :finish-reason (core/stop-reason->finish-reason stop-reasons reason)
+ :raw-finish-reason reason))))
+ (rf))))
([result {:keys [candidates usageMetadata responseId modelVersion promptFeedback error] :as _event}]
(when (some? usageMetadata)
(vreset! usage-acc (usage->aisdk-usage usageMetadata)))
diff --git a/test/metabase/metabot/self/google/stream_generate_content_test.clj b/test/metabase/metabot/self/google/stream_generate_content_test.clj
index dd51d80609a..62c5e59edb0 100644
--- a/test/metabase/metabot/self/google/stream_generate_content_test.clj
+++ b/test/metabase/metabot/self/google/stream_generate_content_test.clj
@@ -531,21 +531,119 @@
(into [] (comp (sgc/->aisdk-chunks-xf) (self.core/aisdk-xf)) events))))))
(deftest ^:parallel max-tokens-finish-reason-test
- (testing "a MAX_TOKENS truncation emits an error part after the partial text, instead of reading as a complete answer"
+ (testing "a MAX_TOKENS truncation becomes :finish-reason \"length\" on the usage chunk not an error part"
(let [events [{:responseId "r11" :modelVersion "gemini-3.5-flash"
:candidates [{:content {:role "model" :parts [{:text "half an ans"}]}
:finishReason "MAX_TOKENS"}]
:usageMetadata {:promptTokenCount 4 :thoughtsTokenCount 2000}}]]
(is (=? [{:type :start}
{:type :text :text "half an ans"}
- {:type :error
- :error {:message #"(?s)Gemini stopped early \(MAX_TOKENS\): the output token limit was reached.*"}}
- {:type :usage}]
+ {:type :usage
+ :finish-reason "length"
+ :raw-finish-reason "MAX_TOKENS"}]
+ (into [] (comp (sgc/->aisdk-chunks-xf) (self.core/aisdk-xf)) events))))))
+
+(deftest ^:parallel max-tokens-truncation-never-reads-as-complete-test
+ (testing "a MAX_TOKENS turn that carries no usageMetadata still reports the truncation"
+ (let [events [{:responseId "r11b"
+ :candidates [{:content {:role "model" :parts [{:text "half an ans"}]}
+ :finishReason "MAX_TOKENS"}]}]]
+ (is (=? [{:type :start}
+ {:type :text-start}
+ {:type :text-delta}
+ {:type :text-end}
+ {:type :usage
+ :finish-reason "length"
+ :raw-finish-reason "MAX_TOKENS"}]
+ (into [] (sgc/->aisdk-chunks-xf) events))))))
+
+(deftest ^:parallel finish-reason-translation-test
+ (let [usage-chunk (fn [reason]
+ (->> (into [] (sgc/->aisdk-chunks-xf)
+ [{:responseId "r11c"
+ :candidates [{:content {:role "model" :parts [{:text "hi"}]}
+ :finishReason reason}]
+ :usageMetadata {:promptTokenCount 4}}])
+ (m/find-first #(= :usage (:type %)))))]
+ (testing "the AI SDK finish reason rides the usage chunk alongside the raw provider value"
+ (are [raw finish-reason] (=? {:finish-reason finish-reason :raw-finish-reason raw}
+ (usage-chunk raw))
+ "STOP" "stop"
+ "MAX_TOKENS" "length"
+ "SAFETY" "content-filter"
+ "RECITATION" "content-filter"
+ "BLOCKLIST" "content-filter"
+ "PROHIBITED_CONTENT" "content-filter"
+ "SPII" "content-filter"
+ "IMAGE_SAFETY" "content-filter"
+ "IMAGE_PROHIBITED_CONTENT" "content-filter"
+ "IMAGE_RECITATION" "content-filter"
+ "MODEL_ARMOR" "content-filter"
+ "LANGUAGE" "content-filter"
+ "ESCALATION" "content-filter"
+ "MALFORMED_FUNCTION_CALL" "error"
+ "UNEXPECTED_TOOL_CALL" "error"
+ "TOO_MANY_TOOL_CALLS" "error"
+ "MISSING_THOUGHT_SIGNATURE" "error"
+ "MALFORMED_RESPONSE" "error"
+ "OTHER" "other"
+ "FINISH_REASON_UNSPECIFIED" "other"
+ "IMAGE_OTHER" "other"
+ "NO_IMAGE" "other"
+ "SOMETHING_NEW" "other"))))
+
+(deftest ^:parallel content-filter-finish-reason-emits-no-error-test
+ (testing "a filtered response reports itself as :finish-reason \"content-filter\", which the client renders itself"
+ (let [events [{:responseId "r11d"
+ :candidates [{:content {:role "model" :parts [{:text "partial"}]}
+ :finishReason "SAFETY"}]
+ :usageMetadata {:promptTokenCount 4}}]]
+ (is (=? [{:type :start}
+ {:type :text :text "partial"}
+ {:type :usage
+ :finish-reason "content-filter"
+ :raw-finish-reason "SAFETY"}]
(into [] (comp (sgc/->aisdk-chunks-xf) (self.core/aisdk-xf)) events))))))
+(deftest ^:parallel content-filter-truncation-never-reads-as-complete-test
+ (testing "a filtered turn that carries no usageMetadata still reports the filtering"
+ (let [events [{:responseId "r11e"
+ :candidates [{:content {:role "model" :parts [{:text "partial"}]}
+ :finishReason "SAFETY"}]}]]
+ (is (=? [{:type :start}
+ {:type :text :text "partial"}
+ {:type :usage
+ :finish-reason "content-filter"
+ :raw-finish-reason "SAFETY"}]
+ (into [] (comp (sgc/->aisdk-chunks-xf) (self.core/aisdk-xf)) events))))))
+
+(deftest ^:parallel stop-reasons-translate-to-aisdk-finish-reasons-test
+ (testing "every translation is one of the AI SDK v5 FinishReason values the client knows how to render"
+ (is (every? self.core/finish-reasons (vals @#'sgc/stop-reasons)))))
+
+(deftest ^:parallel finish-reasons-without-error-are-the-ones-the-client-renders-test
+ (testing "STOP plus every reason translating to \"length\" or \"content-filter\" emits no error part"
+ (is (= #{"STOP" "MAX_TOKENS"
+ "BLOCKLIST" "ESCALATION" "IMAGE_PROHIBITED_CONTENT" "IMAGE_RECITATION" "IMAGE_SAFETY" "LANGUAGE"
+ "MODEL_ARMOR" "PROHIBITED_CONTENT" "RECITATION" "SAFETY" "SPII"}
+ @#'sgc/finish-reasons-without-error))))
+
(deftest ^:parallel malformed-function-call-finish-reason-test
(testing "MALFORMED_FUNCTION_CALL arrives with no parts at all, so the error part is the only diagnostic"
- (let [events [{:responseId "r12"
+ (let [events [{:responseId "r12"
+ :candidates [{:finishReason "MALFORMED_FUNCTION_CALL"}]
+ :usageMetadata {:promptTokenCount 4}}]]
+ (is (=? [{:type :start}
+ {:type :error
+ :error {:message #"(?s)Gemini stopped early \(MALFORMED_FUNCTION_CALL\).*"}}
+ {:type :usage
+ :finish-reason "error"
+ :raw-finish-reason "MALFORMED_FUNCTION_CALL"}]
+ (into [] (comp (sgc/->aisdk-chunks-xf) (self.core/aisdk-xf)) events))))))
+
+(deftest ^:parallel finish-reason-with-error-gets-no-synthetic-usage-test
+ (testing "a reason that emits an :error chunk already says what went wrong, so no zero-token :usage is invented"
+ (let [events [{:responseId "r12b"
:candidates [{:finishReason "MALFORMED_FUNCTION_CALL"}]}]]
(is (=? [{:type :start}
{:type :error
@@ -554,12 +652,16 @@
(deftest ^:parallel unknown-finish-reason-test
(testing "a finish reason we have no message for still reports itself rather than passing silently"
- (let [events [{:responseId "r13"
- :candidates [{:content {:role "model" :parts [{:text "hi"}]}
- :finishReason "SOMETHING_NEW"}]}]]
+ (let [events [{:responseId "r13"
+ :candidates [{:content {:role "model" :parts [{:text "hi"}]}
+ :finishReason "SOMETHING_NEW"}]
+ :usageMetadata {:promptTokenCount 4}}]]
(is (=? [{:type :start}
{:type :text :text "hi"}
- {:type :error :error {:message "Gemini stopped early (SOMETHING_NEW)"}}]
+ {:type :error :error {:message "Gemini stopped early (SOMETHING_NEW)"}}
+ {:type :usage
+ :finish-reason "other"
+ :raw-finish-reason "SOMETHING_NEW"}]
(into [] (comp (sgc/->aisdk-chunks-xf) (self.core/aisdk-xf)) events))))))
(deftest ^:parallel stop-finish-reason-emits-no-error-test