[voice] Update HLI interface for LLM implementations

bundles/org.openhab.core.io.rest.voice/src/main/java/org/openhab/core/io/rest/voice/internal/ConversationDTO.java

@@ -0,0 +1,34 @@
+/*
+ * 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.core.io.rest.voice.internal;
+
+import java.util.List;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+
+/**
+ * A DTO that is used on the REST API to provide infos about {@link org.openhab.core.voice.text.Conversation} to UIs.
+ *
+ * @author Miguel Álvarez Díez - Initial contribution
+ */
+@Schema(name = "Conversation")
+public class ConversationDTO {
+    public String id;
+    public List<MessageDTO> messages;
+
+    public static class MessageDTO {
+        public String uid;
+        public String rol;
+        public String content;
+    }
+}

bundles/org.openhab.core.io.rest.voice/src/main/java/org/openhab/core/io/rest/voice/internal/ConversationMapper.java

@@ -0,0 +1,45 @@
+/*
+ * 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.core.io.rest.voice.internal;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.openhab.core.voice.text.Conversation;
+
+/**
+ * Mapper class that maps {@link org.openhab.core.voice.text.Conversation} instanced to their respective DTOs.
+ *
+ * @author Miguel Álvarez Díez - Initial contribution
+ */
+@NonNullByDefault
+public class ConversationMapper {
+
+    /**
+     * Maps a {@link Conversation} to a {@link ConversationDTO}.
+     *
+     * @param conversation the conversation
+     *
+     * @return the corresponding DTO
+     */
+    public static ConversationDTO map(Conversation conversation) {
+        ConversationDTO dto = new ConversationDTO();
+        dto.id = conversation.getId();
+        dto.messages = conversation.getMessages().stream().map(m -> {
+            ConversationDTO.MessageDTO messageDTO = new ConversationDTO.MessageDTO();
+            messageDTO.uid = m.getUID();
+            messageDTO.rol = m.getRole().name();
+            messageDTO.content = m.getContent();
+            return messageDTO;
+        }).toList();
+        return dto;
+    }
+}

bundles/org.openhab.core.io.rest.voice/src/main/java/org/openhab/core/io/rest/voice/internal/VoiceResource.java

@@ -18,6 +18,7 @@
 
 import javax.annotation.security.RolesAllowed;
 import javax.ws.rs.Consumes;
+import javax.ws.rs.DELETE;
 import javax.ws.rs.GET;
 import javax.ws.rs.HeaderParam;
 import javax.ws.rs.POST;
@@ -41,13 +42,17 @@
 import org.openhab.core.io.rest.RESTConstants;
 import org.openhab.core.io.rest.RESTResource;
 import org.openhab.core.library.types.PercentType;
+import org.openhab.core.voice.InterpreterContext;
 import org.openhab.core.voice.KSService;
 import org.openhab.core.voice.STTService;
 import org.openhab.core.voice.TTSService;
 import org.openhab.core.voice.Voice;
 import org.openhab.core.voice.VoiceManager;
+import org.openhab.core.voice.text.Conversation;
+import org.openhab.core.voice.text.ConversationRole;
 import org.openhab.core.voice.text.HumanLanguageInterpreter;
 import org.openhab.core.voice.text.InterpretationException;
+import org.openhab.core.voice.text.LLMTool;
 import org.osgi.service.component.annotations.Activate;
 import org.osgi.service.component.annotations.Component;
 import org.osgi.service.component.annotations.Reference;
@@ -104,6 +109,43 @@ public VoiceResource( //
         this.voiceManager = voiceManager;
     }
 
+    @GET
+    @Path("/conversations/{id: [a-zA-Z_0-9]+}")
+    @Produces(MediaType.APPLICATION_JSON)
+    @Operation(operationId = "getConversationById", summary = "Get a conversation.", responses = {
+            @ApiResponse(responseCode = "200", description = "OK", content = @Content(schema = @Schema(implementation = ConversationDTO.class))),
+            @ApiResponse(responseCode = "404", description = "Conversation not found") })
+    public Response getConversation(@PathParam("id") @Parameter(description = "conversation id") String id) {
+        Conversation conversation = voiceManager.getConversation(id);
+        if (conversation.getMessages().isEmpty()) {
+            return JSONResponse.createErrorResponse(Status.NOT_FOUND, "No conversation found");
+        }
+        return Response.ok(ConversationMapper.map(conversation)).build();
+    }
+
+    @DELETE
+    @Path("/conversations/{id: [a-zA-Z_0-9]+}")
+    @Produces(MediaType.APPLICATION_JSON)
+    @Operation(operationId = "getConversationById", summary = "Deletes a conversation.", responses = {
+            @ApiResponse(responseCode = "200", description = "OK"),
+            @ApiResponse(responseCode = "404", description = "Conversation or message not found") })
+    public Response deleteConversation(@PathParam("id") @Parameter(description = "conversation id") String id,
+            @Parameter(description = "Optional message UID") @Nullable String messageUID) {
+        Conversation conversation = voiceManager.getConversation(id);
+        if (conversation.getMessages().isEmpty()) {
+            return JSONResponse.createErrorResponse(Status.NOT_FOUND, "Conversation not found");
+        }
+        if (messageUID != null) {
+            if (!conversation.removeSinceMessage(messageUID)) {
+                return JSONResponse.createErrorResponse(Status.NOT_FOUND, "Message not found");
+            }
+        } else {
+            conversation.removeMessages();
+        }
+        voiceManager.persistConversation(conversation);
+        return Response.ok(null, MediaType.TEXT_PLAIN).build();
+    }
+
     @GET
     @Path("/interpreters")
     @Produces(MediaType.APPLICATION_JSON)
