[gemini] Fix parallel function calls in HLI tool loop

Gemini can return several functionCall parts in one model turn, with
the thought signature only on the first part. The HLI stored each call
as its own TOOL_CALL/TOOL_RETURN pair and the API client replayed them
as separate single-call model turns, which Gemini 3.x rejects with 400
INVALID_ARGUMENT (missing thought_signature).

Batch parallel calls into a single TOOL_CALL message (JSON array) and
their results into a single TOOL_RETURN (JSON array of strings), which
also satisfies the conversation rule that a TOOL_RETURN must directly
follow its TOOL_CALL. The API client rebuilds them as one model turn
with all functionCall parts and one user turn with all
functionResponse parts, now echoing the per-call id so equal-named
parallel calls pair unambiguously.

Includes unit tests for the JSON batch (de-)serialization helpers.

Signed-off-by: Christian Heldt <snaut@tutanota.com>

Author: cheldt

bundles/org.openhab.binding.gemini/src/main/java/org/openhab/binding/gemini/internal/api/GeminiApiClient.java

@@ -59,6 +59,7 @@
 import com.fasterxml.jackson.annotation.JsonInclude.Include;
 import com.fasterxml.jackson.core.JsonProcessingException;
 import com.fasterxml.jackson.databind.ObjectMapper;
+import com.google.gson.JsonSyntaxException;
 
 /**
  * The {@link GeminiApiClient} class encapsulates all HTTP/REST API communications with the Google Gemini API.
@@ -136,7 +137,8 @@ public GeminiResponse sendPrompt(String model, List<Conversation.Message> histor
         GeminiContent systemInstruction = createSystemInstruction(systemMessage);
 
         List<GeminiContent> contents = new ArrayList<>();
-        Queue<String> pendingToolCallNames = new LinkedList<>();
+        Queue<GeminiFunctionCall> pendingToolCalls = new LinkedList<>();
+        Queue<Integer> pendingToolCallCounts = new LinkedList<>();
 
         for (Conversation.Message msg : history) {
             switch (msg.role()) {
@@ -151,35 +153,72 @@ public GeminiResponse sendPrompt(String model, List<Conversation.Message> histor
                     break;
                 }
                 case TOOL_CALL: {
-                    GeminiLLMToolCall toolCall = GeminiLLMToolCall.fromJson(msg.content());
-                    String name = toolCall.tool.replaceAll("[^a-zA-Z0-9_-]", "_");
-                    pendingToolCallNames.add(name);
-                    GeminiFunctionCall fc = new GeminiFunctionCall(name, toolCall.params, toolCall.id);
-                    GeminiPart part = new GeminiPart(null, fc, null, null, toolCall.thoughtSignature);
-                    contents.add(new GeminiContent(ROLE_MODEL, List.of(part)));
+                    // Content may hold a single tool call (JSON object) or a batch of parallel tool calls
+                    // (JSON array). All calls of a batch belong to one model turn and must be replayed as
+                    // parts of a single ROLE_MODEL content, otherwise Gemini rejects the request
+                    // (e.g. missing thought_signature on split-off calls).
+                    List<GeminiLLMToolCall> toolCalls = GeminiLLMToolCall.listFromJson(msg.content());
+                    List<GeminiPart> callParts = new ArrayList<>();
+                    for (GeminiLLMToolCall toolCall : toolCalls) {
+                        String name = toolCall.tool.replaceAll("[^a-zA-Z0-9_-]", "_");
+                        GeminiFunctionCall fc = new GeminiFunctionCall(name, toolCall.params, toolCall.id);
+                        pendingToolCalls.add(fc);
+                        callParts.add(new GeminiPart(null, fc, null, null, toolCall.thoughtSignature));
+                    }
+                    if (callParts.isEmpty()) {
+                        break;
+                    }
+                    pendingToolCallCounts.add(callParts.size());
+                    contents.add(new GeminiContent(ROLE_MODEL, callParts));
                     break;
                 }
                 case TOOL_RETURN: {
-                    String name = pendingToolCallNames.poll();
-                    if (name == null) {
+                    Integer batchSize = pendingToolCallCounts.poll();
+                    if (batchSize == null) {
                         logger.trace("skipping orphaned TOOL_RETURN");
                         break; // TOOL_RETURN without preceding TOOL_CALL - ignore
                     }
-                    GeminiFunctionResponse fr = new GeminiFunctionResponse(name, Map.of("result", msg.content()));
-                    GeminiPart part = new GeminiPart(null, null, fr, null, null);
+                    List<String> results;
+                    if (batchSize > 1) {
+                        try {
+                            results = GeminiLLMToolCall.resultsFromJson(msg.content());
+                        } catch (JsonSyntaxException e) {
+                            results = List.of(msg.content());
+                        }
+                    } else {
+                        results = List.of(msg.content());
+                    }
+
+                    List<GeminiPart> returnParts = new ArrayList<>();
+                    for (String result : results) {
+                        GeminiFunctionCall call = pendingToolCalls.poll();
+                        if (call == null) {
+                            break;
+                        }
+                        GeminiFunctionResponse fr = new GeminiFunctionResponse(call.name(), Map.of("result", result),
+                                call.id());
+                        returnParts.add(new GeminiPart(null, null, fr, null, null));
+                    }
+                    // keep the pending queue aligned if fewer results than calls were recorded
+                    for (int i = results.size(); i < batchSize; i++) {
+                        pendingToolCalls.poll();
+                    }
+                    if (returnParts.isEmpty()) {
+                        break;
+                    }
 
                     // Consolidate consecutive TOOL_RETURNs into the same ROLE_USER content
                     if (!contents.isEmpty() && ROLE_USER.equals(contents.getLast().role())) {
                         GeminiContent lastContent = contents.getLast();
                         List<GeminiPart> lastParts = lastContent.parts();
                         if (lastParts != null && !lastParts.isEmpty()
                                 && lastParts.getFirst().functionResponse() != null) {
-                            lastParts.add(part);
+                            lastParts.addAll(returnParts);
                         } else {
-                            contents.add(new GeminiContent(ROLE_USER, new ArrayList<>(List.of(part))));
+                            contents.add(new GeminiContent(ROLE_USER, returnParts));
                         }
                     } else {
-                        contents.add(new GeminiContent(ROLE_USER, new ArrayList<>(List.of(part))));
+                        contents.add(new GeminiContent(ROLE_USER, returnParts));
                     }
                     break;
                 }

bundles/org.openhab.binding.gemini/src/main/java/org/openhab/binding/gemini/internal/api/GeminiLLMToolCall.java

@@ -12,7 +12,9 @@
  */
 package org.openhab.binding.gemini.internal.api;
 
