diff --git a/core/src/main/java/com/google/adk/models/Gemini.java b/core/src/main/java/com/google/adk/models/Gemini.java index 904830d69..c0a9f4f44 100644 --- a/core/src/main/java/com/google/adk/models/Gemini.java +++ b/core/src/main/java/com/google/adk/models/Gemini.java @@ -20,37 +20,26 @@ import com.google.adk.utils.ModelNameUtils; import com.google.common.annotations.VisibleForTesting; import com.google.common.base.Strings; -import com.google.common.collect.ImmutableList; import com.google.common.collect.ImmutableMap; import com.google.common.collect.ImmutableSet; -import com.google.common.primitives.Ints; import com.google.errorprone.annotations.CanIgnoreReturnValue; import com.google.genai.Client; import com.google.genai.ResponseStream; -import com.google.genai.types.Candidate; import com.google.genai.types.ClientOptions; import com.google.genai.types.Content; -import com.google.genai.types.FinishReason; -import com.google.genai.types.FunctionCall; import com.google.genai.types.GenerateContentConfig; import com.google.genai.types.GenerateContentResponse; import com.google.genai.types.HttpOptions; import com.google.genai.types.LiveConnectConfig; -import com.google.genai.types.Part; -import com.google.genai.types.PartialArg; import io.reactivex.rxjava3.core.Flowable; import io.reactivex.rxjava3.schedulers.Schedulers; import java.time.Duration; -import java.util.ArrayList; import java.util.Iterator; -import java.util.LinkedHashMap; import java.util.List; -import java.util.Map; import java.util.Objects; import java.util.concurrent.CompletableFuture; import java.util.concurrent.ExecutorService; import java.util.concurrent.atomic.AtomicBoolean; -import java.util.regex.Matcher; import java.util.regex.Pattern; import okhttp3.OkHttpClient; import org.jspecify.annotations.Nullable; @@ -329,8 +318,7 @@ private Flowable sendRequest( apiClient.async.models.generateContentStream( effectiveModelName, llmRequest.contents(), config); - return Flowable.defer( - () -> new StreamingResponseAggregator().process(readStream(streamFuture), cacheMetadata)); + return aggregateStream(readStream(streamFuture), cacheMetadata); } else { logger.debug("Sending generateContent request to model {}", effectiveModelName); return Flowable.fromFuture( @@ -441,8 +429,16 @@ private static LlmResponse withCacheMetadata( @VisibleForTesting static Flowable processRawResponses(Flowable rawResponses) { - return Flowable.defer( - () -> new StreamingResponseAggregator().process(rawResponses, /* cacheMetadata= */ null)); + return aggregateStream(rawResponses, /* cacheMetadata= */ null); + } + + /** + * Turns a stream of raw responses into partial and aggregated {@link LlmResponse}s, and puts + * {@code cacheMetadata}, if any, on the aggregated response. + */ + private static Flowable aggregateStream( + Flowable rawResponses, @Nullable CacheMetadata cacheMetadata) { + return Flowable.defer(() -> new StreamState().process(rawResponses, cacheMetadata)); } /** @@ -493,502 +489,46 @@ protected CompletableFuture connectLiveTransport( return apiClient.async.live.connect(modelName, config).thenApply(GenAiLiveTransport::new); } - private static final class StreamingResponseAggregator { - /** The largest list index a streamed argument path may set, as in ADK Python. */ - private static final int MAX_ARRAY_INDEX = 10_000; - - /** - * A JSONPath segment, as in ADK Python: a list index such as {@code [0]}, a quoted key such as - * {@code ['a.b']} or {@code ["a.b"]}, or a key with an optional dot. Keys may hold escapes. The - * key loops are possessive: a greedy one recurses per character and overflows the stack. - */ - private static final Pattern JSON_PATH_SEGMENT = - Pattern.compile( - "\\[\\s*(\\d+)\\s*]" - + "|\\['((?:[^'\\\\]|\\\\.)*+)'\\]" - + "|\\[\"((?:[^\"\\\\]|\\\\.)*+)\"\\]" - + "|\\.?((?:[^.\\[\\]\\\\]|\\\\.)++)", - // Only \n ends a line, so "." matches what Python's "." does. - Pattern.UNIX_LINES); - - /** A backslash escape in a JSONPath key: {@code \\uXXXX} or one escaped character. */ - private static final Pattern JSON_PATH_ESCAPE = - Pattern.compile("\\\\u([0-9a-fA-F]{4})|\\\\(.)", Pattern.UNIX_LINES); - - /** A whole number whose magnitude is at most 2^53 - 1 has an exact double; others may not. */ - private static final double MAX_EXACT_DOUBLE_INTEGER = 9007199254740991d; - - private final List accumulatedSequence = new ArrayList<>(); - private final StringBuilder currentTextBuffer = new StringBuilder(); - // Always reassigned in accumulateParts() before it is read; the initializer is never observed. - private boolean currentTextIsThought = false; - - /** - * Returns whether the part is the empty-text terminator Gemini 3 ends a stream with: empty text - * and nothing else worth keeping. Compared by rebuilding rather than against a single literal, - * so a terminator that also carries an explicit {@code thought=false} is still recognised. - */ - private static boolean isStreamTerminator(Part part) { - if (!part.text().map(String::isEmpty).orElse(false)) { - return false; - } - Part.Builder terminator = Part.builder().text(""); - part.thought().ifPresent(terminator::thought); - return terminator.build().equals(part); - } - - // Signature of the buffered text run, kept apart from the call's slot below so an interleaved - // chunk cannot flush one part carrying the other's signature. - private byte[] currentTextThoughtSignature = null; - private byte[] currentThoughtSignature = null; - private GenerateContentResponse lastRawResponse = null; + /** Feeds one stream's raw responses to a {@link StreamingResponseAggregator}. */ + private static final class StreamState { + private final StreamingResponseAggregator aggregator = new StreamingResponseAggregator(); + // Kept from the error chunk, so a later chunk without candidates cannot drop it. + private @Nullable String finishMessage = null; - // Streaming function-call accumulation state. When the model streams a function call across - // multiple chunks (via partialArgs/willContinue), its arguments are accumulated here and a - // single complete function-call part is flushed to accumulatedSequence once it completes. - private String currentFcName = null; - private Map currentFcArgs = new LinkedHashMap<>(); - private String currentFcId = null; - - /** - * Processes a stream of raw responses, emitting partial and aggregated {@link LlmResponse}s, - * and puts {@code cacheMetadata}, if any, on the aggregated response. - */ private Flowable process( Flowable rawResponses, @Nullable CacheMetadata cacheMetadata) { return rawResponses .concatMap(this::processRawResponse) .concatWith( - Flowable.defer( - () -> - processFinalResponse() - .map(response -> withCacheMetadata(response, cacheMetadata)))); + Flowable.defer(() -> + Flowable.fromOptional(aggregator.aggregate()) + .map(this::withFinishMessage) + .map(response -> withCacheMetadata(response, cacheMetadata)))); } - /** - * Processes a single raw streaming chunk, accumulating parts and emitting intermediate - * responses. - */ private Flowable processRawResponse(GenerateContentResponse rawResponse) { - lastRawResponse = rawResponse; + rawResponse + .candidates() + .flatMap(candidates -> candidates.stream().findFirst()) + .filter(candidate -> candidate.finishReason().isPresent()) + .ifPresent(candidate -> finishMessage = candidate.finishMessage().orElse(null)); - LlmResponse currentProcessedLlmResponse = LlmResponse.create(rawResponse); - List parts = - currentProcessedLlmResponse.content().flatMap(Content::parts).orElse(ImmutableList.of()); + LlmResponse response = LlmResponse.create(rawResponse); // Model output and tool arguments must not be logged, so only the chunk's shape is. logger.trace( "Streaming chunk: {} parts, finish reason {}", - parts.size(), - currentProcessedLlmResponse.finishReason().map(Object::toString).orElse("none")); - - // Assign an ID to every function-call part up front, mirroring ADK Python's - // StreamingResponseAggregator: the same ID is reused in the partial and final responses so - // consumers can correlate them. - List partsWithIds = ensureFunctionCallIds(parts); - - if (accumulateParts(partsWithIds)) { - // partsWithIds is non-empty here, so the chunk's content (and its role) is present. Rebuild - // the partial content from the parts-with-IDs so its FC ID matches the final event. - Content.Builder rebuilt = Content.builder().parts(partsWithIds); - currentProcessedLlmResponse.content().flatMap(Content::role).ifPresent(rebuilt::role); - return Flowable.just( - currentProcessedLlmResponse.toBuilder().content(rebuilt.build()).partial(true).build()); - } - - // If the chunk has no text or function calls (e.g. metadata-only or empty), we suppress it - // during streaming so it doesn't emit an empty partial response. - // Exception: If this is a standalone empty chunk in an otherwise completely empty stream - // (and not a STOP chunk), we emit it directly as a non-partial empty response, unless more - // of the stream follows it. - if (!isStop(currentProcessedLlmResponse) - && !continuesStream(rawResponse) - && accumulatedSequence.isEmpty() - && currentTextBuffer.isEmpty()) { - return Flowable.just(currentProcessedLlmResponse.toBuilder().partial(null).build()); - } - - return Flowable.empty(); - } - - /** - * Returns a list of parts where every function-call part has a non-empty ID. If a part's - * function call already has an ID, the original part is preserved; otherwise a new part with a - * client-generated ID is substituted. Non-FC parts are passed through unchanged. - */ - private static List ensureFunctionCallIds(List parts) { - List result = new ArrayList<>(parts.size()); - for (Part part : parts) { - if (part.functionCall().isPresent()) { - FunctionCall fc = part.functionCall().get(); - if (fc.id().map(String::isEmpty).orElse(true)) { - FunctionCall withId = fc.toBuilder().id(generateClientFunctionCallId()).build(); - result.add(part.toBuilder().functionCall(withId).build()); - continue; - } - } - result.add(part); - } - return result; - } - - /** Generates a unique client-side function-call ID. */ - private static String generateClientFunctionCallId() { - return FunctionCallIds.generateClientFunctionCallId(); - } - - /** - * Accumulates content from incoming parts: text, function calls, and any other content part - * (inline image/audio data, file data, code execution, server-side tool calls/responses, - * standalone thought signatures, and future part types), which are appended verbatim as ADK - * Python does. The empty-text part that ends a Gemini 3 stream is the one thing dropped. - * Function-call parts passed to this method are expected to already have IDs (see {@link - * #ensureFunctionCallIds}). - * - * @return true if any content part was present, false otherwise. - */ - private boolean accumulateParts(List parts) { - boolean hasContent = false; - for (Part part : parts) { - String text = part.text().orElse(""); - if (!text.isEmpty()) { - hasContent = true; - boolean isThought = part.thought().orElse(false); - // Flush before capturing this chunk's signature below, or the signature of the run - // starting here lands on the run being flushed. - if (!currentTextBuffer.isEmpty() && isThought != currentTextIsThought) { - flushTextBufferToSequence(); - } - if (currentTextBuffer.isEmpty()) { - currentTextIsThought = isThought; - } - // Keep the first signature of the run, as ADK Python does; the merged part takes it in - // flushTextBufferToSequence. - if (currentTextThoughtSignature == null - && part.thoughtSignature().map(sig -> sig.length > 0).orElse(false)) { - currentTextThoughtSignature = part.thoughtSignature().get(); - } - currentTextBuffer.append(text); - } else if (part.functionCall().isPresent()) { - hasContent = true; - processFunctionCallPart(part); - } else if (isStreamTerminator(part)) { - // Gemini 3 ends a stream with a bare empty text part; it carries nothing to keep. - } else { - // Everything else is appended as the model sent it, signature included. Relocating a - // signature onto a neighbouring part would hand it back on a part the model never signed. - hasContent = true; - flushTextBufferToSequence(); - accumulatedSequence.add(part); - } - } - return hasContent; + response.content().flatMap(Content::parts).map(List::size).orElse(0), + response.finishReason().map(Object::toString).orElse("none")); + // A chunk without content emits nothing; aggregate() keeps its usage and finish reason. + return Flowable.fromOptional(aggregator.processResponse(response)); } - /** - * Processes a function-call part, mirroring ADK Python's {@code _process_function_call_part}. A - * function call whose arguments are streamed across chunks (it carries {@code partialArgs} or - * {@code willContinue=true}) is accumulated and flushed as a single complete part once it - * finishes; a complete (non-streaming) function call is appended directly. - */ - private void processFunctionCallPart(Part part) { - FunctionCall fc = part.functionCall().get(); - boolean hasName = fc.name().filter(name -> !name.isEmpty()).isPresent(); - // A streamed call: it has partialArgs or willContinue, or is the nameless terminal - // marker of an in-progress call. Gemini may end a call with a separate empty - // willContinue=false part, so that marker completes it. - boolean streamedPart = - fc.partialArgs().map(args -> !args.isEmpty()).orElse(false) - || fc.willContinue().orElse(false) - || (currentFcName != null && !hasName); - if (streamedPart) { - // Capture the thought signature from the first chunk that carries one. - if (currentThoughtSignature == null - && part.thoughtSignature().map(sig -> sig.length > 0).orElse(false)) { - currentThoughtSignature = part.thoughtSignature().get(); - } - processStreamingFunctionCall(fc); - } else if (hasName) { - // Complete (non-streamed) call. Safety guard: the model should terminate a streamed call - // with willContinue=false before starting a new one; flush any still-in-progress call so it - // is neither dropped nor merged. The part already has an ID assigned by - // ensureFunctionCallIds. - flushTextBufferToSequence(); - flushFunctionCallToSequence(); - accumulatedSequence.add(part); - } - } - - /** - * Accumulates one chunk of a streamed function call, mirroring ADK Python's {@code - * _process_streaming_function_call}: merges the function name/ID and each {@code partialArg} - * (by JSONPath) into {@link #currentFcArgs}, then flushes the completed call once {@code - * willContinue} is no longer set. - */ - private void processStreamingFunctionCall(FunctionCall fc) { - fc.name().filter(name -> !name.isEmpty()).ifPresent(name -> currentFcName = name); - // Use the first ID seen (the model's, if provided, otherwise a generated one) for the whole - // call so the partial and final events correlate. - if (currentFcId == null) { - currentFcId = - fc.id().filter(id -> !id.isEmpty()).orElseGet(() -> generateClientFunctionCallId()); - } - for (PartialArg partialArg : fc.partialArgs().orElse(ImmutableList.of())) { - String jsonPath = partialArg.jsonPath().orElse(""); - if (jsonPath.isEmpty()) { - continue; - } - applyPartialArg(partialArg, jsonPath); - } - if (!fc.willContinue().orElse(false)) { - flushTextBufferToSequence(); - flushFunctionCallToSequence(); - } - } - - /** - * Applies a single {@link PartialArg} to {@link #currentFcArgs} at {@code jsonPath}, mirroring - * ADK Python's {@code _get_value_from_partial_arg}: string chunks are appended to any existing - * string at the path, while number/bool/null values overwrite. - */ - private void applyPartialArg(PartialArg partialArg, String jsonPath) { - if (partialArg.stringValue().isPresent()) { - Object existing = getValueByJsonPath(jsonPath); - String chunk = partialArg.stringValue().get(); - setValueByJsonPath(jsonPath, existing instanceof String s ? s + chunk : chunk); - } else if (partialArg.numberValue().isPresent()) { - setValueByJsonPath(jsonPath, wholeNumberAsInteger(partialArg.numberValue().get())); - } else if (partialArg.boolValue().isPresent()) { - setValueByJsonPath(jsonPath, partialArg.boolValue().get()); - } else if (partialArg.nullValue().isPresent()) { - setValueByJsonPath(jsonPath, null); + /** Puts the finish message on an aggregated response whose finish reason is an error. */ + private LlmResponse withFinishMessage(LlmResponse response) { + if (finishMessage == null || response.errorCode().isEmpty()) { + return response; } - } - - /** - * Returns a whole number whose magnitude is at most 2^53 - 1 as the Integer or Long a - * non-streamed call carries, because schema validation rejects a Double for an INTEGER field. - * Any other value stays a Double. - */ - private static Number wholeNumberAsInteger(double value) { - if (value != Math.rint(value) || Math.abs(value) > MAX_EXACT_DOUBLE_INTEGER) { - return value; - } - long whole = (long) value; - if (whole == (int) whole) { - return (int) whole; - } - return whole; - } - - /** - * Returns the value currently stored at {@code jsonPath} in {@link #currentFcArgs}, or null. - */ - private @Nullable Object getValueByJsonPath(String jsonPath) { - Object current = currentFcArgs; - for (Object segment : parseJsonPath(jsonPath)) { - if (segment instanceof String key - && current instanceof Map map - && map.containsKey(key)) { - current = map.get(key); - } else if (segment instanceof Integer index - && current instanceof List list - && index < list.size()) { - current = list.get(index); - } else { - return null; - } - } - return current; - } - - /** - * Sets {@code value} at {@code jsonPath} in {@link #currentFcArgs}, creating maps and lists as - * needed and padding lists with nulls, as ADK Python's {@code _set_value_by_json_path} does. It - * stops at a segment that hits a value of the wrong type or an index above 10,000; containers - * created before that segment stay. - */ - @SuppressWarnings("unchecked") - private void setValueByJsonPath(String jsonPath, @Nullable Object value) { - List segments = parseJsonPath(jsonPath); - Object current = currentFcArgs; - for (int i = 0; i < segments.size(); i++) { - boolean last = i == segments.size() - 1; - Object child = - last - ? value - : segments.get(i + 1) instanceof Integer - ? new ArrayList<>() - : new LinkedHashMap<>(); - if (segments.get(i) instanceof String key && current instanceof Map) { - Map map = (Map) current; - if (last || !map.containsKey(key)) { - map.put(key, child); - } - current = map.get(key); - } else if (segments.get(i) instanceof Integer index - && current instanceof List - && index <= MAX_ARRAY_INDEX) { - List list = (List) current; - while (list.size() <= index) { - list.add(null); - } - if (last || list.get(index) == null) { - list.set(index, child); - } - current = list.get(index); - } else { - return; - } - } - } - - /** Splits a JSONPath such as {@code "$.items[0].name"} into map keys and list indices. */ - private static List parseJsonPath(String jsonPath) { - String path = - jsonPath.startsWith("$.") - ? jsonPath.substring(2) - : jsonPath.startsWith("$") ? jsonPath.substring(1) : jsonPath; - Matcher matcher = JSON_PATH_SEGMENT.matcher(path); - List segments = new ArrayList<>(); - while (matcher.find()) { - if (matcher.group(1) != null) { - Integer index = Ints.tryParse(matcher.group(1)); - // An index too large for an int is above MAX_ARRAY_INDEX anyway. - segments.add(index == null ? Integer.MAX_VALUE : index); - } else { - String key = - matcher.group(2) != null - ? matcher.group(2) - : matcher.group(3) != null ? matcher.group(3) : matcher.group(4); - segments.add(unescapeJsonPathKey(key)); - } - } - return segments; - } - - /** Resolves backslash escapes in a JSONPath key the way ADK Python does. */ - private static String unescapeJsonPathKey(String key) { - return JSON_PATH_ESCAPE - .matcher(key) - .replaceAll(match -> - Matcher.quoteReplacement( - match.group(1) != null - ? String.valueOf((char) Integer.parseInt(match.group(1), 16)) - : switch (match.group(2)) { - case "n" -> "\n"; - case "r" -> "\r"; - case "t" -> "\t"; - case "b" -> "\b"; - case "f" -> "\f"; - default -> match.group(2); - })); - } - - /** - * Flushes the accumulated streamed function call (if any) to {@link #accumulatedSequence} as a - * single complete part, mirroring ADK Python's {@code _flush_function_call_to_sequence}. - */ - private void flushFunctionCallToSequence() { - if (currentFcName == null) { - return; - } - FunctionCall.Builder fcBuilder = - FunctionCall.builder().name(currentFcName).args(new LinkedHashMap<>(currentFcArgs)); - if (currentFcId != null) { - fcBuilder.id(currentFcId); - } - Part.Builder partBuilder = Part.builder().functionCall(fcBuilder.build()); - if (currentThoughtSignature != null) { - partBuilder.thoughtSignature(currentThoughtSignature); - } - accumulatedSequence.add(partBuilder.build()); - currentFcName = null; - currentFcArgs = new LinkedHashMap<>(); - currentFcId = null; - currentThoughtSignature = null; - } - - /** Flushes any accumulated text or thought content in the buffer as a new {@link Part}. */ - private void flushTextBufferToSequence() { - if (!currentTextBuffer.isEmpty()) { - Part.Builder partBuilder = - Part.builder().text(currentTextBuffer.toString()).thought(currentTextIsThought); - if (currentTextThoughtSignature != null) { - partBuilder.thoughtSignature(currentTextThoughtSignature); - currentTextThoughtSignature = null; - } - accumulatedSequence.add(partBuilder.build()); - currentTextBuffer.setLength(0); - currentTextIsThought = false; - } - } - - /** - * Emits the final aggregated, non-partial response with all accumulated parts (thoughts, text, - * function calls). Mirrors ADK Python's {@code StreamingResponseAggregator.close()}: emitted - * even without a finish reason so accumulated content is never dropped; a non-STOP finish - * reason is surfaced as an error. - */ - private Flowable processFinalResponse() { - if (lastRawResponse == null) { - return Flowable.empty(); - } - LlmResponse currentResponse = LlmResponse.create(lastRawResponse); - - flushTextBufferToSequence(); - // Flush any in-progress streamed function call whose stream ended before completing. - flushFunctionCallToSequence(); - - // Nothing accumulated and no finish reason: any empty/metadata chunk already streamed, skip. - boolean hasFinishReason = currentResponse.finishReason().isPresent(); - if (accumulatedSequence.isEmpty() && !hasFinishReason) { - return Flowable.empty(); - } - - LlmResponse.Builder finalResponseBuilder = currentResponse.toBuilder().partial(null); - if (hasFinishReason && !isStop(currentResponse)) { - finalResponseBuilder.errorCode(currentResponse.finishReason().get()); - lastRawResponse - .candidates() - .filter(candidates -> !candidates.isEmpty()) - .map(candidates -> candidates.get(0)) - .flatMap(Candidate::finishMessage) - .ifPresent(finalResponseBuilder::errorMessage); - } - - if (accumulatedSequence.isEmpty()) { - return Flowable.just(finalResponseBuilder.build()); - } - - // No re-attach of the final chunk's signature: every part now keeps the signature the model - // put on it, so reading part 0 and stamping the last part could only mis-attribute one. ADK - // Python and the ADK Kotlin sibling have no equivalent either. - return Flowable.just( - finalResponseBuilder - .content(Content.builder().role("model").parts(accumulatedSequence).build()) - .build()); - } - - /** - * Returns whether more of the stream follows this chunk: it carries a continuation token but no - * finish reason, like a pause whose finish reason the SDK clears before resuming it. - */ - private static boolean continuesStream(GenerateContentResponse response) { - return response - .candidates() - .flatMap(candidates -> candidates.stream().findFirst()) - .filter(candidate -> candidate.finishReason().isEmpty()) - .flatMap(Candidate::continuationToken) - .filter(token -> token.length > 0) - .isPresent(); - } - - /** Checks whether the response finish reason indicates the stream has finished with STOP. */ - private static boolean isStop(LlmResponse response) { - return response - .finishReason() - .map(reason -> reason.knownEnum() == FinishReason.Known.STOP) - .orElse(false); + return response.toBuilder().errorMessage(finishMessage).build(); } } } diff --git a/core/src/main/java/com/google/adk/models/StreamingResponseAggregator.java b/core/src/main/java/com/google/adk/models/StreamingResponseAggregator.java new file mode 100644 index 000000000..32cb03eea --- /dev/null +++ b/core/src/main/java/com/google/adk/models/StreamingResponseAggregator.java @@ -0,0 +1,469 @@ +/* + * Copyright 2026 Google LLC + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.google.adk.models; + +import com.google.common.collect.ImmutableList; +import com.google.common.primitives.Ints; +import com.google.genai.types.Content; +import com.google.genai.types.FinishReason; +import com.google.genai.types.FunctionCall; +import com.google.genai.types.GenerateContentResponseUsageMetadata; +import com.google.genai.types.GroundingMetadata; +import com.google.genai.types.Part; +import com.google.genai.types.PartialArg; +import java.util.ArrayList; +import java.util.LinkedHashMap; +import java.util.List; +import java.util.Map; +import java.util.Optional; +import java.util.regex.Matcher; +import java.util.regex.Pattern; +import org.jspecify.annotations.Nullable; + +/** + * Aggregates the chunks of one streamed model turn into partial responses and one final response + * holding the whole turn. + * + *

Pass each chunk to {@link #processResponse}, then call {@link #aggregate} once the stream + * ends. An instance handles a single stream and is not thread-safe. + */ +final class StreamingResponseAggregator { + /** The largest list index a streamed argument path may set, as in ADK Python. */ + private static final int MAX_ARRAY_INDEX = 10_000; + + /** + * A JSONPath segment, as in ADK Python: a list index such as {@code [0]}, a quoted key such as + * {@code ['a.b']} or {@code ["a.b"]}, or a key with an optional dot. Keys may hold escapes. The + * key loops are possessive: a greedy one recurses per character and overflows the stack. + */ + private static final Pattern JSON_PATH_SEGMENT = + Pattern.compile( + "\\[\\s*(\\d+)\\s*]" + + "|\\['((?:[^'\\\\]|\\\\.)*+)'\\]" + + "|\\[\"((?:[^\"\\\\]|\\\\.)*+)\"\\]" + + "|\\.?((?:[^.\\[\\]\\\\]|\\\\.)++)", + // Only \n ends a line, so "." matches what Python's "." does. + Pattern.UNIX_LINES); + + /** A backslash escape in a JSONPath key: {@code \\uXXXX} or one escaped character. */ + private static final Pattern JSON_PATH_ESCAPE = + Pattern.compile("\\\\u([0-9a-fA-F]{4})|\\\\(.)", Pattern.UNIX_LINES); + + /** A whole number whose magnitude is at most 2^53 - 1 has an exact double; others may not. */ + private static final double MAX_EXACT_DOUBLE_INTEGER = 9007199254740991d; + + private final List accumulatedSequence = new ArrayList<>(); + private final StringBuilder currentTextBuffer = new StringBuilder(); + private boolean currentTextIsThought; + // Kept apart from the streamed call's signature so interleaved chunks cannot swap them. + private byte @Nullable [] currentTextThoughtSignature = null; + + private @Nullable LlmResponse lastResponse = null; + + // Latest value from any chunk: providers may send these before the last chunk. + private @Nullable GenerateContentResponseUsageMetadata usageMetadata = null; + private @Nullable FinishReason finishReason = null; + private @Nullable GroundingMetadata groundingMetadata = null; + private @Nullable Content terminatorContent = null; + + // The streamed function call being assembled from partialArgs chunks. + private @Nullable String currentFcName = null; + private Map currentFcArgs = new LinkedHashMap<>(); + private @Nullable String currentFcId = null; + private byte @Nullable [] currentThoughtSignature = null; + + /** + * Accumulates {@code response} and returns it as a partial response, with an ID on every function + * call. Returns empty if the chunk carries no content, such as a metadata-only chunk. + */ + Optional processResponse(LlmResponse response) { + lastResponse = response; + response.usageMetadata().ifPresent(usage -> usageMetadata = usage); + response.finishReason().ifPresent(reason -> finishReason = reason); + response.groundingMetadata().ifPresent(grounding -> groundingMetadata = grounding); + List parts = response.content().flatMap(Content::parts).orElse(ImmutableList.of()); + // Only terminators: a dropped part, such as a nameless function call, must not reach the final. + if (parts.stream().allMatch(StreamingResponseAggregator::isStreamTerminator)) { + response.content().ifPresent(content -> terminatorContent = content); + } + List partsWithIds = ensureFunctionCallIds(parts); + + if (!accumulateParts(partsWithIds)) { + return Optional.empty(); + } + // Rebuilt from partsWithIds so the partial's function call IDs match the final response. + Content.Builder rebuilt = Content.builder().parts(partsWithIds); + response.content().flatMap(Content::role).ifPresent(rebuilt::role); + return Optional.of(response.toBuilder().content(rebuilt.build()).partial(true).build()); + } + + /** + * Returns the final, non-partial response: every accumulated part, or else the latest content + * made only of stream terminators, with the latest usage, finish reason and grounding metadata; + * other fields come from the last chunk. Once a finish reason is seen, the error code is that + * reason unless it is STOP, and the error message is cleared. Returns empty only if no chunk was + * processed. + */ + Optional aggregate() { + if (lastResponse == null) { + return Optional.empty(); + } + + flushTextBufferToSequence(); + // Flush any in-progress streamed function call whose stream ended before completing. + flushFunctionCallToSequence(); + + LlmResponse.Builder finalResponseBuilder = + lastResponse.toBuilder() + .partial(null) + .usageMetadata(usageMetadata) + .finishReason(finishReason) + .groundingMetadata(groundingMetadata); + if (finishReason != null) { + // Overrides the placeholder error a trailing chunk without candidates carries. + finalResponseBuilder.errorCode(isStop(finishReason) ? null : finishReason).errorMessage(null); + } + + return Optional.of( + finalResponseBuilder + .content( + accumulatedSequence.isEmpty() + // Without content or an error code, BaseLlmFlow drops the final and its usage. + ? terminatorContent + : Content.builder() + .role("model") + .parts(new ArrayList<>(accumulatedSequence)) + .build()) + .build()); + } + + /** + * Returns whether the part is the empty-text terminator Gemini 3 ends a stream with: empty text + * and nothing else worth keeping. Compared by rebuilding rather than against a single literal, so + * a terminator that also carries an explicit {@code thought=false} is still recognized. + */ + private static boolean isStreamTerminator(Part part) { + if (!part.text().map(String::isEmpty).orElse(false)) { + return false; + } + Part.Builder terminator = Part.builder().text(""); + part.thought().ifPresent(terminator::thought); + return terminator.build().equals(part); + } + + /** + * Returns a list of parts where every function-call part has a non-empty ID. If a part's function + * call already has an ID, the original part is preserved; otherwise a new part with a + * client-generated ID is substituted. Non-FC parts are passed through unchanged. + */ + private static List ensureFunctionCallIds(List parts) { + List result = new ArrayList<>(parts.size()); + for (Part part : parts) { + if (part.functionCall().isPresent()) { + FunctionCall fc = part.functionCall().get(); + if (fc.id().map(String::isEmpty).orElse(true)) { + FunctionCall withId = + fc.toBuilder().id(FunctionCallIds.generateClientFunctionCallId()).build(); + result.add(part.toBuilder().functionCall(withId).build()); + continue; + } + } + result.add(part); + } + return result; + } + + /** + * Accumulates content from incoming parts: text, function calls, and any other content part + * (inline image/audio data, file data, code execution, server-side tool calls/responses, + * standalone thought signatures, and future part types), which are appended verbatim as ADK + * Python does. The empty-text part that ends a Gemini 3 stream is the one thing dropped. + * Function-call parts passed to this method are expected to already have IDs (see {@link + * #ensureFunctionCallIds}). + * + * @return true if any content part was present, false otherwise. + */ + private boolean accumulateParts(List parts) { + boolean hasContent = false; + for (Part part : parts) { + String text = part.text().orElse(""); + if (!text.isEmpty()) { + hasContent = true; + boolean isThought = part.thought().orElse(false); + // Flush first, or the new run's signature would land on the flushed run. + if (!currentTextBuffer.isEmpty() && isThought != currentTextIsThought) { + flushTextBufferToSequence(); + } + if (currentTextBuffer.isEmpty()) { + currentTextIsThought = isThought; + } + // Keep the run's first signature, as ADK Python does. + if (currentTextThoughtSignature == null + && part.thoughtSignature().map(sig -> sig.length > 0).orElse(false)) { + currentTextThoughtSignature = part.thoughtSignature().get(); + } + currentTextBuffer.append(text); + } else if (part.functionCall().isPresent()) { + hasContent = true; + processFunctionCallPart(part); + } else if (isStreamTerminator(part)) { + // Gemini 3 ends a stream with a bare empty text part; it carries nothing to keep. + } else { + // Kept as sent: a signature moved to another part would come back on an unsigned part. + hasContent = true; + flushTextBufferToSequence(); + accumulatedSequence.add(part); + } + } + return hasContent; + } + + /** + * Processes a function-call part, mirroring ADK Python's {@code _process_function_call_part}. A + * function call whose arguments are streamed across chunks (it carries {@code partialArgs} or + * {@code willContinue=true}) is accumulated and flushed as a single complete part once it + * finishes; a complete (non-streaming) function call is appended directly. + */ + private void processFunctionCallPart(Part part) { + FunctionCall fc = part.functionCall().get(); + boolean hasName = fc.name().filter(name -> !name.isEmpty()).isPresent(); + // Gemini can end a streamed call with a separate nameless willContinue=false part. + boolean streamedPart = + fc.partialArgs().map(args -> !args.isEmpty()).orElse(false) + || fc.willContinue().orElse(false) + || (currentFcName != null && !hasName); + if (streamedPart) { + // Capture the thought signature from the first chunk that carries one. + if (currentThoughtSignature == null + && part.thoughtSignature().map(sig -> sig.length > 0).orElse(false)) { + currentThoughtSignature = part.thoughtSignature().get(); + } + processStreamingFunctionCall(fc); + } else if (hasName) { + // Complete call: flush any open streamed call first so it is neither dropped nor merged. + flushTextBufferToSequence(); + flushFunctionCallToSequence(); + accumulatedSequence.add(part); + } + } + + /** + * Accumulates one chunk of a streamed function call, mirroring ADK Python's {@code + * _process_streaming_function_call}: merges the function name/ID and each {@code partialArg} (by + * JSONPath) into {@link #currentFcArgs}, then flushes the completed call once {@code + * willContinue} is no longer set. + */ + private void processStreamingFunctionCall(FunctionCall fc) { + fc.name().filter(name -> !name.isEmpty()).ifPresent(name -> currentFcName = name); + // One ID for the whole call, so its partial and final responses correlate. + if (currentFcId == null) { + currentFcId = + fc.id() + .filter(id -> !id.isEmpty()) + .orElseGet(FunctionCallIds::generateClientFunctionCallId); + } + for (PartialArg partialArg : fc.partialArgs().orElse(ImmutableList.of())) { + String jsonPath = partialArg.jsonPath().orElse(""); + if (jsonPath.isEmpty()) { + continue; + } + applyPartialArg(partialArg, jsonPath); + } + if (!fc.willContinue().orElse(false)) { + flushTextBufferToSequence(); + flushFunctionCallToSequence(); + } + } + + /** + * Applies a single {@link PartialArg} to {@link #currentFcArgs} at {@code jsonPath}, mirroring + * ADK Python's {@code _get_value_from_partial_arg}: string chunks are appended to any existing + * string at the path, while number/bool/null values overwrite. + */ + private void applyPartialArg(PartialArg partialArg, String jsonPath) { + if (partialArg.stringValue().isPresent()) { + Object existing = getValueByJsonPath(jsonPath); + String chunk = partialArg.stringValue().get(); + setValueByJsonPath(jsonPath, existing instanceof String s ? s + chunk : chunk); + } else if (partialArg.numberValue().isPresent()) { + setValueByJsonPath(jsonPath, wholeNumberAsInteger(partialArg.numberValue().get())); + } else if (partialArg.boolValue().isPresent()) { + setValueByJsonPath(jsonPath, partialArg.boolValue().get()); + } else if (partialArg.nullValue().isPresent()) { + setValueByJsonPath(jsonPath, null); + } + } + + /** + * Returns a whole number whose magnitude is at most 2^53 - 1 as the Integer or Long a + * non-streamed call carries, because schema validation rejects a Double for an INTEGER field. Any + * other value stays a Double. + */ + private static Number wholeNumberAsInteger(double value) { + if (value != Math.rint(value) || Math.abs(value) > MAX_EXACT_DOUBLE_INTEGER) { + return value; + } + long whole = (long) value; + if (whole == (int) whole) { + return (int) whole; + } + return whole; + } + + /** Returns the value currently stored at {@code jsonPath} in {@link #currentFcArgs}, or null. */ + private @Nullable Object getValueByJsonPath(String jsonPath) { + Object current = currentFcArgs; + for (Object segment : parseJsonPath(jsonPath)) { + if (segment instanceof String key + && current instanceof Map map + && map.containsKey(key)) { + current = map.get(key); + } else if (segment instanceof Integer index + && current instanceof List list + && index < list.size()) { + current = list.get(index); + } else { + return null; + } + } + return current; + } + + /** + * Sets {@code value} at {@code jsonPath} in {@link #currentFcArgs}, creating maps and lists as + * needed and padding lists with nulls, as ADK Python's {@code _set_value_by_json_path} does. It + * stops at a segment that hits a value of the wrong type or an index above 10,000; containers + * created before that segment stay. + */ + @SuppressWarnings("unchecked") + private void setValueByJsonPath(String jsonPath, @Nullable Object value) { + List segments = parseJsonPath(jsonPath); + Object current = currentFcArgs; + for (int i = 0; i < segments.size(); i++) { + boolean last = i == segments.size() - 1; + Object child = + last + ? value + : segments.get(i + 1) instanceof Integer ? new ArrayList<>() : new LinkedHashMap<>(); + if (segments.get(i) instanceof String key && current instanceof Map) { + Map map = (Map) current; + if (last || !map.containsKey(key)) { + map.put(key, child); + } + current = map.get(key); + } else if (segments.get(i) instanceof Integer index + && current instanceof List + && index <= MAX_ARRAY_INDEX) { + List list = (List) current; + while (list.size() <= index) { + list.add(null); + } + if (last || list.get(index) == null) { + list.set(index, child); + } + current = list.get(index); + } else { + return; + } + } + } + + /** Splits a JSONPath such as {@code "$.items[0].name"} into map keys and list indices. */ + private static List parseJsonPath(String jsonPath) { + String path = + jsonPath.startsWith("$.") + ? jsonPath.substring(2) + : jsonPath.startsWith("$") ? jsonPath.substring(1) : jsonPath; + Matcher matcher = JSON_PATH_SEGMENT.matcher(path); + List segments = new ArrayList<>(); + while (matcher.find()) { + if (matcher.group(1) != null) { + Integer index = Ints.tryParse(matcher.group(1)); + // An index too large for an int is above MAX_ARRAY_INDEX anyway. + segments.add(index == null ? Integer.MAX_VALUE : index); + } else { + String key = + matcher.group(2) != null + ? matcher.group(2) + : matcher.group(3) != null ? matcher.group(3) : matcher.group(4); + segments.add(unescapeJsonPathKey(key)); + } + } + return segments; + } + + /** Resolves backslash escapes in a JSONPath key the way ADK Python does. */ + private static String unescapeJsonPathKey(String key) { + return JSON_PATH_ESCAPE + .matcher(key) + .replaceAll(match -> + Matcher.quoteReplacement( + match.group(1) != null + ? String.valueOf((char) Integer.parseInt(match.group(1), 16)) + : switch (match.group(2)) { + case "n" -> "\n"; + case "r" -> "\r"; + case "t" -> "\t"; + case "b" -> "\b"; + case "f" -> "\f"; + default -> match.group(2); + })); + } + + /** + * Flushes the accumulated streamed function call (if any) to {@link #accumulatedSequence} as a + * single complete part, mirroring ADK Python's {@code _flush_function_call_to_sequence}. + */ + private void flushFunctionCallToSequence() { + if (currentFcName == null) { + return; + } + FunctionCall.Builder fcBuilder = + FunctionCall.builder().name(currentFcName).args(new LinkedHashMap<>(currentFcArgs)); + if (currentFcId != null) { + fcBuilder.id(currentFcId); + } + Part.Builder partBuilder = Part.builder().functionCall(fcBuilder.build()); + if (currentThoughtSignature != null) { + partBuilder.thoughtSignature(currentThoughtSignature); + } + accumulatedSequence.add(partBuilder.build()); + currentFcName = null; + currentFcArgs = new LinkedHashMap<>(); + currentFcId = null; + currentThoughtSignature = null; + } + + /** Flushes any accumulated text or thought content in the buffer as a new {@link Part}. */ + private void flushTextBufferToSequence() { + if (!currentTextBuffer.isEmpty()) { + Part.Builder partBuilder = + Part.builder().text(currentTextBuffer.toString()).thought(currentTextIsThought); + if (currentTextThoughtSignature != null) { + partBuilder.thoughtSignature(currentTextThoughtSignature); + currentTextThoughtSignature = null; + } + accumulatedSequence.add(partBuilder.build()); + currentTextBuffer.setLength(0); + currentTextIsThought = false; + } + } + + private static boolean isStop(FinishReason reason) { + return reason.knownEnum() == FinishReason.Known.STOP; + } +} diff --git a/core/src/test/java/com/google/adk/models/GeminiTest.java b/core/src/test/java/com/google/adk/models/GeminiTest.java index 64585479a..dc9d516ee 100644 --- a/core/src/test/java/com/google/adk/models/GeminiTest.java +++ b/core/src/test/java/com/google/adk/models/GeminiTest.java @@ -33,11 +33,13 @@ import com.google.common.collect.ImmutableMap; import com.google.common.collect.Iterables; import com.google.genai.types.Blob; +import com.google.genai.types.BlockedReason; import com.google.genai.types.Candidate; import com.google.genai.types.Content; import com.google.genai.types.FinishReason; import com.google.genai.types.FunctionCall; import com.google.genai.types.GenerateContentResponse; +import com.google.genai.types.GenerateContentResponsePromptFeedback; import com.google.genai.types.GenerateContentResponseUsageMetadata; import com.google.genai.types.Part; import com.google.genai.types.PartialArg; @@ -530,6 +532,152 @@ public BaseLlmConnection connect(LlmRequest llmRequest) { assertThat(Iterables.getLast(events).content().get().text()).isEqualTo("{\"guests\":2}"); } + @Test + public void runner_sseTurnWithOnlyStreamTerminator_emitsOneEventWithUsage() { + GenerateContentResponseUsageMetadata usage = createUsageMetadata(120, 5, 125); + + ImmutableList events = + runSseTurn( + toResponseWithText("", FinishReason.Known.STOP).toBuilder() + .usageMetadata(usage) + .build()); + + assertThat(events).hasSize(1); + assertThat(events.get(0).usageMetadata()).hasValue(usage); + assertThat(events.get(0).finishReason().map(FinishReason::knownEnum)) + .hasValue(FinishReason.Known.STOP); + assertThat(events.get(0).errorCode()).isEmpty(); + } + + @Test + public void runner_sseTurnWithStreamTerminatorThenUsageOnlyChunk_emitsOneEventWithUsage() { + GenerateContentResponseUsageMetadata usage = createUsageMetadata(120, 5, 125); + + ImmutableList events = + runSseTurn( + toResponseWithText("", FinishReason.Known.STOP), + GenerateContentResponse.builder().usageMetadata(usage).build()); + + assertThat(events).hasSize(1); + assertThat(events.get(0).usageMetadata()).hasValue(usage); + assertThat(events.get(0).finishReason().map(FinishReason::knownEnum)) + .hasValue(FinishReason.Known.STOP); + assertThat(events.get(0).errorCode()).isEmpty(); + } + + @Test + public void runner_sseTurnWithStreamTerminatorThenStopWithoutParts_emitsOneEventWithUsage() { + GenerateContentResponseUsageMetadata usage = createUsageMetadata(120, 5, 125); + GenerateContentResponse terminator = + toResponse( + Candidate.builder() + .content(Content.builder().role("model").parts(Part.fromText("")).build()) + .build()); + GenerateContentResponse stopWithoutParts = + toResponse( + Candidate.builder().finishReason(new FinishReason(FinishReason.Known.STOP)).build()) + .toBuilder() + .usageMetadata(usage) + .build(); + + ImmutableList events = runSseTurn(terminator, stopWithoutParts); + + assertThat(events).hasSize(1); + assertThat(events.get(0).usageMetadata()).hasValue(usage); + assertThat(events.get(0).finishReason().map(FinishReason::knownEnum)) + .hasValue(FinishReason.Known.STOP); + assertThat(events.get(0).errorCode()).isEmpty(); + } + + @Test + public void runner_sseTurnWithNamelessStreamedCallThenMalformedCall_endsWithTheError() { + Part namelessCallPart = + functionCallPart( + FunctionCall.builder() + .partialArgs(PartialArg.builder().jsonPath("$.x").stringValue("1").build()) + .build()); + GenerateContentResponse namelessCall = + toResponse( + Candidate.builder() + .content(Content.builder().role("model").parts(namelessCallPart).build()) + .build()); + GenerateContentResponse malformedCall = + toResponse( + Candidate.builder() + .finishReason(new FinishReason(FinishReason.Known.MALFORMED_FUNCTION_CALL)) + .finishMessage("Malformed call.") + .build()); + + Event last = Iterables.getLast(runSseTurn(namelessCall, malformedCall)); + + assertThat(last.functionCalls()).isEmpty(); + assertThat(last.errorCode().map(FinishReason::knownEnum)) + .hasValue(FinishReason.Known.MALFORMED_FUNCTION_CALL); + assertThat(last.errorMessage()).hasValue("Malformed call."); + } + + @Test + public void runner_sseTurnWithSafetyWithoutParts_emitsOneErrorEvent() { + GenerateContentResponse blocked = + toResponse( + Candidate.builder() + .finishReason(new FinishReason(FinishReason.Known.SAFETY)) + .finishMessage("Response blocked.") + .build()); + + ImmutableList events = runSseTurn(blocked); + + assertThat(events).hasSize(1); + assertThat(events.get(0).errorCode().map(FinishReason::knownEnum)) + .hasValue(FinishReason.Known.SAFETY); + assertThat(events.get(0).errorMessage()).hasValue("Response blocked."); + } + + @Test + public void runner_sseTurnWithTextThenUsageOnlyChunk_endsWithStopAndUsage() { + GenerateContentResponseUsageMetadata usage = createUsageMetadata(5, 2, 7); + + Event last = + Iterables.getLast( + runSseTurn( + toResponseWithText("Done.", FinishReason.Known.STOP), + GenerateContentResponse.builder().usageMetadata(usage).build())); + + assertThat(last.partial().orElse(false)).isFalse(); + assertThat(last.content().get().text()).isEqualTo("Done."); + assertThat(last.finishReason().map(FinishReason::knownEnum)).hasValue(FinishReason.Known.STOP); + assertThat(last.errorCode()).isEmpty(); + assertThat(last.usageMetadata()).hasValue(usage); + } + + /** Runs one SSE turn of an agent whose Gemini model streams {@code chunks}. */ + private static ImmutableList runSseTurn(GenerateContentResponse... chunks) { + BaseLlm streamingGemini = + new BaseLlm("gemini-2.5-flash") { + @Override + public Flowable generateContent(LlmRequest llmRequest, boolean stream) { + return Gemini.processRawResponses(Flowable.fromArray(chunks)); + } + + @Override + public BaseLlmConnection connect(LlmRequest llmRequest) { + throw new UnsupportedOperationException(); + } + }; + InMemoryRunner runner = + new InMemoryRunner( + LlmAgent.builder().name("agent").model(streamingGemini).build(), "test-app"); + Session session = runner.sessionService().createSession("test-app", "user").blockingGet(); + return ImmutableList.copyOf( + runner + .runAsync( + "user", + session.id(), + Content.fromParts(Part.fromText("hello")), + RunConfig.builder().streamingMode(RunConfig.StreamingMode.SSE).build()) + .blockingIterable()); + } + /** Streams one call whose arguments are {@code numbers}, one partial arg each. */ private ImmutableMap streamedArgs(ImmutableMap numbers) { ImmutableList.Builder partialArgs = ImmutableList.builder(); @@ -974,6 +1122,126 @@ public void processRawResponses_singleEmptyResponse_emitsOneEmptyResponse() { assertLlmResponses(llmResponses, isEmptyResponse()); } + @Test + public void processRawResponses_finishReasonNotStopWithoutContent_emitsOneFinal() { + GenerateContentResponse blocked = + GenerateContentResponse.builder() + .candidates( + Candidate.builder() + .finishReason(new FinishReason(FinishReason.Known.SAFETY)) + .build()) + .build(); + + Flowable llmResponses = Gemini.processRawResponses(Flowable.just(blocked)); + + assertLlmResponses( + llmResponses, isFinalResponseWithoutContentWithErrorCode(FinishReason.Known.SAFETY)); + } + + @Test + public void processRawResponses_emptyChunkBeforeText_emitsNothingForIt() { + GenerateContentResponse empty = + GenerateContentResponse.builder() + .candidates( + Candidate.builder() + .content(Content.builder().parts(ImmutableList.of()).build()) + .build()) + .build(); + + Flowable llmResponses = + Gemini.processRawResponses( + Flowable.just(empty, toResponseWithText("Hi", FinishReason.Known.STOP))); + + assertLlmResponses(llmResponses, isPartialTextResponse("Hi"), isFinalTextResponse("Hi")); + } + + @Test + public void processRawResponses_maxTokensThenChunkWithoutCandidates_finalHasOnlyTheErrorCode() { + GenerateContentResponseUsageMetadata usage = createUsageMetadata(5, 7, 12); + + LlmResponse aggregated = + aggregateFinalResponse( + toResponseWithText("Cut sho", FinishReason.Known.MAX_TOKENS), + GenerateContentResponse.builder().usageMetadata(usage).build()); + + assertThat(aggregated.errorCode().map(FinishReason::knownEnum)) + .hasValue(FinishReason.Known.MAX_TOKENS); + assertThat(aggregated.errorMessage()).isEmpty(); + assertThat(aggregated.usageMetadata()).hasValue(usage); + } + + @Test + public void processRawResponses_safetyThenChunkWithoutCandidates_keepsTheFinishMessage() { + GenerateContentResponseUsageMetadata usage = createUsageMetadata(30, 10, 40); + + LlmResponse aggregated = + aggregateFinalResponse( + toResponse( + Candidate.builder() + .finishReason(new FinishReason(FinishReason.Known.SAFETY)) + .finishMessage("Response blocked.") + .build()), + GenerateContentResponse.builder().usageMetadata(usage).build()); + + assertThat(aggregated.errorCode().map(FinishReason::knownEnum)) + .hasValue(FinishReason.Known.SAFETY); + assertThat(aggregated.errorMessage()).hasValue("Response blocked."); + assertThat(aggregated.usageMetadata()).hasValue(usage); + } + + @Test + public void processRawResponses_maxTokensWithMessageThenChunkWithoutCandidates_keepsIt() { + LlmResponse aggregated = + aggregateFinalResponse( + toResponse( + Candidate.builder() + .content(Content.builder().parts(Part.fromText("Cut sho")).build()) + .finishReason(new FinishReason(FinishReason.Known.MAX_TOKENS)) + .finishMessage("Output limit reached.") + .build()), + GenerateContentResponse.builder().usageMetadata(createUsageMetadata(5, 7, 12)).build()); + + assertThat(aggregated.errorMessage()).hasValue("Output limit reached."); + } + + @Test + public void processRawResponses_maxTokensWithMessageThenCandidateWithoutReason_keepsIt() { + LlmResponse aggregated = + aggregateFinalResponse( + toResponse( + Candidate.builder() + .content(Content.builder().parts(Part.fromText("Cut sho")).build()) + .finishReason(new FinishReason(FinishReason.Known.MAX_TOKENS)) + .finishMessage("Output limit reached.") + .build()), + toResponse(Part.fromText("")), + GenerateContentResponse.builder().usageMetadata(createUsageMetadata(5, 7, 12)).build()); + + assertThat(aggregated.errorMessage()).hasValue("Output limit reached."); + } + + @Test + public void processRawResponses_promptBlocked_finalHasBlockReason() { + GenerateContentResponseUsageMetadata usage = createUsageMetadata(60, 0, 60); + GenerateContentResponse blocked = + GenerateContentResponse.builder() + .promptFeedback( + GenerateContentResponsePromptFeedback.builder() + .blockReason(new BlockedReason(BlockedReason.Known.SAFETY)) + .blockReasonMessage("Prompt blocked.") + .build()) + .usageMetadata(usage) + .build(); + + LlmResponse aggregated = aggregateFinalResponse(blocked); + + assertThat(aggregated.content()).isEmpty(); + assertThat(aggregated.errorCode().map(FinishReason::knownEnum)) + .hasValue(FinishReason.Known.SAFETY); + assertThat(aggregated.errorMessage()).hasValue("Prompt blocked."); + assertThat(aggregated.usageMetadata()).hasValue(usage); + } + @Test public void processRawResponses_finishReasonNotStop_emitsFinalWithErrorCode() { Flowable rawResponses = @@ -1018,6 +1286,23 @@ public void processRawResponses_finishReasonNotStop_emitsFinalWithErrorCode() { "Hello world", FinishReason.Known.MAX_TOKENS, "Output truncated due to token limit.")); } + @Test + public void processRawResponses_stopWithFinishMessage_finalHasNoErrorMessage() { + GenerateContentResponse stopped = + toResponse( + Candidate.builder() + .content(Content.builder().parts(Part.fromText("Done.")).build()) + .finishReason(new FinishReason(FinishReason.Known.STOP)) + .finishMessage("Model finished.") + .build()); + + LlmResponse aggregated = aggregateFinalResponse(stopped); + + assertThat(aggregated.finishReason().map(FinishReason::knownEnum)) + .hasValue(FinishReason.Known.STOP); + assertThat(aggregated.errorMessage()).isEmpty(); + } + @Test public void processRawResponses_textThenEmpty_emitsPartialTextThenFullText() { Flowable rawResponses = @@ -1335,7 +1620,6 @@ public void processRawResponses_emptyPartsThenSignature_doesNotThrowException() assertLlmResponses( llmResponses, - isEmptyResponse(), isPartialSignatureResponse("sig"), isFinalThoughtResponseWithUsageMetadataAndSignature("", metadata, "sig")); } @@ -2147,6 +2431,16 @@ private static Predicate isEmptyResponse() { }; } + private static Predicate isFinalResponseWithoutContentWithErrorCode( + FinishReason.Known expectedErrorCode) { + return response -> { + assertThat(response.partial().orElse(false)).isFalse(); + assertThat(response.content()).isEmpty(); + assertThat(response.errorCode().map(FinishReason::knownEnum)).hasValue(expectedErrorCode); + return true; + }; + } + private static Predicate isPartialTextResponseWithUsageMetadata( String expectedText, GenerateContentResponseUsageMetadata expectedMetadata) { return response -> { diff --git a/core/src/test/java/com/google/adk/models/StreamingResponseAggregatorTest.java b/core/src/test/java/com/google/adk/models/StreamingResponseAggregatorTest.java new file mode 100644 index 000000000..69fdd3d6c --- /dev/null +++ b/core/src/test/java/com/google/adk/models/StreamingResponseAggregatorTest.java @@ -0,0 +1,559 @@ +/* + * Copyright 2026 Google LLC + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package com.google.adk.models; + +import static com.google.common.collect.Iterables.getOnlyElement; +import static com.google.common.truth.Truth.assertThat; + +import com.google.common.collect.ImmutableMap; +import com.google.genai.types.Blob; +import com.google.genai.types.Content; +import com.google.genai.types.FinishReason; +import com.google.genai.types.FunctionCall; +import com.google.genai.types.GenerateContentResponse; +import com.google.genai.types.GenerateContentResponseUsageMetadata; +import com.google.genai.types.GroundingMetadata; +import com.google.genai.types.Part; +import com.google.genai.types.PartialArg; +import java.util.List; +import org.junit.Test; +import org.junit.runner.RunWith; +import org.junit.runners.JUnit4; + +@RunWith(JUnit4.class) +public final class StreamingResponseAggregatorTest { + + private static final byte[] signatureA = {1, 2}; + private static final byte[] signatureB = {3, 4}; + private static final FinishReason STOP = new FinishReason(FinishReason.Known.STOP); + + @Test + public void processResponse_textChunk_returnsChunkAsPartial() { + StreamingResponseAggregator aggregator = new StreamingResponseAggregator(); + GenerateContentResponseUsageMetadata usage = usage(5); + LlmResponse chunk = + chunk(Part.fromText("Hello")).toBuilder().usageMetadata(usage).modelVersion("m").build(); + + LlmResponse partial = aggregator.processResponse(chunk).get(); + + assertThat(partial.partial()).hasValue(true); + assertThat(partial.content().get().role()).hasValue("model"); + assertThat(partial.content().get().parts().get()).containsExactly(Part.fromText("Hello")); + assertThat(partial.usageMetadata()).hasValue(usage); + assertThat(partial.modelVersion()).hasValue("m"); + } + + @Test + public void processResponse_chunkWithoutContent_returnsEmpty() { + StreamingResponseAggregator aggregator = new StreamingResponseAggregator(); + + assertThat(aggregator.processResponse(LlmResponse.builder().usageMetadata(usage(5)).build())) + .isEmpty(); + } + + @Test + public void aggregate_textChunks_mergesIntoOneNonPartialPart() { + StreamingResponseAggregator aggregator = new StreamingResponseAggregator(); + process(aggregator, chunk(Part.fromText("Hello")), chunk(Part.fromText(" world"))); + + LlmResponse aggregated = aggregator.aggregate().get(); + + Part merged = getOnlyElement(aggregated.content().get().parts().get()); + assertThat(merged.text()).hasValue("Hello world"); + assertThat(merged.thought()).hasValue(false); + assertThat(aggregated.content().get().role()).hasValue("model"); + assertThat(aggregated.partial()).isEmpty(); + } + + @Test + public void aggregate_thoughtThenText_keepsSeparateParts() { + StreamingResponseAggregator aggregator = new StreamingResponseAggregator(); + process( + aggregator, + chunk(thought("Let me ")), + chunk(thought("think.")), + chunk(Part.fromText("Answer."))); + + List parts = aggregatedParts(aggregator); + + assertThat(parts).hasSize(2); + assertThat(parts.get(0).text()).hasValue("Let me think."); + assertThat(parts.get(0).thought()).hasValue(true); + assertThat(parts.get(1).text()).hasValue("Answer."); + assertThat(parts.get(1).thought()).hasValue(false); + } + + @Test + public void aggregate_textAroundOtherPart_keepsOrderWithoutMerging() { + StreamingResponseAggregator aggregator = new StreamingResponseAggregator(); + Part image = + Part.builder() + .inlineData(Blob.builder().mimeType("image/png").data(new byte[] {7}).build()) + .build(); + process( + aggregator, + chunk(Part.fromText("Chart:")), + chunk(image), + chunk(Part.fromText("It goes up."))); + + List parts = aggregatedParts(aggregator); + + assertThat(parts).hasSize(3); + assertThat(parts.get(0).text()).hasValue("Chart:"); + assertThat(parts.get(1)).isEqualTo(image); + assertThat(parts.get(2).text()).hasValue("It goes up."); + } + + @Test + public void aggregate_signaturesInOneTextRun_keepsTheFirst() { + StreamingResponseAggregator aggregator = new StreamingResponseAggregator(); + process( + aggregator, + chunk(Part.fromText("Hello")), + chunk(Part.builder().text(" world").thoughtSignature(signatureA).build()), + chunk(Part.builder().text("!").thoughtSignature(signatureB).build())); + + Part merged = getOnlyElement(aggregatedParts(aggregator)); + + assertThat(merged.text()).hasValue("Hello world!"); + assertThat(merged.thoughtSignature().get()).isEqualTo(signatureA); + } + + @Test + public void aggregate_thoughtAndAnswerRuns_keepTheirOwnSignatures() { + StreamingResponseAggregator aggregator = new StreamingResponseAggregator(); + process( + aggregator, + chunk(Part.builder().text("Reasoning.").thought(true).thoughtSignature(signatureA).build()), + chunk(Part.builder().text("Answer.").thoughtSignature(signatureB).build())); + + List parts = aggregatedParts(aggregator); + + assertThat(parts).hasSize(2); + assertThat(parts.get(0).thoughtSignature().get()).isEqualTo(signatureA); + assertThat(parts.get(1).thoughtSignature().get()).isEqualTo(signatureB); + } + + @Test + public void processResponse_functionCallWithoutId_sharesGeneratedIdWithAggregatedResponse() { + StreamingResponseAggregator aggregator = new StreamingResponseAggregator(); + + LlmResponse partial = + aggregator + .processResponse( + chunk(Part.fromFunctionCall("get_weather", ImmutableMap.of("city", "Paris")))) + .get(); + + String partialId = onlyFunctionCall(partial).id().get(); + FunctionCall aggregated = getOnlyElement(aggregatedParts(aggregator)).functionCall().get(); + assertThat(FunctionCallIds.isClientGeneratedFunctionCallId(partialId)).isTrue(); + assertThat(aggregated.id()).hasValue(partialId); + assertThat(aggregated.name()).hasValue("get_weather"); + assertThat(aggregated.args()).hasValue(ImmutableMap.of("city", "Paris")); + } + + @Test + public void aggregate_functionCallWithModelId_keepsTheId() { + StreamingResponseAggregator aggregator = new StreamingResponseAggregator(); + process( + aggregator, + chunk( + functionCallPart( + FunctionCall.builder().id("call-1").name("tool").args(ImmutableMap.of()).build()))); + + FunctionCall aggregated = getOnlyElement(aggregatedParts(aggregator)).functionCall().get(); + + assertThat(aggregated.id()).hasValue("call-1"); + } + + @Test + public void aggregate_textThenCompleteFunctionCall_keepsOrder() { + StreamingResponseAggregator aggregator = new StreamingResponseAggregator(); + process( + aggregator, + chunk(Part.fromText("Calling the tool.")), + chunk(Part.fromFunctionCall("tool", ImmutableMap.of()))); + + List parts = aggregatedParts(aggregator); + + assertThat(parts).hasSize(2); + assertThat(parts.get(0).text()).hasValue("Calling the tool."); + assertThat(parts.get(1).functionCall().get().name()).hasValue("tool"); + } + + @Test + public void aggregate_streamedFunctionCall_assemblesArgsFromPartialArgs() { + StreamingResponseAggregator aggregator = new StreamingResponseAggregator(); + LlmResponse firstPartial = + aggregator + .processResponse( + chunk( + Part.builder() + .functionCall( + FunctionCall.builder().name("create_ticket").willContinue(true).build()) + .thoughtSignature(signatureA) + .build())) + .get(); + process( + aggregator, + chunk( + functionCallPart( + FunctionCall.builder() + .partialArgs( + PartialArg.builder() + .jsonPath("$.title") + .stringValue("Printer is bro") + .build(), + PartialArg.builder() + .jsonPath("$.details.priority") + .numberValue(1.0) + .build()) + .willContinue(true) + .build())), + chunk( + functionCallPart( + FunctionCall.builder() + .partialArgs( + PartialArg.builder().jsonPath("$.title").stringValue("ken").build()) + .willContinue(true) + .build())), + chunk(functionCallPart(FunctionCall.builder().willContinue(false).build()))); + + Part callPart = getOnlyElement(aggregatedParts(aggregator)); + + FunctionCall call = callPart.functionCall().get(); + assertThat(call.name()).hasValue("create_ticket"); + assertThat(call.id()).hasValue(onlyFunctionCall(firstPartial).id().get()); + assertThat(call.args()) + .hasValue( + ImmutableMap.of( + "title", "Printer is broken", "details", ImmutableMap.of("priority", 1))); + assertThat(callPart.thoughtSignature().get()).isEqualTo(signatureA); + } + + @Test + public void aggregate_streamedCallThenCompleteCall_flushesTheStreamedCallFirst() { + StreamingResponseAggregator aggregator = new StreamingResponseAggregator(); + process( + aggregator, + chunk(streamedCallStart("first", "$.x", "1")), + chunk(Part.fromFunctionCall("second", ImmutableMap.of("y", 2)))); + + List parts = aggregatedParts(aggregator); + + assertThat(parts).hasSize(2); + assertThat(parts.get(0).functionCall().get().name()).hasValue("first"); + assertThat(parts.get(0).functionCall().get().args()).hasValue(ImmutableMap.of("x", "1")); + assertThat(parts.get(1).functionCall().get().name()).hasValue("second"); + } + + @Test + public void aggregate_streamedCallEndedByNamelessMarker_flushesCallBeforeTrailingText() { + StreamingResponseAggregator aggregator = new StreamingResponseAggregator(); + process( + aggregator, + chunk(streamedCallStart("tool", "$.x", "1")), + chunk(functionCallPart(FunctionCall.builder().willContinue(false).build())), + chunk(Part.fromText("Done."))); + + List parts = aggregatedParts(aggregator); + + assertThat(parts).hasSize(2); + assertThat(parts.get(0).functionCall().get().name()).hasValue("tool"); + assertThat(parts.get(1).text()).hasValue("Done."); + } + + @Test + public void aggregate_streamEndingMidCall_flushesTheIncompleteCall() { + StreamingResponseAggregator aggregator = new StreamingResponseAggregator(); + process(aggregator, chunk(streamedCallStart("tool", "$.x", "partial"))); + + FunctionCall call = getOnlyElement(aggregatedParts(aggregator)).functionCall().get(); + + assertThat(call.name()).hasValue("tool"); + assertThat(call.args()).hasValue(ImmutableMap.of("x", "partial")); + } + + @Test + public void processResponse_bareEmptyTextPart_returnsEmpty() { + StreamingResponseAggregator aggregator = new StreamingResponseAggregator(); + + assertThat(aggregator.processResponse(chunk(Part.fromText("")))).isEmpty(); + } + + @Test + public void aggregate_bareEmptyTextPart_isDropped() { + StreamingResponseAggregator aggregator = new StreamingResponseAggregator(); + process( + aggregator, + chunk(Part.fromText("")), + chunk(Part.fromText("Done.")), + chunk(Part.fromText("")).toBuilder().finishReason(STOP).build()); + + assertThat(getOnlyElement(aggregatedParts(aggregator)).text()).hasValue("Done."); + } + + @Test + public void processResponse_emptyTextPartWithSignature_returnsPartial() { + StreamingResponseAggregator aggregator = new StreamingResponseAggregator(); + Part signed = Part.builder().text("").thoughtSignature(signatureA).build(); + + assertThat(aggregator.processResponse(chunk(signed))).isPresent(); + } + + @Test + public void aggregate_emptyTextPartWithSignature_isKept() { + StreamingResponseAggregator aggregator = new StreamingResponseAggregator(); + Part signed = Part.builder().text("").thoughtSignature(signatureA).build(); + process(aggregator, chunk(signed)); + + assertThat(aggregatedParts(aggregator)).containsExactly(signed); + } + + @Test + public void aggregate_noChunks_returnsEmpty() { + assertThat(new StreamingResponseAggregator().aggregate()).isEmpty(); + } + + @Test + public void aggregate_noContentAndNoFinishReason_returnsFinalWithoutContent() { + StreamingResponseAggregator aggregator = new StreamingResponseAggregator(); + GenerateContentResponseUsageMetadata usage = usage(5); + process(aggregator, LlmResponse.builder().usageMetadata(usage).build()); + + LlmResponse aggregated = aggregator.aggregate().get(); + + assertThat(aggregated.content()).isEmpty(); + assertThat(aggregated.usageMetadata()).hasValue(usage); + } + + @Test + public void aggregate_finishReasonWithoutContent_returnsResponseWithoutContent() { + StreamingResponseAggregator aggregator = new StreamingResponseAggregator(); + process(aggregator, LlmResponse.builder().finishReason(STOP).build()); + + LlmResponse aggregated = aggregator.aggregate().get(); + + assertThat(aggregated.content()).isEmpty(); + assertThat(aggregated.finishReason()).hasValue(STOP); + assertThat(aggregated.errorCode()).isEmpty(); + } + + @Test + public void aggregate_onlyStreamTerminator_keepsTheChunkContent() { + StreamingResponseAggregator aggregator = new StreamingResponseAggregator(); + LlmResponse terminatorOnly = chunk(Part.fromText("")).toBuilder().finishReason(STOP).build(); + process(aggregator, terminatorOnly); + + LlmResponse aggregated = aggregator.aggregate().get(); + + assertThat(aggregated.content()).isEqualTo(terminatorOnly.content()); + assertThat(aggregated.finishReason()).hasValue(STOP); + } + + @Test + public void aggregate_streamTerminatorThenUsageOnlyChunk_keepsTheTerminatorContent() { + StreamingResponseAggregator aggregator = new StreamingResponseAggregator(); + LlmResponse terminator = chunk(Part.fromText("")).toBuilder().finishReason(STOP).build(); + process(aggregator, terminator, trailingUsageChunk(usage(9))); + + LlmResponse aggregated = aggregator.aggregate().get(); + + assertThat(aggregated.content()).isEqualTo(terminator.content()); + assertThat(aggregated.usageMetadata()).hasValue(usage(9)); + } + + @Test + public void aggregate_namelessStreamedCallChunk_returnsFinalWithoutContent() { + StreamingResponseAggregator aggregator = new StreamingResponseAggregator(); + process( + aggregator, + chunk( + functionCallPart( + FunctionCall.builder() + .partialArgs(PartialArg.builder().jsonPath("$.x").stringValue("1").build()) + .build()))); + + assertThat(aggregator.aggregate().get().content()).isEmpty(); + } + + @Test + public void aggregate_namelessEndMarkerThenStop_returnsFinalWithoutContent() { + StreamingResponseAggregator aggregator = new StreamingResponseAggregator(); + process( + aggregator, + chunk(functionCallPart(FunctionCall.builder().willContinue(false).build())), + LlmResponse.builder().finishReason(STOP).build()); + + assertThat(aggregator.aggregate().get().content()).isEmpty(); + } + + @Test + public void aggregate_buildsOnLastChunkMetadata() { + StreamingResponseAggregator aggregator = new StreamingResponseAggregator(); + GenerateContentResponseUsageMetadata lastUsage = usage(9); + process( + aggregator, + chunk(Part.fromText("Hi")).toBuilder().usageMetadata(usage(5)).modelVersion("m").build(), + chunk(Part.fromText("!")).toBuilder().usageMetadata(lastUsage).finishReason(STOP).build()); + + LlmResponse aggregated = aggregator.aggregate().get(); + + assertThat(aggregated.usageMetadata()).hasValue(lastUsage); + assertThat(aggregated.finishReason()).hasValue(STOP); + assertThat(aggregated.modelVersion()).isEmpty(); + assertThat(aggregated.errorCode()).isEmpty(); + } + + @Test + public void aggregate_nonStopFinishReason_setsErrorCode() { + StreamingResponseAggregator aggregator = new StreamingResponseAggregator(); + FinishReason maxTokens = new FinishReason(FinishReason.Known.MAX_TOKENS); + process( + aggregator, + chunk(Part.fromText("Cut sho")), + LlmResponse.builder().finishReason(maxTokens).build()); + + LlmResponse aggregated = aggregator.aggregate().get(); + + assertThat(getOnlyElement(aggregated.content().get().parts().get()).text()).hasValue("Cut sho"); + assertThat(aggregated.finishReason()).hasValue(maxTokens); + assertThat(aggregated.errorCode()).hasValue(maxTokens); + } + + @Test + public void aggregate_nonStopFinishReasonWithoutContent_setsErrorCodeWithoutContent() { + StreamingResponseAggregator aggregator = new StreamingResponseAggregator(); + FinishReason safety = new FinishReason(FinishReason.Known.SAFETY); + process(aggregator, LlmResponse.builder().finishReason(safety).build()); + + LlmResponse aggregated = aggregator.aggregate().get(); + + assertThat(aggregated.content()).isEmpty(); + assertThat(aggregated.finishReason()).hasValue(safety); + assertThat(aggregated.errorCode()).hasValue(safety); + } + + @Test + public void aggregate_usageOnEarlierChunk_isKept() { + StreamingResponseAggregator aggregator = new StreamingResponseAggregator(); + GenerateContentResponseUsageMetadata usage = usage(15); + process( + aggregator, + chunk(Part.fromText("Hello ")).toBuilder().usageMetadata(usage).build(), + chunk(Part.fromText("World!")).toBuilder().finishReason(STOP).build()); + + LlmResponse aggregated = aggregator.aggregate().get(); + + assertThat(aggregated.usageMetadata()).hasValue(usage); + assertThat(aggregated.finishReason()).hasValue(STOP); + } + + @Test + public void aggregate_trailingUsageOnlyChunk_keepsFinishReason() { + StreamingResponseAggregator aggregator = new StreamingResponseAggregator(); + GenerateContentResponseUsageMetadata usage = usage(42); + process( + aggregator, + chunk(Part.fromText("Hi")), + chunk(Part.fromText("!")).toBuilder().finishReason(STOP).build(), + trailingUsageChunk(usage)); + + LlmResponse aggregated = aggregator.aggregate().get(); + + assertThat(getOnlyElement(aggregated.content().get().parts().get()).text()).hasValue("Hi!"); + assertThat(aggregated.finishReason()).hasValue(STOP); + assertThat(aggregated.usageMetadata()).hasValue(usage); + assertThat(aggregated.errorCode()).isEmpty(); + assertThat(aggregated.errorMessage()).isEmpty(); + } + + @Test + public void aggregate_nonStopFinishReasonBeforeTrailingChunk_setsErrorCode() { + StreamingResponseAggregator aggregator = new StreamingResponseAggregator(); + FinishReason maxTokens = new FinishReason(FinishReason.Known.MAX_TOKENS); + process( + aggregator, + chunk(Part.fromText("Cut sho")).toBuilder().finishReason(maxTokens).build(), + trailingUsageChunk(usage(7))); + + LlmResponse aggregated = aggregator.aggregate().get(); + + assertThat(aggregated.finishReason()).hasValue(maxTokens); + assertThat(aggregated.errorCode()).hasValue(maxTokens); + assertThat(aggregated.errorMessage()).isEmpty(); + } + + @Test + public void aggregate_groundingOnEarlierChunk_isKept() { + StreamingResponseAggregator aggregator = new StreamingResponseAggregator(); + GroundingMetadata grounding = GroundingMetadata.builder().webSearchQueries("weather").build(); + process( + aggregator, + chunk(Part.fromText("Hello ")).toBuilder().groundingMetadata(grounding).build(), + chunk(Part.fromText("World!")).toBuilder().finishReason(STOP).build()); + + LlmResponse aggregated = aggregator.aggregate().get(); + + assertThat(aggregated.groundingMetadata()).hasValue(grounding); + } + + private static void process(StreamingResponseAggregator aggregator, LlmResponse... chunks) { + for (LlmResponse chunk : chunks) { + var unused = aggregator.processResponse(chunk); + } + } + + private static List aggregatedParts(StreamingResponseAggregator aggregator) { + return aggregator.aggregate().get().content().get().parts().get(); + } + + private static FunctionCall onlyFunctionCall(LlmResponse response) { + return getOnlyElement(response.content().get().parts().get()).functionCall().get(); + } + + private static LlmResponse chunk(Part... parts) { + return LlmResponse.builder() + .content(Content.builder().role("model").parts(parts).build()) + .build(); + } + + private static Part thought(String text) { + return Part.builder().text(text).thought(true).build(); + } + + private static Part functionCallPart(FunctionCall functionCall) { + return Part.builder().functionCall(functionCall).build(); + } + + private static Part streamedCallStart(String name, String jsonPath, String value) { + return functionCallPart( + FunctionCall.builder() + .name(name) + .partialArgs(PartialArg.builder().jsonPath(jsonPath).stringValue(value).build()) + .willContinue(true) + .build()); + } + + private static GenerateContentResponseUsageMetadata usage(int totalTokenCount) { + return GenerateContentResponseUsageMetadata.builder().totalTokenCount(totalTokenCount).build(); + } + + /** Returns what {@link LlmResponse#create} makes of a usage-only chunk without candidates. */ + private static LlmResponse trailingUsageChunk(GenerateContentResponseUsageMetadata usage) { + return LlmResponse.create(GenerateContentResponse.builder().usageMetadata(usage).build()); + } +}