@@ -146,20 +188,31 @@ public Response getInterpreter(
             @ApiResponse(responseCode = "400", description = "interpretation exception occurs") })
     public Response interpret(
             @HeaderParam(HttpHeaders.ACCEPT_LANGUAGE) @Parameter(description = "language") @Nullable String language,
+            @QueryParam("conversation") @Parameter(description = "Conversation id") String conversationId,
+            @QueryParam("llmTools") @Parameter(description = "Comma separated list of llm-tool ids") List<String> llmToolIds,
+            @QueryParam("locationItem") @Parameter(description = "Location item id to contextualize the command") @Nullable String locationItem,
             @Parameter(description = "text to interpret", required = true) String text,
             @PathParam("ids") @Parameter(description = "comma separated list of interpreter ids") List<String> ids) {
         final Locale locale = localeService.getLocale(language);
         List<HumanLanguageInterpreter> hlis = voiceManager.getHLIsByIds(ids);
         if (hlis.isEmpty()) {
             return JSONResponse.createErrorResponse(Status.NOT_FOUND, "No interpreter found");
         }
+        List<LLMTool> llmTools = voiceManager.getLLMToolsByIds(llmToolIds);
+        Conversation conversation = voiceManager.getConversation(conversationId);
+        InterpreterContext interpreterContext = new InterpreterContext(conversation, llmTools, locationItem);
         String answer = "";
         String error = null;
         for (HumanLanguageInterpreter interpreter : hlis) {
             try {
-                answer = interpreter.interpret(locale, text);
-                logger.debug("Interpretation result: {}", answer);
+                interpreter.interpret(locale, interpreterContext);
+                Conversation.Message message = interpreterContext.conversation().getLastMessage();
+                if (message != null && message.getRole() == ConversationRole.OPENHAB) {
+                    answer = message.getContent();
+                }
                 error = null;
+                logger.debug("Interpretation result from interpreter '{}': {}", interpreter.getId(), answer);
+                voiceManager.persistConversation(conversation);
                 break;
             } catch (InterpretationException e) {
                 logger.debug("Interpretation exception: {}", e.getMessage());

bundles/org.openhab.core.model.script/src/org/openhab/core/model/script/actions/Voice.java

@@ -25,6 +25,7 @@
 import org.openhab.core.model.script.engine.action.ActionDoc;
 import org.openhab.core.model.script.engine.action.ParamDoc;
 import org.openhab.core.model.script.internal.engine.action.VoiceActionService;
+import org.openhab.core.voice.InterpretationArguments;
 import org.openhab.core.voice.KSService;
 import org.openhab.core.voice.STTService;
 import org.openhab.core.voice.TTSService;
@@ -169,7 +170,7 @@ public static void say(@ParamDoc(name = "text") Object text, @ParamDoc(name = "v
      */
     @ActionDoc(text = "interprets a given text by the default human language interpreter", returns = "human language response")
     public static String interpret(@ParamDoc(name = "text") Object text) {
-        return interpret(text, null);
+        return interpret(text, null, null, null, null);
     }
 
     /**
@@ -182,10 +183,16 @@ public static String interpret(@ParamDoc(name = "text") Object text) {
      */
     @ActionDoc(text = "interprets a given text by given human language interpreter(s)", returns = "human language response")
     public static String interpret(@ParamDoc(name = "text") Object text,
-            @ParamDoc(name = "interpreters") @Nullable String interpreters) {
+            @ParamDoc(name = "interpreters") @Nullable String interpreters,
+            @ParamDoc(name = "conversation") @Nullable String conversation,
+            @ParamDoc(name = "llm-tools") @Nullable String llmTools,
+            @ParamDoc(name = "location") @Nullable String location) {
         String response;
         try {
-            response = VoiceActionService.voiceManager.interpret(text.toString(), interpreters);
+            response = VoiceActionService.voiceManager.interpret(text.toString(),
+                    new InterpretationArguments(Objects.requireNonNullElse(interpreters, ""),
+                            Objects.requireNonNullElse(conversation, ""), Objects.requireNonNullElse(llmTools, ""),
+                            Objects.requireNonNullElse(location, "")));
         } catch (InterpretationException e) {
             String message = Objects.requireNonNullElse(e.getMessage(), "");
             say(message);
@@ -206,10 +213,12 @@ public static String interpret(@ParamDoc(name = "text") Object text,
      */
     @ActionDoc(text = "interprets a given text by given human language interpreter(s) and using the given sink", returns = "human language response")
     public static String interpret(@ParamDoc(name = "text") Object text,
-            @ParamDoc(name = "interpreters") String interpreters, @ParamDoc(name = "sink") @Nullable String sink) {
+            @ParamDoc(name = "interpreters") @Nullable String interpreters,
+            @ParamDoc(name = "sink") @Nullable String sink) {
         String response;
         try {
-            response = VoiceActionService.voiceManager.interpret(text.toString(), interpreters);
+            response = VoiceActionService.voiceManager.interpret(text.toString(),
+                    new InterpretationArguments(interpreters != null ? interpreters : "", "", "", ""));
         } catch (InterpretationException e) {
             String message = Objects.requireNonNullElse(e.getMessage(), "");
             if (sink != null) {

bundles/org.openhab.core.voice/src/main/java/org/openhab/core/voice/DialogContext.java

@@ -22,6 +22,7 @@
 import org.openhab.core.audio.AudioSink;
 import org.openhab.core.audio.AudioSource;
 import org.openhab.core.voice.text.HumanLanguageInterpreter;
+import org.openhab.core.voice.text.LLMTool;
 
 /**
  * Describes dialog configured services and options.
@@ -32,7 +33,7 @@
 public record DialogContext(@Nullable DTService dt, @Nullable String keyword, STTService stt, TTSService tts,
         @Nullable Voice voice, List<HumanLanguageInterpreter> hlis, AudioSource source, AudioSink sink, Locale locale,
         String dialogGroup, @Nullable String locationItem, @Nullable String listeningItem,
-        @Nullable String listeningMelody) {
+        @Nullable String listeningMelody, @Nullable String conversationId, List<LLMTool> llmTools) {
 
     /**
      * Builder for {@link DialogContext}
@@ -47,7 +48,9 @@ public static class Builder {
         private @Nullable TTSService tts;
         private @Nullable Voice voice;
         private List<HumanLanguageInterpreter> hlis = List.of();
+        private List<LLMTool> llmTools = List.of();
         // options
+        private @Nullable String conversationId;
         private String dialogGroup = "default";
         private @Nullable String locationItem;
         private @Nullable String listeningItem;
@@ -130,6 +133,20 @@ public Builder withVoice(@Nullable Voice voice) {
             return this;
         }
 
+        public Builder withConversationId(@Nullable String conversationId) {
+            if (conversationId != null) {
+                this.conversationId = conversationId;
+            }
+            return this;
+        }
+
+        public Builder withLLMTools(List<LLMTool> llmTools) {
+            if (!llmTools.isEmpty()) {
+                this.llmTools = llmTools;
+            }
+            return this;
+        }
+
         public Builder withDialogGroup(@Nullable String dialogGroup) {
             if (dialogGroup != null) {
                 this.dialogGroup = dialogGroup;
@@ -199,7 +216,8 @@ public DialogContext build() throws IllegalStateException {
                 throw new IllegalStateException("Cannot build dialog context: " + String.join(", ", errors) + ".");
             } else {
                 return new DialogContext(dtService, keyword, sttService, ttsService, voice, hliServices, audioSource,
-                        audioSink, locale, dialogGroup, locationItem, listeningItem, listeningMelody);
+                        audioSink, locale, dialogGroup, locationItem, listeningItem, listeningMelody, conversationId,
+                        llmTools);
             }
         }
     }

bundles/org.openhab.core.voice/src/main/java/org/openhab/core/voice/DialogRegistration.java

@@ -57,6 +57,14 @@ public class DialogRegistration {
      * List of interpreters
      */
     public List<String> hliIds = List.of();
+    /**
+     * Conversation id.
+     */
+    public @Nullable String conversationId;
+    /**
+     * List of LLM tools
+     */
+    public List<String> llmToolIds = List.of();
     /**
      * Dialog locale
      */

bundles/org.openhab.core.voice/src/main/java/org/openhab/core/voice/InterpretationArguments.java

@@ -0,0 +1,24 @@
+/*
+ * 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.core.voice;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+
+/**
+ * This service provides functionality around voice services and is the central service to be used directly by others.
+ *
+ * @author Miguel Álvarez Díez - Initial contribution
+ */
+@NonNullByDefault
+public record InterpretationArguments(String hliIdList, String conversationId, String toolIdList, String locationItem) {
+}

bundles/org.openhab.core.voice/src/main/java/org/openhab/core/voice/InterpreterContext.java

@@ -0,0 +1,31 @@
+/*
+ * 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.core.voice;
+
+import java.util.List;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.eclipse.jdt.annotation.Nullable;
+import org.openhab.core.voice.text.Conversation;
+import org.openhab.core.voice.text.LLMTool;
+
+/**
+ * Context passed to the {@link org.openhab.core.voice.text.HumanLanguageInterpreter}
+ * when interpreting a new input text.
+ *
+ * @author Miguel Álvarez Díez - Initial contribution
+ */
+@NonNullByDefault
+public record InterpreterContext(Conversation conversation, List<LLMTool> tools, @Nullable String locationItem) {
+
+}