+import java.util.List;
 import java.util.Map;
+import java.util.Objects;
 
 import org.eclipse.jdt.annotation.NonNullByDefault;
 import org.eclipse.jdt.annotation.Nullable;
@@ -43,9 +45,56 @@ public static GeminiLLMToolCall fromJson(String json) throws JsonSyntaxException
         if (call == null) {
             throw new JsonSyntaxException("Deserialized GeminiLLMToolCall is null.");
         }
-        if (call.tool == null || call.params == null) {
+        // Gson bypasses the constructor, so fields declared non-null can still be null after
+        // deserialization; Objects.isNull avoids the "redundant null check" compiler warning
+        if (Objects.isNull(call.tool) || Objects.isNull(call.params)) {
             throw new JsonSyntaxException("Deserialized GeminiLLMToolCall has null tool or params.");
         }
         return call;
     }
+
+    /**
+     * Serializes a batch of parallel tool calls into a single JSON array string.
+     */
+    public static String toJsonList(List<GeminiLLMToolCall> calls) {
+        return GSON.toJson(calls);
+    }
+
+    /**
+     * Deserializes either a single tool call (JSON object, the legacy format) or a batch of
+     * parallel tool calls (JSON array) into a list.
+     */
+    public static List<GeminiLLMToolCall> listFromJson(String json) throws JsonSyntaxException {
+        if (!json.trim().startsWith("[")) {
+            return List.of(fromJson(json));
+        }
+        GeminiLLMToolCall[] calls = GSON.fromJson(json, GeminiLLMToolCall[].class);
+        if (calls == null) {
+            throw new JsonSyntaxException("Deserialized GeminiLLMToolCall list is null.");
+        }
+        for (GeminiLLMToolCall call : calls) {
+            if (call == null || Objects.isNull(call.tool) || Objects.isNull(call.params)) {
+                throw new JsonSyntaxException("Deserialized GeminiLLMToolCall has null tool or params.");
+            }
+        }
+        return List.of(calls);
+    }
+
+    /**
+     * Serializes the results of a batch of parallel tool calls into a JSON array string.
+     */
+    public static String resultsToJson(List<String> results) {
+        return GSON.toJson(results);
+    }
+
+    /**
+     * Deserializes the results of a batch of parallel tool calls from a JSON array string.
+     */
+    public static List<String> resultsFromJson(String json) throws JsonSyntaxException {
+        String[] results = GSON.fromJson(json, String[].class);
+        if (results == null) {
+            throw new JsonSyntaxException("Deserialized tool call results list is null.");
+        }
+        return List.of(results);
+    }
 }

bundles/org.openhab.binding.gemini/src/main/java/org/openhab/binding/gemini/internal/api/dto/request/GeminiFunctionResponse.java

@@ -27,5 +27,6 @@
  */
 @JsonIgnoreProperties(ignoreUnknown = true)
 @NonNullByDefault
-public record GeminiFunctionResponse(@Nullable String name, @Nullable Map<String, Object> response) {
+public record GeminiFunctionResponse(@Nullable String name, @Nullable Map<String, Object> response,
+        @Nullable String id) {
 }

bundles/org.openhab.binding.gemini/src/main/java/org/openhab/binding/gemini/internal/hli/GeminiHLIService.java

@@ -16,6 +16,7 @@
 import static org.openhab.binding.gemini.internal.GeminiBindingConstants.DEFAULT_MODEL;
 import static org.openhab.binding.gemini.internal.GeminiBindingConstants.DEFAULT_SYSTEM_MESSAGE;
 
+import java.util.ArrayList;
 import java.util.Collection;
 import java.util.HashMap;
 import java.util.List;
@@ -246,41 +247,55 @@ public String interpret(Locale locale, InterpreterContext interpreterContext) th
                 boolean hasToolCall = false;
                 StringBuilder textBuilder = new StringBuilder();
 
+                // Parallel function calls arrive as multiple functionCall parts of a single model turn.
+                // They are batched into a single TOOL_CALL / TOOL_RETURN message pair (JSON arrays), so the
+                // API client can replay them as one model turn followed by one user turn — Gemini rejects
+                // interleaved single-call replays — while respecting the conversation rule that a
+                // TOOL_RETURN must directly follow its TOOL_CALL.
+                List<GeminiLLMToolCall> toolCalls = new ArrayList<>();
                 for (GeminiPart part : parts) {
                     GeminiFunctionCall fc = part.functionCall();
                     if (fc != null) {
                         hasToolCall = true;
                         String toolName = fc.name();
                         Map<String, Object> args = fc.args();
-
-                        GeminiLLMToolCall llmToolCall = new GeminiLLMToolCall(toolName != null ? toolName : "",
-                                args != null ? args : new HashMap<>(), fc.id(), part.thoughtSignature());
-                        try {
-                            conversation.addMessage(ConversationRole.TOOL_CALL, llmToolCall.toJson());
-                        } catch (ConversationException e) {
-                            logger.warn("Cannot interpret: Failed to add TOOL_CALL to conversation", e);
-                            var ex = new InterpretationException(getLocalizedMessage(ERROR_KEY_TECHNICAL_PROBLEM,
-                                    DEFAULT_ERROR_TECHNICAL_PROBLEM, locale));
-                            ex.initCause(e);
-                            throw ex;
-                        }
-
-                        String result = executeTool(tools, toolName, args, locale);
-
-                        try {
-                            conversation.addMessage(ConversationRole.TOOL_RETURN, result);
-                        } catch (ConversationException e) {
-                            logger.warn("Cannot interpret: Failed to add TOOL_RETURN to conversation", e);
-                            var ex = new InterpretationException(getLocalizedMessage(ERROR_KEY_TECHNICAL_PROBLEM,
-                                    DEFAULT_ERROR_TECHNICAL_PROBLEM, locale));
-                            ex.initCause(e);
-                            throw ex;
-                        }
+                        toolCalls.add(new GeminiLLMToolCall(toolName != null ? toolName : "",
+                                args != null ? args : new HashMap<>(), fc.id(), part.thoughtSignature()));
                     } else if (part.text() != null) {
                         textBuilder.append(part.text());
                     }
                 }
 
+                if (!toolCalls.isEmpty()) {
+                    String callContent = toolCalls.size() == 1 ? toolCalls.getFirst().toJson()
+                            : GeminiLLMToolCall.toJsonList(toolCalls);
+                    try {
+                        conversation.addMessage(ConversationRole.TOOL_CALL, callContent);
+                    } catch (ConversationException e) {
+                        logger.warn("Cannot interpret: Failed to add TOOL_CALL to conversation", e);
+                        var ex = new InterpretationException(getLocalizedMessage(ERROR_KEY_TECHNICAL_PROBLEM,
+                                DEFAULT_ERROR_TECHNICAL_PROBLEM, locale));
+                        ex.initCause(e);
+                        throw ex;
+                    }
+
+                    List<String> results = new ArrayList<>();
+                    for (GeminiLLMToolCall toolCall : toolCalls) {
+                        results.add(executeTool(tools, toolCall.tool, toolCall.params, locale));
+                    }
+                    String returnContent = results.size() == 1 ? results.getFirst()
+                            : GeminiLLMToolCall.resultsToJson(results);
+                    try {
+                        conversation.addMessage(ConversationRole.TOOL_RETURN, returnContent);
+                    } catch (ConversationException e) {
+                        logger.warn("Cannot interpret: Failed to add TOOL_RETURN to conversation", e);
+                        var ex = new InterpretationException(getLocalizedMessage(ERROR_KEY_TECHNICAL_PROBLEM,
+                                DEFAULT_ERROR_TECHNICAL_PROBLEM, locale));
+                        ex.initCause(e);
+                        throw ex;
+                    }
+                }
+
                 if (!hasToolCall) {
                     String finalResponse = textBuilder.toString();
                     try {

bundles/org.openhab.binding.gemini/src/test/java/org/openhab/binding/gemini/internal/api/GeminiLLMToolCallTest.java

@@ -0,0 +1,123 @@
+/*
+ * Copyright (c) 2010-2026 Contributors to the openHAB project
+ *
+ * See the NOTICE file(s) distributed with this work for additional
+ * information.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ */
+package org.openhab.binding.gemini.internal.api;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import java.util.List;
+import java.util.Map;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.junit.jupiter.api.Test;
+
+import com.google.gson.JsonSyntaxException;
+
+/**
+ * Tests for the JSON (de-)serialization helpers of {@link GeminiLLMToolCall}, especially the
+ * batch format used to store parallel function calls in a single conversation message.
+ *
+ * @author Christian Heldt - Initial contribution
+ */
+@NonNullByDefault
+public class GeminiLLMToolCallTest {
+
+    @Test
+    public void singleCallRoundTripPreservesAllFields() {
+        GeminiLLMToolCall call = new GeminiLLMToolCall("item-get-state", Map.of("item", "LivingRoom_Lamp"), "call-1",
+                "signature-abc");
+
+        GeminiLLMToolCall deserialized = GeminiLLMToolCall.fromJson(call.toJson());
+
+        assertEquals("item-get-state", deserialized.tool);
+        assertEquals(Map.of("item", "LivingRoom_Lamp"), deserialized.params);
+        assertEquals("call-1", deserialized.id);
+        assertEquals("signature-abc", deserialized.thoughtSignature);
+    }
+
+    @Test
+    public void listFromJsonAcceptsLegacySingleObjectFormat() {
+        GeminiLLMToolCall call = new GeminiLLMToolCall("item-send-command", Map.of("item", "Lamp", "command", "ON"),
+                null, null);
+
+        List<GeminiLLMToolCall> deserialized = GeminiLLMToolCall.listFromJson(call.toJson());
+
+        assertEquals(1, deserialized.size());
+        assertEquals("item-send-command", deserialized.getFirst().tool);
+        assertEquals(Map.of("item", "Lamp", "command", "ON"), deserialized.getFirst().params);
+        assertNull(deserialized.getFirst().id);
+        assertNull(deserialized.getFirst().thoughtSignature);
+    }
+
+    @Test
+    public void batchRoundTripPreservesOrderAndFields() {
+        // Gemini sends the thought signature only on the first part of a parallel call batch
+        List<GeminiLLMToolCall> calls = List.of(
+                new GeminiLLMToolCall("item-get-state", Map.of("item", "Lamp1"), "call-1", "signature-abc"),
+                new GeminiLLMToolCall("item-get-state", Map.of("item", "Lamp2"), "call-2", null));
+
+        List<GeminiLLMToolCall> deserialized = GeminiLLMToolCall.listFromJson(GeminiLLMToolCall.toJsonList(calls));
+
+        assertEquals(2, deserialized.size());
+        assertEquals("item-get-state", deserialized.get(0).tool);
+        assertEquals(Map.of("item", "Lamp1"), deserialized.get(0).params);
+        assertEquals("call-1", deserialized.get(0).id);
+        assertEquals("signature-abc", deserialized.get(0).thoughtSignature);
+        assertEquals("item-get-state", deserialized.get(1).tool);
+        assertEquals(Map.of("item", "Lamp2"), deserialized.get(1).params);
+        assertEquals("call-2", deserialized.get(1).id);
+        assertNull(deserialized.get(1).thoughtSignature);
+    }
+
+    @Test
+    public void listFromJsonAcceptsLeadingWhitespace() {
+        String json = " \n [{\"tool\":\"get-date-time\",\"params\":{}}]";
+
+        List<GeminiLLMToolCall> deserialized = GeminiLLMToolCall.listFromJson(json);
+
+        assertEquals(1, deserialized.size());
+        assertEquals("get-date-time", deserialized.getFirst().tool);
+    }
+
+    @Test
+    public void listFromJsonReturnsEmptyListForEmptyArray() {
+        assertTrue(GeminiLLMToolCall.listFromJson("[]").isEmpty());
+    }
+
+    @Test
+    public void listFromJsonRejectsInvalidInput() {
+        assertThrows(JsonSyntaxException.class, () -> GeminiLLMToolCall.listFromJson("null"));
+        assertThrows(JsonSyntaxException.class, () -> GeminiLLMToolCall.listFromJson("[null]"));
+        assertThrows(JsonSyntaxException.class, () -> GeminiLLMToolCall.listFromJson("[{}]"));
+        assertThrows(JsonSyntaxException.class,
+                () -> GeminiLLMToolCall.listFromJson("[{\"tool\":\"item-get-state\"}]"));
+        assertThrows(JsonSyntaxException.class, () -> GeminiLLMToolCall.listFromJson("[{"));
+    }
+
+    @Test
+    public void resultsRoundTripPreservesOrder() {
+        List<String> results = List.of("Lamp1 is ON", "Lamp2 is OFF");
+
+        assertEquals(results, GeminiLLMToolCall.resultsFromJson(GeminiLLMToolCall.resultsToJson(results)));
+    }
+
+    @Test
+    public void resultsFromJsonRejectsInvalidInput() {
+        assertThrows(JsonSyntaxException.class, () -> GeminiLLMToolCall.resultsFromJson("null"));
+        // a plain (non-array) tool result must not parse, so the caller can fall back to treating
+        // it as a single result
+        assertThrows(JsonSyntaxException.class, () -> GeminiLLMToolCall.resultsFromJson("plain text result"));
+    }
+}