You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@zeppelin.apache.org by yo...@apache.org on 2026/10/11 11:11:25 UTC
(zeppelin) branch master updated: [ZEPPELIN-6733] Add AI assistant chat to notebooks (server-side)
This is an automated email from the ASF dual-hosted git repository.
voidmatcha pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/zeppelin.git
The following commit(s) were added to refs/heads/master by this push:
new de1d7a9e02 [ZEPPELIN-6733] Add AI assistant chat to notebooks (server-side)
de1d7a9e02 is described below
commit de1d7a9e02a14436e1791838f74f12a2850490ef
Author: SeungYoung Oh <se...@naver.com>
AuthorDate: Sun Oct 11 20:11:19 2026 +0900
[ZEPPELIN-6733] Add AI assistant chat to notebooks (server-side)
## What is this PR for?
This PR adds the server-side implementation of an AI assistant for notebooks.
### Motivation
AI can help with coding and data analysis, but using it with Zeppelin requires users to move code and results between the notebook and a separate chat. A built-in assistant can reduce this effort. It can also make notebook operations and other tasks easier through tools.
### Decisions
**Model adaptor**
- The assistant currently supports OpenAI models.
- It uses the official OpenAI Java SDK to keep up with API changes.
**Data structure**
```text
Notebook 1 ── N Conversation
Conversation 1 ── N Message
Message (assistant) 1 ── N ToolCall
```
**File path**
`$ZEPPELIN_HOME/assistant/<noteId>/<conversationId>.json`
**Permissions**
- Anyone who can read a notebook can read its conversations.
- Only the user who created a conversation can mutate it.
See the [proposal](https://cwiki.apache.org/confluence/x/5qbwGg) for more details.
### Direction
- The assistant is disabled by default and can be enabled through `zeppelin.notebook.assistant.enable`. Enabling it by default is planned once the feature is stable.
- The initial tool, `list_paragraphs`, just returns paragraph metadata. More tools are needed to make the assistant more capable. Contributions are welcome.
## What type of PR is it?
Feature
## What is the Jira issue?
* https://issues.apache.org/jira/browse/ZEPPELIN-6733
## How should this be tested?
- Run the assistant unit tests
```bash
./mvnw test -pl zeppelin-server \
-Dtest='org.apache.zeppelin.service.assistant.*Test'
```
- Verify conversation management and message history through the REST APIs
- Verify streaming responses and tool calls through WebSocket
## Questions:
* Does the license files need to update? Y
* Is there breaking changes for older versions? N
* Does this needs documentation? Y
Closes #5547 from seung-00/feature/notebook-assistant.
Signed-off-by: YONGJAE LEE <de...@gmail.com>
---
conf/zeppelin-site.xml.template | 26 ++
.../java/org/apache/zeppelin/common/Message.java | 4 +-
zeppelin-distribution/src/bin_license/LICENSE | 20 +
zeppelin-server/pom.xml | 65 +++
.../zeppelin/conf/ZeppelinConfiguration.java | 31 +-
.../rest/AssistantConversationRestApi.java | 157 +++++++
.../zeppelin/rest/AssistantMessageRestApi.java | 71 ++++
.../rest/message/ConversationMetadata.java | 55 +++
.../zeppelin/rest/message/ConversationRequest.java | 29 ++
.../rest/message/ConversationResponse.java | 48 +++
.../zeppelin/rest/message/MessagesResponse.java | 36 ++
.../apache/zeppelin/server/RestApiApplication.java | 4 +
.../org/apache/zeppelin/server/ZeppelinServer.java | 24 ++
.../zeppelin/service/ConfigurationService.java | 4 +
.../zeppelin/service/assistant/Assistant.java | 78 ++++
.../zeppelin/service/assistant/AssistantEvent.java | 61 +++
.../service/assistant/AssistantEventListener.java | 23 ++
.../service/assistant/AssistantEventPayload.java | 121 ++++++
.../service/assistant/AssistantEventType.java | 34 ++
.../zeppelin/service/assistant/AssistantImpl.java | 376 +++++++++++++++++
.../service/assistant/AssistantModule.java | 83 ++++
.../zeppelin/service/assistant/ChatModel.java | 31 ++
.../zeppelin/service/assistant/Conversation.java | 88 ++++
.../service/assistant/ConversationJsonCodec.java | 89 ++++
.../service/assistant/ConversationRepository.java | 35 ++
.../service/assistant/DisabledAssistant.java | 101 +++++
.../assistant/FileConversationRepository.java | 102 +++++
.../service/assistant/ListParagraphsTool.java | 91 ++++
.../apache/zeppelin/service/assistant/Message.java | 156 +++++++
.../zeppelin/service/assistant/MessagePage.java | 30 ++
.../service/assistant/OpenAiChatModel.java | 201 +++++++++
.../apache/zeppelin/service/assistant/Tool.java | 40 ++
.../zeppelin/service/assistant/ToolCall.java | 43 ++
.../zeppelin/service/assistant/ToolExecutor.java | 61 +++
.../zeppelin/service/assistant/ToolResult.java | 28 ++
.../zeppelin/service/assistant/ToolSpec.java | 32 ++
.../org/apache/zeppelin/socket/NotebookServer.java | 44 ++
.../service/assistant/AssistantEventTest.java | 45 ++
.../zeppelin/service/assistant/AssistantTest.java | 456 +++++++++++++++++++++
.../service/assistant/ConversationTest.java | 49 +++
.../assistant/FileConversationRepositoryTest.java | 114 ++++++
.../service/assistant/ListParagraphsToolTest.java | 87 ++++
.../service/assistant/ToolExecutorTest.java | 97 +++++
...ublic-api.ts => message-assistant.interface.ts} | 28 +-
.../interfaces/message-data-type-map.interface.ts | 3 +
.../src/interfaces/message-operator.interface.ts | 12 +
.../zeppelin-sdk/src/interfaces/public-api.ts | 1 +
47 files changed, 3404 insertions(+), 10 deletions(-)
diff --git a/conf/zeppelin-site.xml.template b/conf/zeppelin-site.xml.template
index 19727fdec3..6cf0e071d6 100755
--- a/conf/zeppelin-site.xml.template
+++ b/conf/zeppelin-site.xml.template
@@ -846,4 +846,30 @@
<description>fields to be excluded from being saved in note files, with Paragraph prefix mean the fields in Paragraph, e.g. Paragraph.results</description>
</property>
+<property>
+ <name>zeppelin.assistant.enable</name>
+ <value>false</value>
+</property>
+
+<property>
+ <name>zeppelin.assistant.openai.api.key</name>
+ <value></value>
+</property>
+
+<property>
+ <name>zeppelin.assistant.openai.endpoint</name>
+ <value>https://api.openai.com/v1</value>
+</property>
+
+<property>
+ <name>zeppelin.assistant.openai.model</name>
+ <value>gpt-6-luna</value>
+</property>
+
+<property>
+ <name>zeppelin.assistant.dir</name>
+ <value>assistant</value>
+ <description>Directory for assistant conversations.</description>
+</property>
+
</configuration>
diff --git a/zeppelin-common/src/main/java/org/apache/zeppelin/common/Message.java b/zeppelin-common/src/main/java/org/apache/zeppelin/common/Message.java
index d1e1606007..04a3f79cc2 100644
--- a/zeppelin-common/src/main/java/org/apache/zeppelin/common/Message.java
+++ b/zeppelin-common/src/main/java/org/apache/zeppelin/common/Message.java
@@ -203,7 +203,9 @@ public class Message implements JsonSerializable {
COLLABORATIVE_MODE_STATUS, // [s-c] collaborative mode status
PATCH_PARAGRAPH, // [c-s][s-c] patch editor text
NOTE_RUNNING_STATUS, // [s-c] sequential run status will be change
- NOTICE // [s-c] Notice
+ NOTICE, // [s-c] Notice
+ ASSISTANT_SEND_MESSAGE, // [c-s] send a message to the notebook assistant
+ ASSISTANT_EVENT // [s-c] assistant run stream event (see "type" field)
}
// these messages will be ignored during the sequential run of the note
diff --git a/zeppelin-distribution/src/bin_license/LICENSE b/zeppelin-distribution/src/bin_license/LICENSE
index 3c6939d403..09594969c9 100644
--- a/zeppelin-distribution/src/bin_license/LICENSE
+++ b/zeppelin-distribution/src/bin_license/LICENSE
@@ -1,5 +1,25 @@
The following components are provided under Apache License.
+ (Apache 2.0) ClassMate (com.fasterxml:classmate:1.7.0 - https://github.com/FasterXML/java-classmate)
+ (Apache 2.0) Jackson JDK8 Datatypes (com.fasterxml.jackson.datatype:jackson-datatype-jdk8:2.18.3 - https://github.com/FasterXML/jackson-modules-java8)
+ (Apache 2.0) Jackson Java Time Datatypes (com.fasterxml.jackson.datatype:jackson-datatype-jsr310:2.18.3 - https://github.com/FasterXML/jackson-modules-java8)
+ (Apache 2.0) Jackson Kotlin Module (com.fasterxml.jackson.module:jackson-module-kotlin:2.18.3 - https://github.com/FasterXML/jackson-module-kotlin)
+ (Apache 2.0) JSON Schema Generator (com.github.victools:jsonschema-generator:4.38.0 - https://github.com/victools/jsonschema-generator)
+ (Apache 2.0) JSON Schema Generator (com.github.victools:jsonschema-module-jackson:4.38.0 - https://github.com/victools/jsonschema-generator)
+ (Apache 2.0) JSON Schema Generator (com.github.victools:jsonschema-module-swagger-2:4.38.0 - https://github.com/victools/jsonschema-generator)
+ (Apache 2.0) OpenAI Java SDK (com.openai:openai-java:4.69.3 - https://github.com/openai/openai-java)
+ (Apache 2.0) OpenAI Java SDK (com.openai:openai-java-client-okhttp:4.69.3 - https://github.com/openai/openai-java)
+ (Apache 2.0) OpenAI Java SDK (com.openai:openai-java-core:4.69.3 - https://github.com/openai/openai-java)
+ (Apache 2.0) OkHttp (com.squareup.okhttp3:okhttp:4.12.0 - https://github.com/square/okhttp)
+ (Apache 2.0) Okio (com.squareup.okio:okio:3.6.0 - https://github.com/square/okio)
+ (Apache 2.0) Okio (com.squareup.okio:okio-jvm:3.6.0 - https://github.com/square/okio)
+ (Apache 2.0) Swagger Annotations (io.swagger.core.v3:swagger-annotations:2.2.31 - https://github.com/swagger-api/swagger-core)
+ (Apache 2.0) Kotlin (org.jetbrains.kotlin:kotlin-reflect:1.9.10 - https://github.com/JetBrains/kotlin)
+ (Apache 2.0) Kotlin (org.jetbrains.kotlin:kotlin-stdlib:1.9.10 - https://github.com/JetBrains/kotlin)
+ (Apache 2.0) Kotlin (org.jetbrains.kotlin:kotlin-stdlib-common:1.9.10 - https://github.com/JetBrains/kotlin)
+ (Apache 2.0) Kotlin (org.jetbrains.kotlin:kotlin-stdlib-jdk7:1.9.10 - https://github.com/JetBrains/kotlin)
+ (Apache 2.0) Kotlin (org.jetbrains.kotlin:kotlin-stdlib-jdk8:1.9.10 - https://github.com/JetBrains/kotlin)
+
(Apache 2.0) nvd3.js v1.7.1 (http://nvd3.org/) - https://github.com/novus/nvd3/blob/v1.7.1/LICENSE.md
(Apache 2.0) gson v2.8.9 (com.google.code.gson:gson:jar:2.8.9 - https://github.com/google/gson) - https://github.com/google/gson/blob/gson-parent-2.8.9/LICENSE
(Apache 2.0) Amazon Web Services SDK for Java v1.11.736 (https://aws.amazon.com/sdk-for-java/) - https://raw.githubusercontent.com/aws/aws-sdk-java/1.11.736/LICENSE.txt
diff --git a/zeppelin-server/pom.xml b/zeppelin-server/pom.xml
index 505c5ed75b..7191c0bb01 100644
--- a/zeppelin-server/pom.xml
+++ b/zeppelin-server/pom.xml
@@ -432,6 +432,71 @@
<artifactId>gson</artifactId>
</dependency>
+ <dependency>
+ <groupId>com.openai</groupId>
+ <artifactId>openai-java</artifactId>
+ <version>4.69.3</version>
+ <exclusions>
+ <!-- Declare consistent Kotlin and annotation versions below. -->
+ <exclusion>
+ <groupId>org.jetbrains.kotlin</groupId>
+ <artifactId>kotlin-stdlib-jdk8</artifactId>
+ </exclusion>
+ <exclusion>
+ <groupId>org.jetbrains.kotlin</groupId>
+ <artifactId>kotlin-reflect</artifactId>
+ </exclusion>
+ <exclusion>
+ <groupId>com.google.errorprone</groupId>
+ <artifactId>error_prone_annotations</artifactId>
+ </exclusion>
+ <exclusion>
+ <groupId>org.jetbrains</groupId>
+ <artifactId>annotations</artifactId>
+ </exclusion>
+ </exclusions>
+ </dependency>
+
+ <!-- Align SDK transitives for server and distribution. -->
+ <dependency>
+ <groupId>org.jetbrains.kotlin</groupId>
+ <artifactId>kotlin-stdlib-jdk8</artifactId>
+ <version>1.9.10</version>
+ <exclusions>
+ <!-- Use the annotation version declared below. -->
+ <exclusion>
+ <groupId>org.jetbrains</groupId>
+ <artifactId>annotations</artifactId>
+ </exclusion>
+ </exclusions>
+ </dependency>
+
+ <dependency>
+ <groupId>org.jetbrains.kotlin</groupId>
+ <artifactId>kotlin-reflect</artifactId>
+ <version>1.9.10</version>
+ <scope>runtime</scope>
+ <exclusions>
+ <!-- Use the annotation version declared below. -->
+ <exclusion>
+ <groupId>org.jetbrains</groupId>
+ <artifactId>annotations</artifactId>
+ </exclusion>
+ </exclusions>
+ </dependency>
+
+ <dependency>
+ <groupId>org.jetbrains</groupId>
+ <artifactId>annotations</artifactId>
+ <version>15.0</version>
+ </dependency>
+
+ <dependency>
+ <groupId>com.google.errorprone</groupId>
+ <artifactId>error_prone_annotations</artifactId>
+ <version>2.18.0</version>
+ </dependency>
+
<dependency>
<groupId>com.nimbusds</groupId>
<artifactId>nimbus-jose-jwt</artifactId>
diff --git a/zeppelin-server/src/main/java/org/apache/zeppelin/conf/ZeppelinConfiguration.java b/zeppelin-server/src/main/java/org/apache/zeppelin/conf/ZeppelinConfiguration.java
index 6a7e1b7909..8b161d174f 100644
--- a/zeppelin-server/src/main/java/org/apache/zeppelin/conf/ZeppelinConfiguration.java
+++ b/zeppelin-server/src/main/java/org/apache/zeppelin/conf/ZeppelinConfiguration.java
@@ -888,6 +888,26 @@ public class ZeppelinConfiguration {
return getBoolean(ConfVars.ZEPPELIN_SEARCH_SEMANTIC_ENABLE);
}
+ public boolean isAssistantEnabled() {
+ return getBoolean(ConfVars.ZEPPELIN_ASSISTANT_ENABLE);
+ }
+
+ public String getAssistantApiKey() {
+ return getString(ConfVars.ZEPPELIN_ASSISTANT_OPENAI_API_KEY);
+ }
+
+ public String getAssistantEndpoint() {
+ return getString(ConfVars.ZEPPELIN_ASSISTANT_OPENAI_ENDPOINT);
+ }
+
+ public String getAssistantModel() {
+ return getString(ConfVars.ZEPPELIN_ASSISTANT_OPENAI_MODEL);
+ }
+
+ public String getAssistantDir() {
+ return getAbsoluteDir(ConfVars.ZEPPELIN_ASSISTANT_DIR);
+ }
+
public boolean isOnlyYarnCluster() {
return getBoolean(ConfVars.ZEPPELIN_SPARK_ONLY_YARN_CLUSTER);
}
@@ -1193,7 +1213,16 @@ public class ZeppelinConfiguration {
ZEPPELIN_SPARK_ONLY_YARN_CLUSTER("zeppelin.spark.only_yarn_cluster", false),
ZEPPELIN_SESSION_CHECK_INTERVAL("zeppelin.session.check_interval", 60 * 10 * 1000),
ZEPPELIN_NOTE_CACHE_THRESHOLD("zeppelin.note.cache.threshold", 50),
- ZEPPELIN_NOTE_FILE_EXCLUDE_FIELDS("zeppelin.note.file.exclude.fields", "");
+ ZEPPELIN_NOTE_FILE_EXCLUDE_FIELDS("zeppelin.note.file.exclude.fields", ""),
+ ZEPPELIN_ASSISTANT_ENABLE("zeppelin.assistant.enable", false),
+ ZEPPELIN_ASSISTANT_DIR("zeppelin.assistant.dir", "assistant"),
+ ZEPPELIN_ASSISTANT_OPENAI_API_KEY("zeppelin.assistant.openai.api.key", ""),
+ ZEPPELIN_ASSISTANT_OPENAI_ENDPOINT(
+ "zeppelin.assistant.openai.endpoint", "https://api.openai.com/v1"
+ ),
+ ZEPPELIN_ASSISTANT_OPENAI_MODEL(
+ "zeppelin.assistant.openai.model", "gpt-6-luna"
+ );
private String varName;
private Class<?> varClass;
diff --git a/zeppelin-server/src/main/java/org/apache/zeppelin/rest/AssistantConversationRestApi.java b/zeppelin-server/src/main/java/org/apache/zeppelin/rest/AssistantConversationRestApi.java
new file mode 100644
index 0000000000..4d3b8f5201
--- /dev/null
+++ b/zeppelin-server/src/main/java/org/apache/zeppelin/rest/AssistantConversationRestApi.java
@@ -0,0 +1,157 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You 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 org.apache.zeppelin.rest;
+
+import com.google.gson.JsonSyntaxException;
+
+import jakarta.inject.Inject;
+import jakarta.inject.Singleton;
+import jakarta.ws.rs.BadRequestException;
+import jakarta.ws.rs.DELETE;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.PATCH;
+import jakarta.ws.rs.POST;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.PathParam;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.Response;
+
+import java.io.IOException;
+import java.util.Optional;
+import java.util.stream.Collectors;
+
+import org.apache.zeppelin.annotation.ZeppelinApi;
+import org.apache.zeppelin.rest.message.ConversationRequest;
+import org.apache.zeppelin.rest.message.ConversationMetadata;
+import org.apache.zeppelin.rest.message.ConversationResponse;
+import org.apache.zeppelin.server.JsonResponse;
+import org.apache.zeppelin.service.AuthenticationService;
+import org.apache.zeppelin.service.assistant.Assistant;
+
+@Path("/notes/{noteId}/conversations")
+@Produces("application/json")
+@Singleton
+public class AssistantConversationRestApi extends AbstractRestApi {
+
+ private final Assistant assistant;
+
+ @Inject
+ public AssistantConversationRestApi(
+ AuthenticationService authenticationService,
+ Assistant assistant
+ ) {
+ super(authenticationService);
+ this.assistant = assistant;
+ }
+
+ private static ConversationRequest parseBody(String body) {
+ try {
+ return GSON.fromJson(body, ConversationRequest.class);
+ } catch (JsonSyntaxException e) {
+ throw new BadRequestException();
+ }
+ }
+
+ @GET
+ @ZeppelinApi
+ public Response list(@PathParam("noteId") String noteId) throws IOException {
+ var context = getServiceContext();
+ return new JsonResponse<>(
+ Response.Status.OK,
+ "",
+ assistant.listConversations(noteId, context.getUserAndRoles()).stream()
+ .map(c -> ConversationMetadata.of(c, context.getAutheInfo().getUser()))
+ .collect(Collectors.toList())
+ ).build();
+ }
+
+ @GET
+ @Path("/{conversationId}")
+ @ZeppelinApi
+ public Response get(
+ @PathParam("noteId") String noteId,
+ @PathParam("conversationId") String conversationId
+ ) throws IOException {
+ var context = getServiceContext();
+ var conversation = assistant.getConversation(
+ noteId,
+ conversationId,
+ context.getUserAndRoles()
+ );
+ return new JsonResponse<>(
+ Response.Status.OK,
+ "",
+ ConversationResponse.of(conversation, context.getAutheInfo().getUser())
+ ).build();
+ }
+
+ @POST
+ @ZeppelinApi
+ public Response create(
+ @PathParam("noteId") String noteId,
+ String body
+ ) throws IOException {
+ String title = Optional.ofNullable(parseBody(body))
+ .map(ConversationRequest::getTitle)
+ .orElse(null);
+ var context = getServiceContext();
+ var conversation = assistant.createConversation(
+ noteId, title, context.getAutheInfo(), context.getUserAndRoles()
+ );
+ return new JsonResponse<>(
+ Response.Status.CREATED,
+ "",
+ ConversationMetadata.of(conversation, context.getAutheInfo().getUser())
+ ).build();
+ }
+
+ @PATCH
+ @Path("/{conversationId}")
+ @ZeppelinApi
+ public Response updateTitle(
+ @PathParam("noteId") String noteId,
+ @PathParam("conversationId") String conversationId,
+ String body
+ ) throws IOException {
+ String title = Optional.ofNullable(parseBody(body))
+ .map(ConversationRequest::getTitle)
+ .filter(t -> !t.isBlank())
+ .orElseThrow(() -> new BadRequestException("title is required"));
+ var context = getServiceContext();
+ var conversation = assistant.updateTitle(
+ noteId, conversationId, title, context.getAutheInfo().getUser(), context.getUserAndRoles());
+ return new JsonResponse<>(
+ Response.Status.OK,
+ "",
+ ConversationMetadata.of(conversation, context.getAutheInfo().getUser())
+ ).build();
+ }
+
+ @DELETE
+ @Path("/{conversationId}")
+ @ZeppelinApi
+ public Response delete(
+ @PathParam("noteId") String noteId,
+ @PathParam("conversationId") String conversationId
+ ) throws IOException {
+ var context = getServiceContext();
+ assistant.deleteConversation(
+ noteId, conversationId, context.getAutheInfo().getUser(), context.getUserAndRoles());
+ return Response.noContent().build();
+ }
+}
diff --git a/zeppelin-server/src/main/java/org/apache/zeppelin/rest/AssistantMessageRestApi.java b/zeppelin-server/src/main/java/org/apache/zeppelin/rest/AssistantMessageRestApi.java
new file mode 100644
index 0000000000..9d46f6ab02
--- /dev/null
+++ b/zeppelin-server/src/main/java/org/apache/zeppelin/rest/AssistantMessageRestApi.java
@@ -0,0 +1,71 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You 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 org.apache.zeppelin.rest;
+
+import jakarta.inject.Inject;
+import jakarta.inject.Singleton;
+import jakarta.ws.rs.DefaultValue;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.PathParam;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.QueryParam;
+import jakarta.ws.rs.core.Response;
+
+import java.io.IOException;
+
+import org.apache.zeppelin.annotation.ZeppelinApi;
+import org.apache.zeppelin.rest.message.MessagesResponse;
+import org.apache.zeppelin.server.JsonResponse;
+import org.apache.zeppelin.service.AuthenticationService;
+import org.apache.zeppelin.service.assistant.Assistant;
+
+@Path("/notes/{noteId}/conversations/{conversationId}/messages")
+@Produces("application/json")
+@Singleton
+public class AssistantMessageRestApi extends AbstractRestApi {
+
+ private final Assistant assistant;
+
+ @Inject
+ public AssistantMessageRestApi(
+ AuthenticationService authenticationService,
+ Assistant assistant
+ ) {
+ super(authenticationService);
+ this.assistant = assistant;
+ }
+
+ @GET
+ @ZeppelinApi
+ public Response list(
+ @PathParam("noteId") String noteId,
+ @PathParam("conversationId") String conversationId,
+ @QueryParam("cursor") String cursor,
+ @QueryParam("limit") @DefaultValue("10") int limit
+ ) throws IOException {
+ return new JsonResponse<>(
+ Response.Status.OK,
+ "",
+ MessagesResponse.of(
+ assistant.listMessages(
+ noteId, conversationId, cursor, limit, getServiceContext().getUserAndRoles()
+ ))
+ ).build();
+ }
+}
diff --git a/zeppelin-server/src/main/java/org/apache/zeppelin/rest/message/ConversationMetadata.java b/zeppelin-server/src/main/java/org/apache/zeppelin/rest/message/ConversationMetadata.java
new file mode 100644
index 0000000000..408428c7d4
--- /dev/null
+++ b/zeppelin-server/src/main/java/org/apache/zeppelin/rest/message/ConversationMetadata.java
@@ -0,0 +1,55 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You 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 org.apache.zeppelin.rest.message;
+
+import org.apache.zeppelin.service.assistant.Conversation;
+
+public final class ConversationMetadata {
+ private final String id;
+ private final String noteId;
+ private final String ownerId;
+ private final String title;
+ private final String createdAt;
+ private final String updatedAt;
+ private final boolean canSendMessage;
+
+ private ConversationMetadata(
+ String id,
+ String noteId,
+ String ownerId,
+ String title,
+ String createdAt,
+ String updatedAt,
+ boolean canSendMessage
+ ) {
+ this.id = id;
+ this.noteId = noteId;
+ this.ownerId = ownerId;
+ this.title = title;
+ this.createdAt = createdAt;
+ this.updatedAt = updatedAt;
+ this.canSendMessage = canSendMessage;
+ }
+
+ public static ConversationMetadata of(Conversation c, String userId) {
+ return new ConversationMetadata(
+ c.getId(), c.getNoteId(), c.getOwnerId(), c.getTitle(), c.getCreatedAt(), c.getUpdatedAt(),
+ c.isOwner(userId)
+ );
+ }
+}
diff --git a/zeppelin-server/src/main/java/org/apache/zeppelin/rest/message/ConversationRequest.java b/zeppelin-server/src/main/java/org/apache/zeppelin/rest/message/ConversationRequest.java
new file mode 100644
index 0000000000..9ecbf0dbf7
--- /dev/null
+++ b/zeppelin-server/src/main/java/org/apache/zeppelin/rest/message/ConversationRequest.java
@@ -0,0 +1,29 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You 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 org.apache.zeppelin.rest.message;
+
+public class ConversationRequest {
+ private final String title;
+
+ public ConversationRequest(String title) {
+ this.title = title;
+ }
+
+ public String getTitle() {
+ return title;
+ }
+}
diff --git a/zeppelin-server/src/main/java/org/apache/zeppelin/rest/message/ConversationResponse.java b/zeppelin-server/src/main/java/org/apache/zeppelin/rest/message/ConversationResponse.java
new file mode 100644
index 0000000000..e747be73b7
--- /dev/null
+++ b/zeppelin-server/src/main/java/org/apache/zeppelin/rest/message/ConversationResponse.java
@@ -0,0 +1,48 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You 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 org.apache.zeppelin.rest.message;
+
+import java.util.List;
+import org.apache.zeppelin.service.assistant.Conversation;
+import org.apache.zeppelin.service.assistant.Message;
+
+public final class ConversationResponse {
+ private final String id;
+ private final String noteId;
+ private final String ownerId;
+ private final String title;
+ private final String createdAt;
+ private final String updatedAt;
+ private final boolean canSendMessage;
+ private final List<Message> messages;
+
+ private ConversationResponse(Conversation conversation, String userId) {
+ this.id = conversation.getId();
+ this.noteId = conversation.getNoteId();
+ this.ownerId = conversation.getOwnerId();
+ this.title = conversation.getTitle();
+ this.createdAt = conversation.getCreatedAt();
+ this.updatedAt = conversation.getUpdatedAt();
+ this.canSendMessage = conversation.isOwner(userId);
+ this.messages = List.copyOf(conversation.getMessages());
+ }
+
+ public static ConversationResponse of(Conversation conversation, String userId) {
+ return new ConversationResponse(conversation, userId);
+ }
+}
diff --git a/zeppelin-server/src/main/java/org/apache/zeppelin/rest/message/MessagesResponse.java b/zeppelin-server/src/main/java/org/apache/zeppelin/rest/message/MessagesResponse.java
new file mode 100644
index 0000000000..e026886cba
--- /dev/null
+++ b/zeppelin-server/src/main/java/org/apache/zeppelin/rest/message/MessagesResponse.java
@@ -0,0 +1,36 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You 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 org.apache.zeppelin.rest.message;
+
+import java.util.List;
+import org.apache.zeppelin.service.assistant.Message;
+import org.apache.zeppelin.service.assistant.MessagePage;
+
+public final class MessagesResponse {
+ private final List<Message> messages;
+ private final String cursor;
+
+ private MessagesResponse(MessagePage page) {
+ this.messages = List.copyOf(page.messages);
+ this.cursor = page.cursor;
+ }
+
+ public static MessagesResponse of(MessagePage page) {
+ return new MessagesResponse(page);
+ }
+}
diff --git a/zeppelin-server/src/main/java/org/apache/zeppelin/server/RestApiApplication.java b/zeppelin-server/src/main/java/org/apache/zeppelin/server/RestApiApplication.java
index b43fe0111a..79ecf80f84 100644
--- a/zeppelin-server/src/main/java/org/apache/zeppelin/server/RestApiApplication.java
+++ b/zeppelin-server/src/main/java/org/apache/zeppelin/server/RestApiApplication.java
@@ -23,6 +23,8 @@ import java.util.Set;
import jakarta.ws.rs.core.Application;
+import org.apache.zeppelin.rest.AssistantConversationRestApi;
+import org.apache.zeppelin.rest.AssistantMessageRestApi;
import org.apache.zeppelin.rest.AdminRestApi;
import org.apache.zeppelin.rest.ConfigurationsRestApi;
import org.apache.zeppelin.rest.CredentialRestApi;
@@ -43,6 +45,8 @@ public class RestApiApplication extends Application {
@Override
public Set<Class<?>> getClasses() {
Set<Class<?>> s = new HashSet<>();
+ s.add(AssistantConversationRestApi.class);
+ s.add(AssistantMessageRestApi.class);
s.add(AdminRestApi.class);
s.add(ConfigurationsRestApi.class);
s.add(CredentialRestApi.class);
diff --git a/zeppelin-server/src/main/java/org/apache/zeppelin/server/ZeppelinServer.java b/zeppelin-server/src/main/java/org/apache/zeppelin/server/ZeppelinServer.java
index 480422b4a5..af255aa2c6 100644
--- a/zeppelin-server/src/main/java/org/apache/zeppelin/server/ZeppelinServer.java
+++ b/zeppelin-server/src/main/java/org/apache/zeppelin/server/ZeppelinServer.java
@@ -92,6 +92,8 @@ import org.apache.zeppelin.search.LuceneSearch;
import org.apache.zeppelin.search.NoSearchService;
import org.apache.zeppelin.search.SearchService;
import org.apache.zeppelin.service.*;
+import org.apache.zeppelin.service.assistant.Assistant;
+import org.apache.zeppelin.service.assistant.AssistantModule;
import org.apache.zeppelin.service.AuthenticationService;
import org.apache.zeppelin.service.auth.AuthenticationServiceFactory;
import org.apache.zeppelin.socket.ConnectionManager;
@@ -139,6 +141,7 @@ public class ZeppelinServer implements AutoCloseable {
private final Server jettyWebServer;
private final ServiceLocator sharedServiceLocator;
private final ConfigStorage storage;
+ private AssistantModule assistantModule;
public ZeppelinServer(ZeppelinConfiguration zConf) throws IOException {
this(zConf, DEFAULT_SERVICE_LOCATOR_NAME);
@@ -255,6 +258,24 @@ public class ZeppelinServer implements AutoCloseable {
// Lazy loading will cause paragraph recovery and cron job initialization is delayed.
Notebook notebook = ServiceLocatorUtilities.getService(
sharedServiceLocator, Notebook.class.getName());
+
+ assistantModule = new AssistantModule(
+ zConf.isAssistantEnabled(),
+ zConf.getAssistantEndpoint(),
+ zConf.getAssistantApiKey(),
+ zConf.getAssistantModel(),
+ zConf.getAssistantDir(),
+ notebook,
+ sharedServiceLocator.getService(NotebookService.class),
+ sharedServiceLocator.getService(AuthorizationService.class)
+ );
+ ServiceLocatorUtilities.bind(sharedServiceLocator, new AbstractBinder() {
+ @Override
+ protected void configure() {
+ bind(assistantModule.assistant).to(Assistant.class);
+ }
+ });
+
ServiceLocatorUtilities.getService(
sharedServiceLocator, SearchService.class.getName());
ServiceLocatorUtilities.getService(
@@ -361,6 +382,9 @@ public class ZeppelinServer implements AutoCloseable {
if (sharedServiceLocator != null) {
// Stop after Jetty so no new connection can restart the heartbeat scheduler.
sharedServiceLocator.getService(NotebookServer.class).stopHeartbeatScheduler();
+ if (assistantModule != null) {
+ assistantModule.close();
+ }
if (!zConf.isRecoveryEnabled()) {
sharedServiceLocator.getService(InterpreterSettingManager.class).close();
}
diff --git a/zeppelin-server/src/main/java/org/apache/zeppelin/service/ConfigurationService.java b/zeppelin-server/src/main/java/org/apache/zeppelin/service/ConfigurationService.java
index a3b226770d..001f01e8c9 100644
--- a/zeppelin-server/src/main/java/org/apache/zeppelin/service/ConfigurationService.java
+++ b/zeppelin-server/src/main/java/org/apache/zeppelin/service/ConfigurationService.java
@@ -37,6 +37,8 @@ public class ConfigurationService {
throws IOException {
Map<String, String> properties = zConf.dumpConfigurations(key ->
!key.contains("password") &&
+ !key.equals(ZeppelinConfiguration.ConfVars
+ .ZEPPELIN_ASSISTANT_OPENAI_API_KEY.getVarName()) &&
!key.equals(ZeppelinConfiguration.ConfVars
.ZEPPELIN_NOTEBOOK_AZURE_CONNECTION_STRING.getVarName()));
callback.onSuccess(properties, context);
@@ -53,6 +55,8 @@ public class ConfigurationService {
throws IOException {
Map<String, String> properties = zConf.dumpConfigurations(key ->
!key.contains("password") &&
+ !key.equals(ZeppelinConfiguration.ConfVars
+ .ZEPPELIN_ASSISTANT_OPENAI_API_KEY.getVarName()) &&
!key.equals(ZeppelinConfiguration.ConfVars
.ZEPPELIN_NOTEBOOK_AZURE_CONNECTION_STRING
.getVarName()) &&
diff --git a/zeppelin-server/src/main/java/org/apache/zeppelin/service/assistant/Assistant.java b/zeppelin-server/src/main/java/org/apache/zeppelin/service/assistant/Assistant.java
new file mode 100644
index 0000000000..17f0d9e3cc
--- /dev/null
+++ b/zeppelin-server/src/main/java/org/apache/zeppelin/service/assistant/Assistant.java
@@ -0,0 +1,78 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You 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 org.apache.zeppelin.service.assistant;
+
+import java.io.IOException;
+import java.util.List;
+import java.util.Set;
+import java.util.concurrent.Future;
+
+import org.apache.zeppelin.user.AuthenticationInfo;
+
+public interface Assistant {
+
+ List<Conversation> listConversations(
+ String noteId,
+ Set<String> userAndRoles
+ ) throws IOException;
+
+ Conversation createConversation(
+ String noteId,
+ String title,
+ AuthenticationInfo authInfo,
+ Set<String> userAndRoles
+ ) throws IOException;
+
+ Conversation getConversation(
+ String noteId,
+ String conversationId,
+ Set<String> userAndRoles
+ ) throws IOException;
+
+ Conversation updateTitle(
+ String noteId,
+ String conversationId,
+ String title,
+ String userId,
+ Set<String> userAndRoles
+ ) throws IOException;
+
+ void deleteConversation(
+ String noteId,
+ String conversationId,
+ String userId,
+ Set<String> userAndRoles
+ ) throws IOException;
+
+ MessagePage listMessages(
+ String noteId,
+ String conversationId,
+ String cursor,
+ int limit,
+ Set<String> userAndRoles
+ ) throws IOException;
+
+ Future<?> sendMessage(
+ String noteId,
+ String conversationId,
+ String userContent,
+ AuthenticationInfo authInfo,
+ Set<String> userAndRoles,
+ AssistantEventListener sink
+ );
+}
diff --git a/zeppelin-server/src/main/java/org/apache/zeppelin/service/assistant/AssistantEvent.java b/zeppelin-server/src/main/java/org/apache/zeppelin/service/assistant/AssistantEvent.java
new file mode 100644
index 0000000000..440fc241e5
--- /dev/null
+++ b/zeppelin-server/src/main/java/org/apache/zeppelin/service/assistant/AssistantEvent.java
@@ -0,0 +1,61 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You 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 org.apache.zeppelin.service.assistant;
+
+import com.google.gson.Gson;
+import com.google.gson.reflect.TypeToken;
+import java.util.Collections;
+import java.util.Map;
+import org.apache.commons.lang3.StringUtils;
+
+public interface AssistantEvent {
+
+ final class TextDelta implements AssistantEvent {
+ public final String delta;
+
+ public TextDelta(String delta) {
+ this.delta = delta;
+ }
+ }
+
+ final class ToolCall implements AssistantEvent {
+ private static final Gson GSON = new Gson();
+
+ public final String id;
+ public final String name;
+ public final Map<String, Object> arguments;
+
+ public ToolCall(String id, String name, String arguments) {
+ this.id = id;
+ this.name = name;
+ this.arguments = StringUtils.isBlank(arguments)
+ ? Collections.emptyMap()
+ : GSON.fromJson(arguments, new TypeToken<Map<String, Object>>() { }.getType());
+ }
+ }
+
+ final class Usage implements AssistantEvent {
+ public final int inputTokens;
+ public final int outputTokens;
+
+ public Usage(int inputTokens, int outputTokens) {
+ this.inputTokens = inputTokens;
+ this.outputTokens = outputTokens;
+ }
+ }
+}
diff --git a/zeppelin-server/src/main/java/org/apache/zeppelin/service/assistant/AssistantEventListener.java b/zeppelin-server/src/main/java/org/apache/zeppelin/service/assistant/AssistantEventListener.java
new file mode 100644
index 0000000000..f29b8e1373
--- /dev/null
+++ b/zeppelin-server/src/main/java/org/apache/zeppelin/service/assistant/AssistantEventListener.java
@@ -0,0 +1,23 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You 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 org.apache.zeppelin.service.assistant;
+
+@FunctionalInterface
+public interface AssistantEventListener {
+ void onEvent(AssistantEventType type, AssistantEventPayload payload);
+}
diff --git a/zeppelin-server/src/main/java/org/apache/zeppelin/service/assistant/AssistantEventPayload.java b/zeppelin-server/src/main/java/org/apache/zeppelin/service/assistant/AssistantEventPayload.java
new file mode 100644
index 0000000000..6a0ad335ff
--- /dev/null
+++ b/zeppelin-server/src/main/java/org/apache/zeppelin/service/assistant/AssistantEventPayload.java
@@ -0,0 +1,121 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You 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 org.apache.zeppelin.service.assistant;
+
+import java.util.Map;
+import jakarta.ws.rs.WebApplicationException;
+
+public interface AssistantEventPayload {
+
+ final class RunStarted implements AssistantEventPayload {
+ final String runId;
+ final String createdAt;
+
+ RunStarted(String runId, String createdAt) {
+ this.runId = runId;
+ this.createdAt = createdAt;
+ }
+ }
+
+ final class RunCompleted implements AssistantEventPayload {
+ final String runId;
+ final Usage usage;
+
+ RunCompleted(String runId, Usage usage) {
+ this.runId = runId;
+ this.usage = usage;
+ }
+ }
+
+ final class RunFailed implements AssistantEventPayload {
+ final String runId;
+ final Error error;
+
+ RunFailed(String runId, Error error) {
+ this.runId = runId;
+ this.error = error;
+ }
+ }
+
+ final class MessageDelta implements AssistantEventPayload {
+ final String messageId;
+ final String delta;
+
+ MessageDelta(String messageId, String delta) {
+ this.messageId = messageId;
+ this.delta = delta;
+ }
+ }
+
+ final class MessageDone implements AssistantEventPayload {
+ final String messageId;
+ final String content;
+
+ MessageDone(String messageId, String content) {
+ this.messageId = messageId;
+ this.content = content;
+ }
+ }
+
+ final class ToolCallStarted implements AssistantEventPayload {
+ final String toolCallId;
+ final String name;
+ final Map<String, Object> arguments;
+
+ ToolCallStarted(String toolCallId, String name, Map<String, Object> arguments) {
+ this.toolCallId = toolCallId;
+ this.name = name;
+ this.arguments = arguments;
+ }
+ }
+
+ final class ToolCallDone implements AssistantEventPayload {
+ final String toolCallId;
+ final ToolResult result;
+
+ ToolCallDone(String toolCallId, ToolResult result) {
+ this.toolCallId = toolCallId;
+ this.result = result;
+ }
+ }
+
+ final class Usage {
+ final int inputTokens;
+ final int outputTokens;
+
+ Usage(int inputTokens, int outputTokens) {
+ this.inputTokens = inputTokens;
+ this.outputTokens = outputTokens;
+ }
+ }
+
+ final class Error {
+ final int status;
+
+ private Error(int status) {
+ this.status = status;
+ }
+
+ public static Error of(Exception e) {
+ int status = e instanceof WebApplicationException
+ ? ((WebApplicationException) e).getResponse().getStatus()
+ : 500;
+ return new Error(status);
+ }
+ }
+}
diff --git a/zeppelin-server/src/main/java/org/apache/zeppelin/service/assistant/AssistantEventType.java b/zeppelin-server/src/main/java/org/apache/zeppelin/service/assistant/AssistantEventType.java
new file mode 100644
index 0000000000..8c0137146a
--- /dev/null
+++ b/zeppelin-server/src/main/java/org/apache/zeppelin/service/assistant/AssistantEventType.java
@@ -0,0 +1,34 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You 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 org.apache.zeppelin.service.assistant;
+
+public enum AssistantEventType {
+ RUN_STARTED("run.started"),
+ RUN_COMPLETED("run.completed"),
+ RUN_FAILED("run.failed"),
+ MESSAGE_DELTA("message.delta"),
+ MESSAGE_DONE("message.done"),
+ TOOL_CALL_STARTED("tool_call.started"),
+ TOOL_CALL_DONE("tool_call.done");
+
+ public final String wireName;
+
+ AssistantEventType(String wireName) {
+ this.wireName = wireName;
+ }
+}
diff --git a/zeppelin-server/src/main/java/org/apache/zeppelin/service/assistant/AssistantImpl.java b/zeppelin-server/src/main/java/org/apache/zeppelin/service/assistant/AssistantImpl.java
new file mode 100644
index 0000000000..9020c36625
--- /dev/null
+++ b/zeppelin-server/src/main/java/org/apache/zeppelin/service/assistant/AssistantImpl.java
@@ -0,0 +1,376 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You 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 org.apache.zeppelin.service.assistant;
+
+import com.google.gson.Gson;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import java.io.IOException;
+import java.time.Instant;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+import java.util.UUID;
+import java.util.stream.IntStream;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Future;
+import jakarta.ws.rs.BadRequestException;
+import jakarta.ws.rs.ClientErrorException;
+import jakarta.ws.rs.ForbiddenException;
+import jakarta.ws.rs.NotFoundException;
+import jakarta.ws.rs.core.Response;
+import org.apache.commons.lang3.StringUtils;
+import org.apache.zeppelin.notebook.AuthorizationService;
+import org.apache.zeppelin.notebook.Notebook;
+import org.apache.zeppelin.rest.exception.NoteNotFoundException;
+import org.apache.zeppelin.service.NotebookService;
+import org.apache.zeppelin.user.AuthenticationInfo;
+
+public class AssistantImpl implements Assistant {
+
+ private static final Logger LOGGER = LoggerFactory.getLogger(AssistantImpl.class);
+ private static final Gson GSON = new Gson();
+ private static final int HISTORY_MESSAGE_LIMIT = 10;
+
+ private static final String INSTRUCTIONS =
+ "You are an AI assistant helping users work with a notebook in Apache Zeppelin.\n"
+ + "Respond in the user's language, and keep your answers concise and clear.\n"
+ + "Format your responses using Markdown.";
+
+ private final ExecutorService assistantExecutor;
+
+ private final Set<String> busyConversations = ConcurrentHashMap.newKeySet();
+
+ private final Notebook notebook;
+ private final ChatModel modelClient;
+ private final ConversationRepository conversationRepository;
+ private final AuthorizationService authorizationService;
+ private final ToolExecutor toolExecutor;
+
+ public AssistantImpl(
+ Notebook notebook,
+ ChatModel modelClient,
+ NotebookService notebookService,
+ AuthorizationService authorizationService,
+ ConversationRepository conversationRepository,
+ ExecutorService assistantExecutor
+ ) {
+ this.assistantExecutor = assistantExecutor;
+ this.authorizationService = authorizationService;
+ this.notebook = notebook;
+ this.modelClient = modelClient;
+ this.conversationRepository = conversationRepository;
+ this.toolExecutor = new ToolExecutor(
+ List.of(
+ new ListParagraphsTool(notebookService)
+ )
+ );
+ }
+
+ @Override
+ public List<Conversation> listConversations(
+ String noteId,
+ Set<String> userAndRoles
+ ) throws IOException {
+ if (!authorizationService.isReader(noteId, userAndRoles)) {
+ throw new ForbiddenException();
+ }
+
+ return notebook.processNote(noteId, note -> {
+ if (note == null) throw new NoteNotFoundException(noteId);
+ return conversationRepository.findAll(noteId);
+ });
+ }
+
+ @Override
+ public Conversation createConversation(
+ String noteId,
+ String title,
+ AuthenticationInfo authInfo,
+ Set<String> userAndRoles
+ ) throws IOException {
+ if (!authorizationService.isReader(noteId, userAndRoles)) throw new ForbiddenException();
+ if (AuthenticationInfo.isAnonymous(authInfo)) throw new ForbiddenException();
+
+ return notebook.processNote(noteId, note -> {
+ if (note == null) throw new NoteNotFoundException(noteId);
+ var conversation = Conversation.create(noteId, title, authInfo.getUser());
+ conversationRepository.create(conversation);
+ return conversation;
+ });
+ }
+
+ @Override
+ public Conversation getConversation(
+ String noteId,
+ String conversationId,
+ Set<String> userAndRoles
+ ) throws IOException {
+ if (!authorizationService.isReader(noteId, userAndRoles)) throw new ForbiddenException();
+
+ return notebook.processNote(noteId, note -> {
+ if (note == null) throw new NoteNotFoundException(noteId);
+ return conversationRepository.find(noteId, conversationId)
+ .orElseThrow(NotFoundException::new);
+ });
+ }
+
+ @Override
+ public Conversation updateTitle(
+ String noteId,
+ String conversationId,
+ String title,
+ String userId,
+ Set<String> userAndRoles
+ ) throws IOException {
+ if (!busyConversations.add(conversationId)) {
+ throw new ClientErrorException("", Response.Status.CONFLICT);
+ }
+ try {
+ var conversation = getConversation(noteId, conversationId, userAndRoles);
+ if (!conversation.isOwner(userId)) throw new ForbiddenException();
+ return notebook.processNote(noteId, note -> {
+ if (note == null) throw new NoteNotFoundException(noteId);
+ conversationRepository.update(conversation, c -> c.setTitle(title));
+ return conversation;
+ });
+ } finally {
+ busyConversations.remove(conversationId);
+ }
+ }
+
+ @Override
+ public void deleteConversation(
+ String noteId,
+ String conversationId,
+ String userId,
+ Set<String> userAndRoles
+ ) throws IOException {
+ if (!busyConversations.add(conversationId)) {
+ throw new ClientErrorException("", Response.Status.CONFLICT);
+ }
+ try {
+ Conversation conversation = getConversation(noteId, conversationId, userAndRoles);
+ if (!conversation.isOwner(userId)) throw new ForbiddenException();
+ notebook.processNote(noteId, note -> {
+ if (note == null) throw new NoteNotFoundException(noteId);
+ conversationRepository.delete(noteId, conversationId);
+ return null;
+ });
+ } finally {
+ busyConversations.remove(conversationId);
+ }
+ }
+
+ @Override
+ public MessagePage listMessages(
+ String noteId,
+ String conversationId,
+ String cursor,
+ int limit,
+ Set<String> userAndRoles
+ ) throws IOException {
+ if (limit <= 0) throw new BadRequestException();
+ List<Message> messages = new ArrayList<>(
+ getConversation(noteId, conversationId, userAndRoles).getMessages()
+ );
+ Collections.reverse(messages);
+
+ int startInclusive = cursor == null ? 0 : IntStream.range(0, messages.size())
+ .filter(i -> messages.get(i).getId().equals(cursor))
+ .findFirst()
+ .orElseThrow(NotFoundException::new) + 1;
+ int pageSize = Math.min(limit, messages.size() - startInclusive);
+ int endExclusive = startInclusive + pageSize;
+
+ List<Message> page = messages.subList(startInclusive, endExclusive);
+
+ boolean hasMore = endExclusive < messages.size();
+ String nextCursor = hasMore ? page.get(page.size() - 1).getId() : null;
+ return new MessagePage(page, nextCursor);
+ }
+
+ @Override
+ public Future<?> sendMessage(
+ String noteId,
+ String conversationId,
+ String userContent,
+ AuthenticationInfo authInfo,
+ Set<String> userAndRoles,
+ AssistantEventListener sink
+ ) {
+ return assistantExecutor.submit(() -> runMessage(
+ noteId, conversationId, userContent, authInfo, userAndRoles, sink)
+ );
+ }
+
+ private void runMessage(
+ String noteId,
+ String conversationId,
+ String userContent,
+ AuthenticationInfo authInfo,
+ Set<String> userAndRoles,
+ AssistantEventListener sink
+ ) {
+ var runId = "run_" + UUID.randomUUID().toString().replace("-", "").substring(0, 16);
+ boolean acquired = false;
+ try {
+ if (StringUtils.isBlank(userContent)) throw new BadRequestException();
+ if (!busyConversations.add(conversationId)) {
+ throw new ClientErrorException("", Response.Status.CONFLICT);
+ }
+ acquired = true;
+
+ var conversation = getConversation(noteId, conversationId, userAndRoles);
+ if (!conversation.isOwner(authInfo.getUser())) throw new ForbiddenException();
+
+ notebook.processNote(noteId, note -> {
+ if (note == null) throw new NoteNotFoundException(noteId);
+ conversationRepository.update(
+ conversation, c -> c.addMessage(Message.user(Message.id(), userContent))
+ );
+ return null;
+ });
+
+ sink.onEvent(
+ AssistantEventType.RUN_STARTED,
+ new AssistantEventPayload.RunStarted(runId, Instant.now().toString())
+ );
+
+ Map<String, Integer> tokens = new HashMap<>();
+ tokens.put("input", 0);
+ tokens.put("output", 0);
+
+ runLoop(noteId, conversation, authInfo, userAndRoles, sink, tokens);
+
+ sink.onEvent(
+ AssistantEventType.RUN_COMPLETED,
+ new AssistantEventPayload.RunCompleted(
+ runId,
+ new AssistantEventPayload.Usage(tokens.get("input"), tokens.get("output"))
+ )
+ );
+ } catch (Exception e) {
+ LOGGER.error("Error during Assistant run", e);
+ sink.onEvent(
+ AssistantEventType.RUN_FAILED,
+ new AssistantEventPayload.RunFailed(runId, AssistantEventPayload.Error.of(e))
+ );
+ } finally {
+ if (acquired) busyConversations.remove(conversationId);
+ }
+ }
+
+ private void runLoop(
+ String noteId,
+ Conversation conversation,
+ AuthenticationInfo authInfo,
+ Set<String> userAndRoles,
+ AssistantEventListener sink,
+ Map<String, Integer> tokens
+ ) throws IOException {
+ for (int iteration = 0; iteration < 10; iteration++) {
+ String assistantId = Message.id();
+ var textBuffer = new StringBuilder();
+ List<ToolCall> toolCalls = new ArrayList<>();
+
+ modelClient.stream(
+ INSTRUCTIONS,
+ conversation.getRecentMessages(HISTORY_MESSAGE_LIMIT),
+ toolExecutor.specs(),
+ event -> {
+ if (event instanceof AssistantEvent.TextDelta) {
+ String delta = ((AssistantEvent.TextDelta) event).delta;
+ textBuffer.append(delta);
+ sink.onEvent(
+ AssistantEventType.MESSAGE_DELTA,
+ new AssistantEventPayload.MessageDelta(assistantId, delta)
+ );
+ } else if (event instanceof AssistantEvent.ToolCall) {
+ AssistantEvent.ToolCall tc = (AssistantEvent.ToolCall) event;
+ toolCalls.add(new ToolCall(tc.id, tc.name, tc.arguments));
+ } else if (event instanceof AssistantEvent.Usage) {
+ AssistantEvent.Usage u = (AssistantEvent.Usage) event;
+ tokens.put("input", tokens.get("input") + u.inputTokens);
+ tokens.put("output", tokens.get("output") + u.outputTokens);
+ }
+ }
+ );
+
+ if (!toolCalls.isEmpty()) {
+ Message.Assistant assistantMsg = Message.assistant(assistantId, textBuffer.toString());
+ toolCalls.forEach(assistantMsg::addToolCall);
+
+ List<Message> turn = new ArrayList<>();
+ turn.add(assistantMsg);
+
+ if (textBuffer.length() > 0) {
+ sink.onEvent(
+ AssistantEventType.MESSAGE_DONE,
+ new AssistantEventPayload.MessageDone(assistantId, textBuffer.toString())
+ );
+ }
+
+ for (ToolCall tc : assistantMsg.getToolCalls()) {
+ sink.onEvent(
+ AssistantEventType.TOOL_CALL_STARTED,
+ new AssistantEventPayload.ToolCallStarted(tc.getId(), tc.getName(), tc.getArguments())
+ );
+ ToolResult result = toolExecutor.callTool(
+ noteId, tc.getName(), tc.getArguments(), authInfo, userAndRoles
+ );
+ tc.setResult(result);
+ turn.add(Message.tool(Message.id(), tc.getId(), GSON.toJson(result)));
+ sink.onEvent(
+ AssistantEventType.TOOL_CALL_DONE,
+ new AssistantEventPayload.ToolCallDone(tc.getId(), result)
+ );
+ }
+
+ notebook.processNote(noteId, note -> {
+ if (note == null) throw new NoteNotFoundException(noteId);
+ conversationRepository.update(conversation, c -> turn.forEach(c::addMessage));
+ return null;
+ });
+ } else {
+ // No tool calls; finish the run.
+ String assistantText = textBuffer.toString();
+ notebook.processNote(noteId, note -> {
+ if (note == null) throw new NoteNotFoundException(noteId);
+ conversationRepository.update(
+ conversation,
+ c -> c.addMessage(Message.assistant(assistantId, assistantText))
+ );
+ return null;
+ });
+ sink.onEvent(
+ AssistantEventType.MESSAGE_DONE,
+ new AssistantEventPayload.MessageDone(assistantId, assistantText)
+ );
+ return;
+ }
+ }
+ throw new IllegalStateException("Tool iteration limit exceeded");
+ }
+
+}
diff --git a/zeppelin-server/src/main/java/org/apache/zeppelin/service/assistant/AssistantModule.java b/zeppelin-server/src/main/java/org/apache/zeppelin/service/assistant/AssistantModule.java
new file mode 100644
index 0000000000..cc0a436102
--- /dev/null
+++ b/zeppelin-server/src/main/java/org/apache/zeppelin/service/assistant/AssistantModule.java
@@ -0,0 +1,83 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You 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 org.apache.zeppelin.service.assistant;
+
+import com.google.common.util.concurrent.ThreadFactoryBuilder;
+
+import java.io.File;
+import java.util.concurrent.ArrayBlockingQueue;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.ThreadPoolExecutor;
+import java.util.concurrent.TimeUnit;
+
+import org.apache.commons.lang3.StringUtils;
+import org.apache.zeppelin.notebook.AuthorizationService;
+import org.apache.zeppelin.notebook.Notebook;
+import org.apache.zeppelin.service.NotebookService;
+
+public class AssistantModule implements AutoCloseable {
+
+ public final Assistant assistant;
+
+ public final OpenAiChatModel model;
+
+ public final ConversationRepository repository;
+
+ private final ExecutorService assistantExecutor;
+
+ public AssistantModule(
+ boolean enabled,
+ String endpoint,
+ String apiKey,
+ String modelName,
+ String conversationDir,
+ Notebook notebook,
+ NotebookService notebookService,
+ AuthorizationService authorizationService
+ ) {
+ if (!enabled || StringUtils.isBlank(apiKey)) {
+ assistant = new DisabledAssistant();
+ model = null;
+ repository = null;
+ assistantExecutor = null;
+ return;
+ }
+ repository = new FileConversationRepository(new File(conversationDir));
+ model = new OpenAiChatModel(endpoint, apiKey, modelName);
+ assistantExecutor = new ThreadPoolExecutor(
+ 10, 10, 0L, TimeUnit.MILLISECONDS, new ArrayBlockingQueue<>(10),
+ new ThreadFactoryBuilder().setNameFormat("assistant-run-%d").setDaemon(true).build()
+ );
+ assistant = new AssistantImpl(
+ notebook, model, notebookService, authorizationService, repository, assistantExecutor
+ );
+ }
+
+ @Override
+ public void close() {
+ try {
+ if (assistantExecutor != null) {
+ assistantExecutor.shutdownNow();
+ }
+ } finally {
+ if (model != null) {
+ model.close();
+ }
+ }
+ }
+}
diff --git a/zeppelin-server/src/main/java/org/apache/zeppelin/service/assistant/ChatModel.java b/zeppelin-server/src/main/java/org/apache/zeppelin/service/assistant/ChatModel.java
new file mode 100644
index 0000000000..7c4ac2134a
--- /dev/null
+++ b/zeppelin-server/src/main/java/org/apache/zeppelin/service/assistant/ChatModel.java
@@ -0,0 +1,31 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You 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 org.apache.zeppelin.service.assistant;
+
+import java.util.List;
+import java.util.function.Consumer;
+
+public interface ChatModel {
+
+ void stream(
+ String systemPrompt,
+ List<Message> history,
+ List<ToolSpec> tools,
+ Consumer<AssistantEvent> consumer
+ );
+}
diff --git a/zeppelin-server/src/main/java/org/apache/zeppelin/service/assistant/Conversation.java b/zeppelin-server/src/main/java/org/apache/zeppelin/service/assistant/Conversation.java
new file mode 100644
index 0000000000..bb156ff7f2
--- /dev/null
+++ b/zeppelin-server/src/main/java/org/apache/zeppelin/service/assistant/Conversation.java
@@ -0,0 +1,88 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You 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 org.apache.zeppelin.service.assistant;
+
+import java.time.Instant;
+import java.time.LocalDateTime;
+import java.time.format.DateTimeFormatter;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.UUID;
+
+public class Conversation {
+
+ // yy-MM-dd HH:mm, e.g. "26-10-02 14:30"
+ private static final DateTimeFormatter TITLE_TIME = DateTimeFormatter.ofPattern("yy-MM-dd HH:mm");
+
+ private String id;
+ private String noteId;
+ private String ownerId;
+ private String title;
+ private String createdAt;
+ private String updatedAt;
+ private List<Message> messages;
+
+ Conversation() {
+ this.messages = new ArrayList<>();
+ }
+
+ public static Conversation create(String noteId, String title, String ownerId) {
+ Conversation c = new Conversation();
+ c.id = "conv_" + UUID.randomUUID().toString().replace("-", "").substring(0, 16);
+ c.noteId = noteId;
+ c.ownerId = ownerId;
+ c.title = title != null ? title : LocalDateTime.now().format(TITLE_TIME);
+ c.createdAt = Instant.now().toString();
+ c.updatedAt = c.createdAt;
+ return c;
+ }
+
+ public String getId() { return id; }
+ public String getNoteId() { return noteId; }
+ public String getOwnerId() { return ownerId; }
+ public String getTitle() { return title; }
+ public String getCreatedAt() { return createdAt; }
+ public String getUpdatedAt() { return updatedAt; }
+ public List<Message> getMessages() { return messages; }
+
+ public List<Message> getRecentMessages(int limit) {
+ if (limit <= 0) throw new IllegalArgumentException();
+ int start = Math.max(0, messages.size() - limit);
+ // Keep tool results together with the assistant message that requested them.
+ while (start > 0 && messages.get(start) instanceof Message.Tool) start--;
+ return messages.subList(start, messages.size());
+ }
+
+ public boolean isOwner(String user) {
+ return ownerId.equals(user);
+ }
+
+ public void setTitle(String title) {
+ this.title = title;
+ touch();
+ }
+
+ public void addMessage(Message message) {
+ messages.add(message);
+ updatedAt = Instant.now().toString();
+ }
+
+ public void touch() {
+ updatedAt = Instant.now().toString();
+ }
+}
diff --git a/zeppelin-server/src/main/java/org/apache/zeppelin/service/assistant/ConversationJsonCodec.java b/zeppelin-server/src/main/java/org/apache/zeppelin/service/assistant/ConversationJsonCodec.java
new file mode 100644
index 0000000000..c4d3776f1a
--- /dev/null
+++ b/zeppelin-server/src/main/java/org/apache/zeppelin/service/assistant/ConversationJsonCodec.java
@@ -0,0 +1,89 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You 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 org.apache.zeppelin.service.assistant;
+
+import com.google.gson.Gson;
+import com.google.gson.GsonBuilder;
+import com.google.gson.JsonDeserializationContext;
+import com.google.gson.JsonDeserializer;
+import com.google.gson.JsonElement;
+import com.google.gson.JsonObject;
+import com.google.gson.JsonParseException;
+import com.google.gson.JsonSerializationContext;
+import com.google.gson.JsonSerializer;
+
+import java.lang.reflect.Type;
+
+/**
+ * JSON wire format for an assistant conversation.
+ */
+final class ConversationJsonCodec {
+
+ private static final Gson GSON = new GsonBuilder()
+ .registerTypeAdapter(Message.class, new MessageAdapter())
+ .create();
+
+ private ConversationJsonCodec() {
+ }
+
+ static String serialize(Conversation conversation) {
+ return GSON.toJson(conversation);
+ }
+
+ static Conversation deserialize(String json) {
+ Conversation conversation = GSON.fromJson(json, Conversation.class);
+ if (conversation == null || conversation.getId() == null || conversation.getNoteId() == null
+ || conversation.getCreatedAt() == null || conversation.getMessages() == null) {
+ throw new JsonParseException("Invalid assistant conversation storage");
+ }
+ return conversation;
+ }
+
+ /**
+ * Routes deserialization to the concrete Message subtype based on {@code role}.
+ */
+ private static class MessageAdapter
+ implements JsonDeserializer<Message>, JsonSerializer<Message> {
+ private static final Gson SUBTYPE = new Gson();
+
+ @Override
+ public Message deserialize(JsonElement json, Type type, JsonDeserializationContext ctx)
+ throws JsonParseException {
+ JsonObject obj = json.getAsJsonObject();
+ if (!obj.has("role")) {
+ throw new JsonParseException("Message missing 'role' field");
+ }
+ Message.Role role = Message.Role.fromValue(obj.get("role").getAsString());
+ switch (role) {
+ case USER:
+ return SUBTYPE.fromJson(json, Message.User.class);
+ case ASSISTANT:
+ return SUBTYPE.fromJson(json, Message.Assistant.class);
+ case TOOL:
+ return SUBTYPE.fromJson(json, Message.Tool.class);
+ default:
+ throw new JsonParseException("Unsupported role: " + role);
+ }
+ }
+
+ @Override
+ public JsonElement serialize(Message src, Type type, JsonSerializationContext ctx) {
+ return SUBTYPE.toJsonTree(src);
+ }
+ }
+}
diff --git a/zeppelin-server/src/main/java/org/apache/zeppelin/service/assistant/ConversationRepository.java b/zeppelin-server/src/main/java/org/apache/zeppelin/service/assistant/ConversationRepository.java
new file mode 100644
index 0000000000..a88db48edb
--- /dev/null
+++ b/zeppelin-server/src/main/java/org/apache/zeppelin/service/assistant/ConversationRepository.java
@@ -0,0 +1,35 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You 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 org.apache.zeppelin.service.assistant;
+
+import java.io.IOException;
+import java.util.List;
+import java.util.Optional;
+import java.util.function.Consumer;
+
+public interface ConversationRepository {
+ List<Conversation> findAll(String noteId) throws IOException;
+
+ Optional<Conversation> find(String noteId, String conversationId) throws IOException;
+
+ void create(Conversation conversation) throws IOException;
+
+ void update(Conversation entity, Consumer<Conversation> change) throws IOException;
+
+ void delete(String noteId, String conversationId) throws IOException;
+}
diff --git a/zeppelin-server/src/main/java/org/apache/zeppelin/service/assistant/DisabledAssistant.java b/zeppelin-server/src/main/java/org/apache/zeppelin/service/assistant/DisabledAssistant.java
new file mode 100644
index 0000000000..bcc46330e3
--- /dev/null
+++ b/zeppelin-server/src/main/java/org/apache/zeppelin/service/assistant/DisabledAssistant.java
@@ -0,0 +1,101 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You 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 org.apache.zeppelin.service.assistant;
+
+import java.io.IOException;
+import java.util.List;
+import java.util.Set;
+import java.util.concurrent.Future;
+
+import org.apache.zeppelin.user.AuthenticationInfo;
+
+import jakarta.ws.rs.ServiceUnavailableException;
+
+public class DisabledAssistant implements Assistant {
+
+ @Override
+ public List<Conversation> listConversations(
+ String noteId,
+ Set<String> userAndRoles
+ ) throws IOException {
+ throw new ServiceUnavailableException();
+ }
+
+ @Override
+ public Conversation createConversation(
+ String noteId,
+ String title,
+ AuthenticationInfo authInfo,
+ Set<String> userAndRoles
+ ) throws IOException {
+ throw new ServiceUnavailableException();
+ }
+
+ @Override
+ public Conversation getConversation(
+ String noteId,
+ String conversationId,
+ Set<String> userAndRoles
+ ) throws IOException {
+ throw new ServiceUnavailableException();
+ }
+
+ @Override
+ public Conversation updateTitle(
+ String noteId,
+ String conversationId,
+ String title,
+ String userId,
+ Set<String> userAndRoles
+ ) throws IOException {
+ throw new ServiceUnavailableException();
+ }
+
+ @Override
+ public void deleteConversation(
+ String noteId,
+ String conversationId,
+ String userId,
+ Set<String> userAndRoles
+ ) throws IOException {
+ throw new ServiceUnavailableException();
+ }
+
+ @Override
+ public MessagePage listMessages(
+ String noteId,
+ String conversationId,
+ String cursor,
+ int limit,
+ Set<String> userAndRoles
+ ) throws IOException {
+ throw new ServiceUnavailableException();
+ }
+
+ @Override
+ public Future<?> sendMessage(
+ String noteId,
+ String conversationId,
+ String userContent,
+ AuthenticationInfo authInfo,
+ Set<String> userAndRoles,
+ AssistantEventListener sink
+ ) {
+ throw new ServiceUnavailableException();
+ }
+}
diff --git a/zeppelin-server/src/main/java/org/apache/zeppelin/service/assistant/FileConversationRepository.java b/zeppelin-server/src/main/java/org/apache/zeppelin/service/assistant/FileConversationRepository.java
new file mode 100644
index 0000000000..b9f371b33e
--- /dev/null
+++ b/zeppelin-server/src/main/java/org/apache/zeppelin/service/assistant/FileConversationRepository.java
@@ -0,0 +1,102 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You 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 org.apache.zeppelin.service.assistant;
+
+import java.io.File;
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.NoSuchFileException;
+import java.time.Instant;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.Comparator;
+import java.util.List;
+import java.util.Optional;
+import java.util.function.Consumer;
+import org.apache.zeppelin.util.FileUtils;
+
+public final class FileConversationRepository implements ConversationRepository {
+ private final File directory;
+
+ public FileConversationRepository(File directory) {
+ this.directory = directory;
+ }
+
+ @Override
+ public List<Conversation> findAll(String noteId) throws IOException {
+ File noteDirectory = noteDirectory(noteId);
+ if (!noteDirectory.exists()) return Collections.emptyList();
+ File[] files = noteDirectory.listFiles((dir, name) -> name.endsWith(".json"));
+ if (files == null) throw new IOException();
+
+ List<Conversation> conversations = new ArrayList<>();
+ for (File file : files) read(file).ifPresent(conversations::add);
+ conversations.sort(Comparator.comparing(c -> Instant.parse(c.getCreatedAt())));
+ return Collections.unmodifiableList(conversations);
+ }
+
+ @Override
+ public Optional<Conversation> find(String noteId, String conversationId) throws IOException {
+ return read(file(noteId, conversationId));
+ }
+
+ @Override
+ public void create(Conversation conversation) throws IOException {
+ File file = file(conversation.getNoteId(), conversation.getId());
+ if (file.exists()) throw new IllegalStateException();
+ commit(file, conversation);
+ }
+
+ @Override
+ public void update(Conversation entity, Consumer<Conversation> change) throws IOException {
+ File file = file(entity.getNoteId(), entity.getId());
+ if (!file.exists()) throw new IOException();
+ change.accept(entity);
+ commit(file, entity);
+ }
+
+ @Override
+ public void delete(String noteId, String conversationId) throws IOException {
+ Files.delete(file(noteId, conversationId).toPath());
+ }
+
+ private File noteDirectory(String noteId) throws IOException {
+ File noteDirectory = new File(directory, noteId).getCanonicalFile();
+ if (!directory.getCanonicalFile().equals(noteDirectory.getParentFile())) throw new IOException();
+ return noteDirectory;
+ }
+
+ private File file(String noteId, String conversationId) throws IOException {
+ File noteDirectory = noteDirectory(noteId);
+ File file = new File(noteDirectory, conversationId + ".json").getCanonicalFile();
+ if (!noteDirectory.equals(file.getParentFile())) throw new IOException();
+ return file;
+ }
+
+ private static Optional<Conversation> read(File file) throws IOException {
+ try {
+ return Optional.of(ConversationJsonCodec.deserialize(Files.readString(file.toPath())));
+ } catch (NoSuchFileException e) {
+ return Optional.empty();
+ }
+ }
+
+ private static void commit(File file, Conversation conversation) throws IOException {
+ FileUtils.atomicWriteToFile(ConversationJsonCodec.serialize(conversation), file);
+ }
+}
diff --git a/zeppelin-server/src/main/java/org/apache/zeppelin/service/assistant/ListParagraphsTool.java b/zeppelin-server/src/main/java/org/apache/zeppelin/service/assistant/ListParagraphsTool.java
new file mode 100644
index 0000000000..9104ae45f3
--- /dev/null
+++ b/zeppelin-server/src/main/java/org/apache/zeppelin/service/assistant/ListParagraphsTool.java
@@ -0,0 +1,91 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You 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 org.apache.zeppelin.service.assistant;
+
+import java.io.IOException;
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+import org.apache.commons.lang3.StringUtils;
+import org.apache.zeppelin.user.AuthenticationInfo;
+
+import org.apache.zeppelin.notebook.Paragraph;
+import org.apache.zeppelin.service.NotebookService;
+import org.apache.zeppelin.service.ServiceContext;
+import org.apache.zeppelin.service.SimpleServiceCallback;
+
+public class ListParagraphsTool implements Tool {
+
+ private final NotebookService notebookService;
+
+ public ListParagraphsTool(NotebookService notebookService) {
+ this.notebookService = notebookService;
+ }
+
+ @Override
+ public String name() {
+ return "list_paragraphs";
+ }
+
+ @Override
+ public String description() {
+ return "List notebook paragraphs.";
+ }
+
+ @Override
+ public Map<String, Object> parameters() {
+ return Map.of("type", "object", "properties", Map.of());
+ }
+
+ @Override
+ public List<Map<String, Object>> call(
+ String noteId,
+ Map<String, Object> args,
+ AuthenticationInfo authInfo,
+ Set<String> userAndRoles
+ ) throws IOException {
+ ServiceContext context = new ServiceContext(authInfo, userAndRoles);
+ return notebookService.getNote(noteId, context, callback(), note -> {
+ List<Map<String, Object>> result = new ArrayList<>();
+ for (int i = 0; i < note.getParagraphCount(); i++) {
+ Paragraph p = note.getParagraph(i);
+ Map<String, Object> info = new HashMap<>();
+ info.put("id", p.getId());
+ info.put("title", p.getTitle());
+ info.put("text", StringUtils.abbreviate(p.getText(), 500));
+ info.put("index", i);
+ result.add(info);
+ }
+ return result;
+ });
+ }
+
+ private static <T> SimpleServiceCallback<T> callback() {
+ return new SimpleServiceCallback<T>() {
+ @Override
+ public void onFailure(Exception ex, ServiceContext context) throws IOException {
+ if (ex instanceof RuntimeException) {
+ throw (RuntimeException) ex;
+ }
+ throw new IOException(ex);
+ }
+ };
+ }
+}
diff --git a/zeppelin-server/src/main/java/org/apache/zeppelin/service/assistant/Message.java b/zeppelin-server/src/main/java/org/apache/zeppelin/service/assistant/Message.java
new file mode 100644
index 0000000000..b0e1b3d4cd
--- /dev/null
+++ b/zeppelin-server/src/main/java/org/apache/zeppelin/service/assistant/Message.java
@@ -0,0 +1,156 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You 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 org.apache.zeppelin.service.assistant;
+
+import com.google.gson.annotations.SerializedName;
+
+import java.time.Instant;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.UUID;
+
+public abstract class Message {
+
+ public enum Role {
+ @SerializedName("system") SYSTEM,
+ @SerializedName("user") USER,
+ @SerializedName("assistant") ASSISTANT,
+ @SerializedName("tool") TOOL;
+
+ public static Role fromValue(String value) {
+ for (Role r : values()) {
+ if (r.name().equalsIgnoreCase(value)) {
+ return r;
+ }
+ }
+ throw new IllegalArgumentException();
+ }
+ }
+
+ private String id;
+ private String createdAt;
+
+ private Message() {}
+
+ Message(String id, String createdAt) {
+ this.id = id;
+ this.createdAt = createdAt;
+ }
+
+ public String getId() {
+ return id;
+ }
+
+ public String getCreatedAt() { return createdAt; }
+
+ public abstract Role getRole();
+
+ public static String id() {
+ return "msg_" + UUID.randomUUID().toString().replace("-", "").substring(0, 16);
+ }
+
+ public static Message.User user(String id, String content) {
+ return new Message.User(id, content, Instant.now().toString());
+ }
+
+ public static Message.Assistant assistant(String id, String content) {
+ return new Message.Assistant(id, content, Instant.now().toString());
+ }
+
+ public static Message.Tool tool(String id, String toolCallId, String content) {
+ return new Message.Tool(id, toolCallId, content, Instant.now().toString());
+ }
+
+ public static class User extends Message {
+ private Role role = Role.USER;
+ private String content;
+
+ private User() {}
+
+ User(String id, String content, String createdAt) {
+ super(id, createdAt);
+ this.content = content;
+ }
+
+ @Override
+ public Role getRole() {
+ return role;
+ }
+
+ public String getContent() {
+ return content;
+ }
+ }
+
+ public static class Assistant extends Message {
+ private Role role = Role.ASSISTANT;
+ private String content;
+ private List<ToolCall> toolCalls = new ArrayList<>();
+
+ private Assistant() {}
+
+ Assistant(String id, String content, String createdAt) {
+ super(id, createdAt);
+ this.content = content;
+ }
+
+ @Override
+ public Role getRole() {
+ return role;
+ }
+
+ public String getContent() {
+ return content;
+ }
+
+ public List<ToolCall> getToolCalls() {
+ return toolCalls;
+ }
+
+ public void addToolCall(ToolCall toolCall) {
+ toolCalls.add(toolCall);
+ }
+ }
+
+ public static class Tool extends Message {
+ private Role role = Role.TOOL;
+ private String toolCallId;
+ private String content;
+
+ private Tool() {}
+
+ Tool(String id, String toolCallId, String content, String createdAt) {
+ super(id, createdAt);
+ this.toolCallId = toolCallId;
+ this.content = content;
+ }
+
+ @Override
+ public Role getRole() {
+ return role;
+ }
+
+ public String getToolCallId() {
+ return toolCallId;
+ }
+
+ public String getContent() {
+ return content;
+ }
+ }
+}
diff --git a/zeppelin-server/src/main/java/org/apache/zeppelin/service/assistant/MessagePage.java b/zeppelin-server/src/main/java/org/apache/zeppelin/service/assistant/MessagePage.java
new file mode 100644
index 0000000000..6fee457130
--- /dev/null
+++ b/zeppelin-server/src/main/java/org/apache/zeppelin/service/assistant/MessagePage.java
@@ -0,0 +1,30 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You 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 org.apache.zeppelin.service.assistant;
+
+import java.util.List;
+
+public final class MessagePage {
+ public final List<Message> messages;
+ public final String cursor;
+
+ public MessagePage(List<Message> messages, String cursor) {
+ this.messages = messages;
+ this.cursor = cursor;
+ }
+}
diff --git a/zeppelin-server/src/main/java/org/apache/zeppelin/service/assistant/OpenAiChatModel.java b/zeppelin-server/src/main/java/org/apache/zeppelin/service/assistant/OpenAiChatModel.java
new file mode 100644
index 0000000000..88ab7a27db
--- /dev/null
+++ b/zeppelin-server/src/main/java/org/apache/zeppelin/service/assistant/OpenAiChatModel.java
@@ -0,0 +1,201 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You 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 org.apache.zeppelin.service.assistant;
+
+import com.google.gson.Gson;
+import com.openai.client.OpenAIClient;
+import com.openai.client.okhttp.OpenAIOkHttpClient;
+import com.openai.core.JsonValue;
+import com.openai.core.http.StreamResponse;
+import com.openai.models.responses.EasyInputMessage;
+import com.openai.models.responses.FunctionTool;
+import com.openai.models.responses.ResponseCreateParams;
+import com.openai.models.responses.ResponseFunctionToolCall;
+import com.openai.models.responses.ResponseInputItem;
+import com.openai.models.responses.ResponseStreamEvent;
+
+import java.time.Duration;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+import java.util.concurrent.CancellationException;
+import java.util.function.Consumer;
+
+/**
+ * {@link ChatModel} backed by the official {@code com.openai:openai-java} SDK,
+ */
+public class OpenAiChatModel implements ChatModel, AutoCloseable {
+
+ private static final Gson GSON = new Gson();
+
+ private final String baseUrl;
+ private final String apiKey;
+ private final String model;
+ private OpenAIClient cachedClient;
+ private boolean closed;
+
+ public OpenAiChatModel(String baseUrl, String apiKey, String model) {
+ this.baseUrl = baseUrl;
+ this.apiKey = apiKey;
+ this.model = model;
+ }
+
+ private synchronized OpenAIClient client() {
+ if (closed) throw new CancellationException();
+ if (cachedClient == null) {
+ cachedClient = OpenAIOkHttpClient.builder()
+ .baseUrl(baseUrl)
+ .apiKey(apiKey)
+ .timeout(Duration.ofMinutes(1))
+ .build();
+ }
+ return cachedClient;
+ }
+
+ @Override
+ public synchronized void close() {
+ if (closed) return;
+ closed = true;
+ if (cachedClient != null) {
+ cachedClient.close();
+ }
+ }
+
+ @Override
+ public void stream(
+ String instruction,
+ List<Message> history,
+ List<ToolSpec> tools,
+ Consumer<AssistantEvent> consumer
+ ) {
+ List<ResponseInputItem> input = new ArrayList<>();
+ for (Message m : history) {
+ addHistoryItems(input, m);
+ }
+
+ ResponseCreateParams.Builder params = ResponseCreateParams.builder()
+ .model(model)
+ .instructions(instruction)
+ .store(false)
+ .inputOfResponse(input);
+
+ for (ToolSpec t : tools) {
+ params.addTool(FunctionTool.builder()
+ .name(t.name)
+ .description(t.description)
+ .parameters(toParameters(t.parameters))
+ .strict(false)
+ .build());
+ }
+
+ boolean[] completed = {false};
+ try (
+ StreamResponse<ResponseStreamEvent> stream = client()
+ .responses()
+ .createStreaming(params.build())
+ ) {
+ stream.stream().forEach(event -> {
+ if (event.completed().isPresent()) completed[0] = true;
+ handleEvent(event, consumer);
+ });
+ }
+ // A stream that ends without a completed response
+ if (!completed[0]) {
+ throw new IllegalStateException();
+ }
+ }
+
+ private static FunctionTool.Parameters toParameters(Map<String, Object> schema) {
+ FunctionTool.Parameters.Builder builder = FunctionTool.Parameters.builder();
+ for (Map.Entry<String, Object> e : schema.entrySet()) {
+ builder.putAdditionalProperty(e.getKey(), JsonValue.from(e.getValue()));
+ }
+ return builder.build();
+ }
+
+ // TODO(seung-00) replace with pattern matching (Java 16+)
+ private void addHistoryItems(List<ResponseInputItem> input, Message m) {
+ if (m instanceof Message.User) {
+ String content = ((Message.User) m).getContent();
+ if (content != null) {
+ input.add(easyMessage(EasyInputMessage.Role.USER, content));
+ }
+ } else if (m instanceof Message.Assistant) {
+ Message.Assistant assistant = (Message.Assistant) m;
+ if (assistant.getContent() != null && !assistant.getContent().isEmpty()) {
+ input.add(easyMessage(EasyInputMessage.Role.ASSISTANT, assistant.getContent()));
+ }
+ for (ToolCall tc : assistant.getToolCalls()) {
+ input.add(ResponseInputItem.ofFunctionCall(ResponseFunctionToolCall.builder()
+ .callId(tc.getId())
+ .name(tc.getName())
+ .arguments(GSON.toJson(tc.getArguments()))
+ .build()));
+ }
+ } else if (m instanceof Message.Tool) {
+ Message.Tool tool = (Message.Tool) m;
+ input.add(ResponseInputItem.ofFunctionCallOutput(
+ ResponseInputItem.FunctionCallOutput.builder()
+ .callId(tool.getToolCallId())
+ .output(tool.getContent() != null ? tool.getContent() : "")
+ .build()
+ )
+ );
+ }
+ }
+
+ private static ResponseInputItem easyMessage(EasyInputMessage.Role role, String content) {
+ return ResponseInputItem.ofEasyInputMessage(
+ EasyInputMessage.builder().role(role).content(content).build());
+ }
+
+ private void handleEvent(
+ ResponseStreamEvent event,
+ Consumer<AssistantEvent> consumer
+ ) {
+ // A failure event ends the stream without a completion; surface it instead of silently
+ // saving an empty/partial reply and reporting success.
+ event.error().ifPresent(e -> {
+ throw new IllegalStateException("OpenAI stream error: " + e.message());
+ });
+ event.failed().ifPresent(f -> {
+ throw new IllegalStateException("OpenAI response failed");
+ });
+ event.incomplete().ifPresent(i -> {
+ throw new IllegalStateException("OpenAI response incomplete");
+ });
+
+ event.outputTextDelta().ifPresent(
+ d -> consumer.accept(new AssistantEvent.TextDelta(d.delta())));
+
+ // A refusal is a real reply the user must see; stream it as text so it is delivered and saved.
+ event.refusalDelta().ifPresent(
+ r -> consumer.accept(new AssistantEvent.TextDelta(r.delta())));
+
+ event.outputItemDone().flatMap(done -> done.item().functionCall())
+ .ifPresent(call ->
+ consumer.accept(
+ new AssistantEvent.ToolCall(call.callId(), call.name(), call.arguments())
+ ));
+
+ event.completed().flatMap(done -> done.response().usage())
+ .ifPresent(u -> consumer.accept(
+ new AssistantEvent.Usage((int) u.inputTokens(), (int) u.outputTokens())
+ ));
+ }
+}
diff --git a/zeppelin-server/src/main/java/org/apache/zeppelin/service/assistant/Tool.java b/zeppelin-server/src/main/java/org/apache/zeppelin/service/assistant/Tool.java
new file mode 100644
index 0000000000..cb390eb416
--- /dev/null
+++ b/zeppelin-server/src/main/java/org/apache/zeppelin/service/assistant/Tool.java
@@ -0,0 +1,40 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You 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 org.apache.zeppelin.service.assistant;
+
+import java.io.IOException;
+import java.util.Map;
+import java.util.Set;
+import org.apache.zeppelin.user.AuthenticationInfo;
+
+public interface Tool {
+
+ String name();
+
+ String description();
+
+ /** JSON Schema of the tool's arguments. */
+ Map<String, Object> parameters();
+
+ Object call(
+ String noteId,
+ Map<String, Object> args,
+ AuthenticationInfo authInfo,
+ Set<String> userAndRoles
+ ) throws IOException;
+}
diff --git a/zeppelin-server/src/main/java/org/apache/zeppelin/service/assistant/ToolCall.java b/zeppelin-server/src/main/java/org/apache/zeppelin/service/assistant/ToolCall.java
new file mode 100644
index 0000000000..dd5c404ac4
--- /dev/null
+++ b/zeppelin-server/src/main/java/org/apache/zeppelin/service/assistant/ToolCall.java
@@ -0,0 +1,43 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You 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 org.apache.zeppelin.service.assistant;
+
+import java.util.Map;
+
+public class ToolCall {
+
+ private String id;
+ private String name;
+ private Map<String, Object> arguments;
+ private ToolResult result;
+
+ private ToolCall() {}
+
+ public ToolCall(String id, String name, Map<String, Object> arguments) {
+ this.id = id;
+ this.name = name;
+ this.arguments = arguments;
+ }
+
+ public String getId() { return id; }
+ public String getName() { return name; }
+ public Map<String, Object> getArguments() { return arguments; }
+ public ToolResult getResult() { return result; }
+
+ public void setResult(ToolResult result) { this.result = result; }
+}
diff --git a/zeppelin-server/src/main/java/org/apache/zeppelin/service/assistant/ToolExecutor.java b/zeppelin-server/src/main/java/org/apache/zeppelin/service/assistant/ToolExecutor.java
new file mode 100644
index 0000000000..c77db4977f
--- /dev/null
+++ b/zeppelin-server/src/main/java/org/apache/zeppelin/service/assistant/ToolExecutor.java
@@ -0,0 +1,61 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You 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 org.apache.zeppelin.service.assistant;
+
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+import java.util.stream.Collectors;
+import org.apache.zeppelin.user.AuthenticationInfo;
+public class ToolExecutor {
+
+ private final Map<String, Tool> byName;
+
+ public ToolExecutor(List<Tool> tools) {
+ Map<String, Tool> map = new LinkedHashMap<>();
+ for (Tool t : tools) {
+ map.put(t.name(), t);
+ }
+ this.byName = map;
+ }
+
+ public List<ToolSpec> specs() {
+ return byName.values().stream()
+ .map(t -> new ToolSpec(t.name(), t.description(), t.parameters()))
+ .collect(Collectors.toList());
+ }
+
+ public ToolResult callTool(
+ String noteId,
+ String name,
+ Map<String, Object> args,
+ AuthenticationInfo authInfo,
+ Set<String> userAndRoles
+ ) {
+ Tool tool = byName.get(name);
+
+ if (tool == null) return new ToolResult(null, "Unknown tool: " + name);
+
+ try {
+ return new ToolResult(tool.call(noteId, args, authInfo, userAndRoles), null);
+ } catch (Exception ex) {
+ return new ToolResult(null, String.valueOf(ex.getMessage()));
+ }
+ }
+}
diff --git a/zeppelin-server/src/main/java/org/apache/zeppelin/service/assistant/ToolResult.java b/zeppelin-server/src/main/java/org/apache/zeppelin/service/assistant/ToolResult.java
new file mode 100644
index 0000000000..7e76c93dcb
--- /dev/null
+++ b/zeppelin-server/src/main/java/org/apache/zeppelin/service/assistant/ToolResult.java
@@ -0,0 +1,28 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You 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 org.apache.zeppelin.service.assistant;
+
+public final class ToolResult {
+ public final Object value;
+ public final String error;
+
+ public ToolResult(Object value, String error) {
+ this.value = value;
+ this.error = error;
+ }
+}
diff --git a/zeppelin-server/src/main/java/org/apache/zeppelin/service/assistant/ToolSpec.java b/zeppelin-server/src/main/java/org/apache/zeppelin/service/assistant/ToolSpec.java
new file mode 100644
index 0000000000..f5f0a419e0
--- /dev/null
+++ b/zeppelin-server/src/main/java/org/apache/zeppelin/service/assistant/ToolSpec.java
@@ -0,0 +1,32 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You 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 org.apache.zeppelin.service.assistant;
+
+import java.util.Map;
+
+public final class ToolSpec {
+ public final String name;
+ public final String description;
+ public final Map<String, Object> parameters;
+
+ public ToolSpec(String name, String description, Map<String, Object> parameters) {
+ this.name = name;
+ this.description = description;
+ this.parameters = parameters;
+ }
+}
diff --git a/zeppelin-server/src/main/java/org/apache/zeppelin/socket/NotebookServer.java b/zeppelin-server/src/main/java/org/apache/zeppelin/socket/NotebookServer.java
index ba5bffc76e..75eb183e9b 100644
--- a/zeppelin-server/src/main/java/org/apache/zeppelin/socket/NotebookServer.java
+++ b/zeppelin-server/src/main/java/org/apache/zeppelin/socket/NotebookServer.java
@@ -91,6 +91,8 @@ import org.apache.zeppelin.scheduler.Job;
import org.apache.zeppelin.scheduler.Job.Status;
import org.apache.zeppelin.service.JobManagerService;
import org.apache.zeppelin.service.NotebookService;
+import org.apache.zeppelin.service.assistant.AssistantEventListener;
+import org.apache.zeppelin.service.assistant.Assistant;
import org.apache.zeppelin.service.ServiceContext;
import org.apache.zeppelin.service.SimpleServiceCallback;
import org.apache.zeppelin.service.exception.JobManagerForbiddenException;
@@ -162,6 +164,7 @@ public class NotebookServer implements AngularObjectRegistryListener,
private Provider<NotebookService> notebookServiceProvider;
private AuthorizationService authorizationService;
private Provider<JobManagerService> jobManagerServiceProvider;
+ private Provider<Assistant> assistantProvider;
public NotebookServer() {
NotebookServer.self.set(this);
@@ -220,6 +223,16 @@ public class NotebookServer implements AngularObjectRegistryListener,
this.jobManagerServiceProvider = jobManagerServiceProvider;
}
+ @Inject
+ public void setAssistant(
+ Provider<Assistant> assistantProvider) {
+ this.assistantProvider = assistantProvider;
+ }
+
+ public Assistant getAssistant() {
+ return assistantProvider.get();
+ }
+
public Notebook getNotebook() {
return notebookProvider.get();
}
@@ -568,6 +581,9 @@ public class NotebookServer implements AngularObjectRegistryListener,
case PATCH_PARAGRAPH:
patchParagraph(conn, context, receivedMessage);
break;
+ case ASSISTANT_SEND_MESSAGE:
+ sendAssistantMessage(conn, context, receivedMessage);
+ break;
default:
break;
}
@@ -1245,6 +1261,34 @@ public class NotebookServer implements AngularObjectRegistryListener,
});
}
+ private void sendAssistantMessage(
+ NotebookSocket conn,
+ ServiceContext context,
+ Message fromMessage
+ ) {
+ String noteId = (String) fromMessage.get("noteId");
+ String conversationId = (String) fromMessage.get("conversationId");
+ String content = (String) fromMessage.get("content");
+ AssistantEventListener sink = (type, payload) -> {
+ try {
+ conn.send(serializeMessage(new Message(OP.ASSISTANT_EVENT)
+ .put("conversationId", conversationId)
+ .put("type", type.wireName)
+ .put("payload", payload)));
+ } catch (IOException e) {
+ LOGGER.warn("Failed to send assistant event to connection", e);
+ }
+ };
+ getAssistant().sendMessage(
+ noteId,
+ conversationId,
+ content,
+ context.getAutheInfo(),
+ context.getUserAndRoles(),
+ sink
+ );
+ }
+
private void cloneNote(NotebookSocket conn,
ServiceContext context,
Message fromMessage) throws IOException {
diff --git a/zeppelin-server/src/test/java/org/apache/zeppelin/service/assistant/AssistantEventTest.java b/zeppelin-server/src/test/java/org/apache/zeppelin/service/assistant/AssistantEventTest.java
new file mode 100644
index 0000000000..3d8a25c40b
--- /dev/null
+++ b/zeppelin-server/src/test/java/org/apache/zeppelin/service/assistant/AssistantEventTest.java
@@ -0,0 +1,45 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You 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 org.apache.zeppelin.service.assistant;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+import com.google.gson.JsonParseException;
+import java.util.Map;
+import org.junit.jupiter.api.Test;
+
+class AssistantEventTest {
+ @Test
+ void parsesArguments() {
+ var call = new AssistantEvent.ToolCall(
+ "call",
+ "tool",
+ "{\"name\":\"value\",\"options\":{\"enabled\":true}}"
+ );
+ assertEquals(Map.of("name", "value", "options", Map.of("enabled", true)), call.arguments);
+
+ for (String arguments : new String[]{null, "", " \t", "{}"}) {
+ assertTrue(new AssistantEvent.ToolCall("call", "tool", arguments).arguments.isEmpty());
+ }
+
+ assertThrows(
+ JsonParseException.class,
+ () -> new AssistantEvent.ToolCall("call", "tool", "{")
+ );
+ }
+}
diff --git a/zeppelin-server/src/test/java/org/apache/zeppelin/service/assistant/AssistantTest.java b/zeppelin-server/src/test/java/org/apache/zeppelin/service/assistant/AssistantTest.java
new file mode 100644
index 0000000000..5befd6019f
--- /dev/null
+++ b/zeppelin-server/src/test/java/org/apache/zeppelin/service/assistant/AssistantTest.java
@@ -0,0 +1,456 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You 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 org.apache.zeppelin.service.assistant;
+
+import static org.junit.jupiter.api.Assertions.*;
+import static org.mockito.ArgumentMatchers.*;
+import static org.mockito.Mockito.*;
+
+import java.io.File;
+import java.io.IOException;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Optional;
+import java.util.Set;
+import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.TimeUnit;
+import java.util.function.Consumer;
+import jakarta.ws.rs.BadRequestException;
+import jakarta.ws.rs.ClientErrorException;
+import jakarta.ws.rs.ForbiddenException;
+import jakarta.ws.rs.ServiceUnavailableException;
+import org.apache.zeppelin.notebook.AuthorizationService;
+import org.apache.zeppelin.notebook.Note;
+import org.apache.zeppelin.notebook.Notebook;
+import org.apache.zeppelin.notebook.Notebook.NoteProcessor;
+import org.apache.zeppelin.rest.exception.NoteNotFoundException;
+import org.apache.zeppelin.service.NotebookService;
+import org.apache.zeppelin.user.AuthenticationInfo;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
+
+class AssistantTest {
+
+ private final ExecutorService executor = Executors.newFixedThreadPool(2);
+
+ @AfterEach
+ void tearDown() {
+ executor.shutdownNow();
+ }
+
+ private final AuthenticationInfo authInfo = new AuthenticationInfo("holden");
+ private final AuthenticationInfo otherAuthInfo = new AuthenticationInfo("phoebe");
+ private final Set<String> userAndRoles = Set.of("user");
+
+ @Test
+ void rejectsUnavailable() {
+ var sut = new DisabledAssistant();
+
+ assertThrows(ServiceUnavailableException.class,
+ () -> sut.listConversations("noteId", userAndRoles));
+ assertThrows(ServiceUnavailableException.class,
+ () -> sut.createConversation("noteId", "title", authInfo, userAndRoles));
+ assertThrows(ServiceUnavailableException.class,
+ () -> sut.getConversation("noteId", "conv", userAndRoles));
+ assertThrows(ServiceUnavailableException.class,
+ () -> sut.updateTitle("noteId", "conv", "title", authInfo.getUser(), userAndRoles));
+ assertThrows(ServiceUnavailableException.class,
+ () -> sut.deleteConversation("noteId", "conv", authInfo.getUser(), userAndRoles));
+ assertThrows(ServiceUnavailableException.class,
+ () -> sut.listMessages("noteId", "conv", null, 10, userAndRoles));
+ assertThrows(ServiceUnavailableException.class,
+ () -> sut.sendMessage("noteId", "conv", "hi", authInfo, userAndRoles,
+ (type, payload) -> fail("Disabled service must not emit events")));
+ }
+
+ @Test
+ void rejectsNonReaders() {
+ var authorization = mock(AuthorizationService.class);
+ when(authorization.isReader("noteId", userAndRoles)).thenReturn(false);
+
+ var sut = new AssistantImpl(
+ null, mock(ChatModel.class), null, authorization, null, executor
+ );
+
+ assertThrows(ForbiddenException.class, () -> sut.listConversations("noteId", userAndRoles));
+ assertThrows(ForbiddenException.class,
+ () -> sut.createConversation("noteId", "title", authInfo, userAndRoles)
+ );
+ assertThrows(ForbiddenException.class,
+ () -> sut.deleteConversation("noteId", "conv", authInfo.getUser(), userAndRoles)
+ );
+ }
+
+ @Test
+ void rejectsAnonymousCreate() {
+ var authorization = mock(AuthorizationService.class);
+ when(authorization.isReader("noteId", userAndRoles)).thenReturn(true);
+ var sut = new AssistantImpl(
+ null, mock(ChatModel.class), null, authorization, null, executor);
+
+ assertThrows(
+ ForbiddenException.class,
+ () -> sut.createConversation("noteId", "title", AuthenticationInfo.ANONYMOUS, userAndRoles)
+ );
+ }
+
+ @Test
+ void createsConversation(@TempDir File tempDir) throws Exception {
+ var notebook = mock(Notebook.class);
+ when(notebook.processNote(eq("noteId"), any()))
+ .thenAnswer(invocation -> ((NoteProcessor<?>) invocation.getArgument(1)).process(new Note()));
+
+ var authorization = mock(AuthorizationService.class);
+ when(authorization.isReader("noteId", userAndRoles)).thenReturn(true);
+
+ var repository = new FileConversationRepository(tempDir);
+ var sut = new AssistantImpl(
+ notebook, mock(ChatModel.class), null, authorization, repository, executor
+ );
+
+ var created = sut.createConversation("noteId", "test", authInfo, userAndRoles);
+ assertTrue(new File(tempDir, "noteId" + "/" + created.getId() + ".json").isFile());
+ }
+
+ @Test
+ void rejectsMissingNote() throws Exception {
+ var notebook = mock(Notebook.class);
+ when(notebook.processNote(eq("noteId"), any()))
+ .thenAnswer(invocation -> ((NoteProcessor<?>) invocation.getArgument(1)).process(null));
+ var authorization = mock(AuthorizationService.class);
+ when(authorization.isReader("noteId", userAndRoles)).thenReturn(true);
+ var repository = mock(ConversationRepository.class);
+ var sut = new AssistantImpl(
+ notebook, mock(ChatModel.class), null, authorization, repository, executor
+ );
+
+ assertThrows(
+ NoteNotFoundException.class,
+ () -> sut.createConversation("noteId", "test", authInfo, userAndRoles)
+ );
+ verifyNoInteractions(repository);
+ }
+
+ @Test
+ void releasesSlotAfterFailure() throws Exception {
+ var notebook = mock(Notebook.class);
+ when(notebook.processNote(eq("noteId"), any()))
+ .thenAnswer(invocation -> ((NoteProcessor<?>) invocation.getArgument(1)).process(new Note()));
+ var authorization = mock(AuthorizationService.class);
+ when(authorization.isReader("noteId", userAndRoles)).thenReturn(true);
+
+ var conversation = Conversation.create("noteId", "test", authInfo.getUser());
+ var repository = mock(ConversationRepository.class);
+ when(repository.find("noteId", conversation.getId()))
+ .thenReturn(Optional.of(conversation));
+ var sut = new AssistantImpl(
+ notebook, mock(ChatModel.class), null, authorization, repository, executor
+ );
+
+ doThrow(new IOException()).when(repository).update(any(), any());
+ assertThrows(
+ IOException.class,
+ () -> sut.updateTitle("noteId", conversation.getId(), "discarded", authInfo.getUser(), userAndRoles)
+ );
+
+ doAnswer(invocation -> {
+ invocation.<Consumer<Conversation>>getArgument(1).accept(invocation.getArgument(0));
+ return null;
+ }).when(repository).update(any(), any());
+ var updated = sut.updateTitle(
+ "noteId", conversation.getId(), "after-failure", authInfo.getUser(), userAndRoles
+ );
+ assertEquals("after-failure", updated.getTitle());
+ }
+
+ @Test
+ void enforcesOwnership() throws Exception {
+ var notebook = mock(Notebook.class);
+ when(notebook.processNote(eq("noteId"), any()))
+ .thenAnswer(invocation -> ((NoteProcessor<?>) invocation.getArgument(1))
+ .process(new Note()));
+ var authorization = mock(AuthorizationService.class);
+ when(authorization.isReader("noteId", userAndRoles)).thenReturn(true);
+
+ var conversation = Conversation.create("noteId", "test", authInfo.getUser());
+ var repository = mock(ConversationRepository.class);
+ when(repository.find("noteId", conversation.getId())).thenReturn(Optional.of(conversation));
+ when(repository.findAll("noteId")).thenReturn(List.of(conversation));
+ var sut = new AssistantImpl(
+ notebook, mock(ChatModel.class), null, authorization, repository, executor
+ );
+
+ // A different reader can read.
+ assertEquals(1, sut.listConversations("noteId", userAndRoles).size());
+ assertNotNull(sut.getConversation("noteId", conversation.getId(), userAndRoles));
+ assertNotNull(sut.listMessages("noteId", conversation.getId(), null, 10, userAndRoles));
+
+ // But cannot mutate.
+ assertThrows(ForbiddenException.class,
+ () -> sut.deleteConversation("noteId", conversation.getId(), otherAuthInfo.getUser(), userAndRoles)
+ );
+ assertThrows(ForbiddenException.class,
+ () -> sut.updateTitle("noteId", conversation.getId(), "x", otherAuthInfo.getUser(), userAndRoles));
+ var events = new ArrayList<AssistantEventPayload>();
+ sut.sendMessage("noteId", conversation.getId(), "hi", otherAuthInfo, userAndRoles,
+ (type, payload) -> events.add(payload)
+ ).get(5, TimeUnit.SECONDS);
+ assertEquals(1, events.size());
+ assertEquals(403, ((AssistantEventPayload.RunFailed) events.get(0)).error.status);
+ }
+
+ @Test
+ void paginatesMessages() throws Exception {
+ var notebook = mock(Notebook.class);
+ when(notebook.processNote(eq("noteId"), any()))
+ .thenAnswer(invocation -> ((NoteProcessor<?>) invocation.getArgument(1))
+ .process(new Note()));
+ var authorization = mock(AuthorizationService.class);
+ when(authorization.isReader("noteId", userAndRoles)).thenReturn(true);
+ var conversation = Conversation.create("noteId", "test", authInfo.getUser());
+ var repository = mock(ConversationRepository.class);
+ when(repository.find("noteId", conversation.getId())).thenReturn(Optional.of(conversation));
+ var sut = new AssistantImpl(
+ notebook, mock(ChatModel.class), null, authorization, repository, executor
+ );
+
+ var messages = List.of(
+ Message.user("m1", "first"),
+ Message.user("m2", "second"),
+ Message.user("m3", "third"));
+ messages.forEach(conversation::addMessage);
+
+ var first = sut.listMessages("noteId", conversation.getId(), null, 2, userAndRoles);
+ assertEquals(List.of(messages.get(2), messages.get(1)), first.messages);
+ assertEquals("m2", first.cursor);
+
+ var last = sut.listMessages("noteId", conversation.getId(), first.cursor, 2, userAndRoles);
+ assertEquals(List.of(messages.get(0)), last.messages);
+ assertNull(last.cursor);
+ }
+
+ @Test
+ void rejectsInvalidLimit() {
+ var sut = new AssistantImpl(
+ null, mock(ChatModel.class), null, null, null, executor);
+ assertThrows(
+ BadRequestException.class,
+ () -> sut.listMessages("noteId", "conv", null, 0, userAndRoles)
+ );
+ assertThrows(
+ BadRequestException.class,
+ () -> sut.listMessages("noteId", "conv", null, -1, userAndRoles)
+ );
+ }
+
+ @Test
+ void limitsModelHistory() throws Exception {
+ var notebook = mock(Notebook.class);
+ when(notebook.processNote(eq("noteId"), any())).thenAnswer(invocation ->
+ ((NoteProcessor<?>) invocation.getArgument(1)).process(new Note()));
+ var authorization = mock(AuthorizationService.class);
+ when(authorization.isReader("noteId", userAndRoles)).thenReturn(true);
+ var chatModel = mock(ChatModel.class);
+ var repository = mock(ConversationRepository.class);
+ var conversation = Conversation.create("noteId", "test", authInfo.getUser());
+ var sut = new AssistantImpl(
+ notebook, chatModel, null, authorization, repository, executor
+ );
+ var limit = 10;
+
+ for (int i = 0; i < limit + 2; i++) conversation.addMessage(Message.user("msg_" + i, "m" + i));
+ when(repository.find("noteId", conversation.getId())).thenReturn(Optional.of(conversation));
+ doAnswer(invocation -> {
+ invocation.<Consumer<Conversation>>getArgument(1).accept(invocation.getArgument(0));
+ return null;
+ }).when(repository).update(any(), any());
+ doAnswer(invocation -> {
+ List<Message> history = invocation.getArgument(1);
+ assertEquals(limit, history.size());
+ assertEquals("m3", ((Message.User) history.get(0)).getContent());
+ assertEquals("hi", ((Message.User) history.get(9)).getContent());
+ return null;
+ }).when(chatModel).stream(any(), any(), any(), any());
+
+ sut.sendMessage("noteId", conversation.getId(), "hi", authInfo, userAndRoles,
+ (type, payload) -> { }
+ ).get(5, TimeUnit.SECONDS);
+ }
+
+ @Test
+ void streamsReply() throws Exception {
+ var notebook = mock(Notebook.class);
+ when(notebook.processNote(eq("noteId"), any())).thenAnswer(invocation ->
+ ((NoteProcessor<?>) invocation.getArgument(1)).process(new Note()));
+ var authorization = mock(AuthorizationService.class);
+ when(authorization.isReader("noteId", userAndRoles)).thenReturn(true);
+ var repository = mock(ConversationRepository.class);
+ var conversation = Conversation.create("noteId", "test", authInfo.getUser());
+ when(repository.find("noteId", conversation.getId())).thenReturn(Optional.of(conversation));
+ doAnswer(invocation -> {
+ invocation.<Consumer<Conversation>>getArgument(1).accept(invocation.getArgument(0));
+ return null;
+ }).when(repository).update(any(), any());
+ var chatModel = mock(ChatModel.class);
+ var sut = new AssistantImpl(
+ notebook, chatModel, null, authorization, repository, executor
+ );
+
+ doAnswer(invocation -> {
+ Consumer<AssistantEvent> consumer = invocation.getArgument(3);
+ consumer.accept(new AssistantEvent.TextDelta("Hel"));
+ consumer.accept(new AssistantEvent.TextDelta("lo"));
+ return null;
+ }).when(chatModel).stream(any(), any(), any(), any());
+
+ var deltas = new ArrayList<String>();
+ var dones = new ArrayList<String>();
+ sut.sendMessage("noteId", conversation.getId(), "hi", authInfo, userAndRoles,
+ (type, payload) -> {
+ if (type == AssistantEventType.MESSAGE_DELTA) {
+ deltas.add(((AssistantEventPayload.MessageDelta) payload).delta);
+ } else if (type == AssistantEventType.MESSAGE_DONE) {
+ dones.add(((AssistantEventPayload.MessageDone) payload).content);
+ }
+ }).get(5, TimeUnit.SECONDS);
+
+ assertEquals(List.of("Hel", "lo"), deltas);
+ assertEquals(List.of("Hello"), dones);
+ assertEquals("Hello", ((Message.Assistant) conversation.getMessages().get(1)).getContent());
+ }
+
+ @Test
+ void completesToolTurn() throws Exception {
+ var notebook = mock(Notebook.class);
+ when(notebook.processNote(eq("noteId"), any()))
+ .thenAnswer(invocation -> ((NoteProcessor<?>) invocation.getArgument(1))
+ .process(new Note()));
+ var authorization = mock(AuthorizationService.class);
+ when(authorization.isReader("noteId", userAndRoles)).thenReturn(true);
+ var repository = mock(ConversationRepository.class);
+
+ var conversation = Conversation.create("noteId", "test", authInfo.getUser());
+ when(repository.find("noteId", conversation.getId())).thenReturn(Optional.of(conversation));
+ doAnswer(invocation -> {
+ invocation.<Consumer<Conversation>>getArgument(1).accept(invocation.getArgument(0));
+ return null;
+ }).when(repository).update(any(), any());
+ var chatModel = mock(ChatModel.class);
+ var notebookService = mock(NotebookService.class);
+ var sut = new AssistantImpl(
+ notebook, chatModel, notebookService, authorization, repository, executor
+ );
+
+ doAnswer(invocation -> {
+ Consumer<AssistantEvent> consumer = invocation.getArgument(3);
+ consumer.accept(new AssistantEvent.ToolCall("call_1", "list_paragraphs", "{}"));
+ return null;
+ }).doAnswer(invocation -> {
+ List<Message> history = invocation.getArgument(1);
+ assertEquals("call_1", ((Message.Tool) history.get(2)).getToolCallId());
+ Consumer<AssistantEvent> consumer = invocation.getArgument(3);
+ consumer.accept(new AssistantEvent.TextDelta("final"));
+ return null;
+ }).when(chatModel).stream(any(), any(), any(), any());
+
+ sut.sendMessage("noteId", conversation.getId(), "hi", authInfo, userAndRoles,
+ (type, payload) -> { }
+ ).get(5, TimeUnit.SECONDS);
+
+ var stored = conversation.getMessages();
+ assertEquals(4, stored.size());
+
+ Message.Assistant toolTurn = (Message.Assistant) stored.get(1);
+ assertEquals("list_paragraphs", toolTurn.getToolCalls().get(0).getName());
+ assertEquals("call_1", ((Message.Tool) stored.get(2)).getToolCallId());
+ assertEquals("final", ((Message.Assistant) stored.get(3)).getContent());
+ }
+
+ @Test
+ void guardsRunningConversation() throws Exception {
+ var notebook = mock(Notebook.class);
+ when(notebook.processNote(eq("noteId"), any())).thenAnswer(invocation ->
+ ((NoteProcessor<?>) invocation.getArgument(1)).process(new Note()));
+ var authorization = mock(AuthorizationService.class);
+ when(authorization.isReader("noteId", userAndRoles)).thenReturn(true);
+ var repository = mock(ConversationRepository.class);
+ var conversation = Conversation.create("noteId", "test", authInfo.getUser());
+ when(repository.find("noteId", conversation.getId())).thenReturn(Optional.of(conversation));
+ doAnswer(invocation -> {
+ invocation.<Consumer<Conversation>>getArgument(1).accept(invocation.getArgument(0));
+ return null;
+ }).when(repository).update(any(), any());
+ var chatModel = mock(ChatModel.class);
+ var sut = new AssistantImpl(
+ notebook, chatModel, null, authorization, repository, executor);
+
+ var streaming = new CountDownLatch(1);
+ var finish = new CountDownLatch(1);
+
+ doAnswer(invocation -> {
+ streaming.countDown(); // signal streaming has started
+ assertTrue(finish.await(5, TimeUnit.SECONDS)); // wait for finish
+ return null;
+ }).when(chatModel).stream(any(), any(), any(), any());
+
+ try {
+ var running = sut.sendMessage(
+ "noteId", conversation.getId(), "hi", authInfo, userAndRoles,
+ (type, payload) -> { }
+ );
+ assertTrue(streaming.await(5, TimeUnit.SECONDS));
+
+ // other conversations can be mutated.
+ var second = Conversation.create("noteId", "independent", authInfo.getUser());
+ when(repository.find("noteId", second.getId())).thenReturn(Optional.of(second));
+ assertEquals("updated",
+ sut.updateTitle("noteId", second.getId(), "updated", authInfo.getUser(), userAndRoles)
+ .getTitle()
+ );
+
+ // running conversation cannot be mutated.
+ assertThrows(ClientErrorException.class,
+ () -> sut.updateTitle("noteId", conversation.getId(), "renamed", authInfo.getUser(),
+ userAndRoles)
+ );
+ assertThrows(ClientErrorException.class,
+ () -> sut.deleteConversation("noteId", conversation.getId(), authInfo.getUser(),
+ userAndRoles)
+ );
+
+ var events = new ArrayList<AssistantEventPayload>();
+ sut.sendMessage("noteId", conversation.getId(), "duplicated", authInfo, userAndRoles,
+ (type, payload) -> events.add(payload)
+ ).get(5, TimeUnit.SECONDS);
+ assertEquals(409, ((AssistantEventPayload.RunFailed) events.get(0)).error.status);
+
+ finish.countDown();
+ running.get(5, TimeUnit.SECONDS); // wait for message processing to complete.
+
+ assertEquals("released",
+ sut.updateTitle("noteId", conversation.getId(), "released", authInfo.getUser(), userAndRoles)
+ .getTitle()
+ );
+ } finally {
+ finish.countDown();
+ }
+ }
+}
diff --git a/zeppelin-server/src/test/java/org/apache/zeppelin/service/assistant/ConversationTest.java b/zeppelin-server/src/test/java/org/apache/zeppelin/service/assistant/ConversationTest.java
new file mode 100644
index 0000000000..5c27489970
--- /dev/null
+++ b/zeppelin-server/src/test/java/org/apache/zeppelin/service/assistant/ConversationTest.java
@@ -0,0 +1,49 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You 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 org.apache.zeppelin.service.assistant;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+import java.util.List;
+import java.util.Map;
+import org.junit.jupiter.api.Test;
+
+class ConversationTest {
+
+ @Test
+ void validatesHistoryWindow() {
+ var conversation = Conversation.create("noteId", "test", "holden");
+ assertTrue(conversation.getRecentMessages(10).isEmpty());
+ assertThrows(IllegalArgumentException.class, () -> conversation.getRecentMessages(0));
+ assertThrows(IllegalArgumentException.class, () -> conversation.getRecentMessages(-1));
+ }
+
+ @Test
+ void keepsToolCallsWithResults() {
+ var conversation = Conversation.create("noteId", "test", "holden");
+ conversation.addMessage(Message.user("old", "old"));
+ var assistant = Message.assistant("assistant", "");
+ assistant.addToolCall(new ToolCall("call_1", "list_paragraphs", Map.of()));
+ conversation.addMessage(assistant);
+ var result = Message.tool("tool", "call_1", "[]");
+ conversation.addMessage(result);
+
+ assertEquals(List.of(assistant, result), conversation.getRecentMessages(1));
+ assertEquals(3, conversation.getMessages().size());
+ }
+}
diff --git a/zeppelin-server/src/test/java/org/apache/zeppelin/service/assistant/FileConversationRepositoryTest.java b/zeppelin-server/src/test/java/org/apache/zeppelin/service/assistant/FileConversationRepositoryTest.java
new file mode 100644
index 0000000000..efeaa94b32
--- /dev/null
+++ b/zeppelin-server/src/test/java/org/apache/zeppelin/service/assistant/FileConversationRepositoryTest.java
@@ -0,0 +1,114 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You 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 org.apache.zeppelin.service.assistant;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+import java.io.File;
+import java.io.IOException;
+import java.nio.file.Files;
+import java.util.Set;
+import java.util.stream.Collectors;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
+
+class FileConversationRepositoryTest {
+ @Test
+ void storesSeparateFiles(@TempDir File directory) throws IOException {
+ var sut = new FileConversationRepository(directory);
+
+ var first = Conversation.create("noteId", "first", "holden");
+ sut.create(first);
+ var second = Conversation.create("noteId", "second", "holden");
+ sut.create(second);
+
+ var loaded = sut.findAll("noteId");
+
+ assertEquals(
+ Set.of(first.getId(), second.getId()), loaded.stream().map(Conversation::getId)
+ .collect(Collectors.toSet())
+ );
+ assertTrue(new File(directory, "noteId/" + first.getId() + ".json").isFile());
+ assertTrue(new File(directory, "noteId/" + second.getId() + ".json").isFile());
+ }
+
+ @Test
+ void propagatesReadFailure(@TempDir File directory) throws IOException {
+ var sut = new FileConversationRepository(directory);
+ Files.createDirectories(new File(directory, "noteId/unreadable.json").toPath());
+ assertThrows(IOException.class, () -> sut.findAll("noteId"));
+ }
+
+ @Test
+ void rejectsDuplicate(@TempDir File directory) throws IOException {
+ var sut = new FileConversationRepository(directory);
+ var conversation = Conversation.create("noteId", "title", "holden");
+ sut.create(conversation);
+
+ conversation.setTitle("discarded");
+ assertThrows(IllegalStateException.class, () -> sut.create(conversation));
+ assertEquals("title", sut.find("noteId", conversation.getId()).orElseThrow().getTitle());
+ }
+
+ @Test
+ void persistsUpdate(@TempDir File directory) throws IOException {
+ var sut = new FileConversationRepository(directory);
+ var conversation = Conversation.create("noteId", "title", "holden");
+ sut.create(conversation);
+
+ sut.update(conversation, c -> {
+ c.setTitle("renamed");
+ c.addMessage(Message.user("msg_1", "hello"));
+ });
+ var stored = sut.find("noteId", conversation.getId()).orElseThrow();
+
+ assertEquals("renamed", stored.getTitle());
+ assertEquals(1, stored.getMessages().size());
+ assertEquals("hello", ((Message.User) stored.getMessages().get(0)).getContent());
+ }
+
+ @Test
+ void preservesFailedUpdate(@TempDir File directory) throws IOException {
+ var sut = new FileConversationRepository(directory);
+ var conversation = Conversation.create("noteId", "title", "holden");
+ sut.create(conversation);
+
+ assertThrows(IllegalStateException.class, () -> sut.update(conversation, c -> {
+ c.setTitle("discarded");
+ throw new IllegalStateException();
+ }));
+ assertEquals("title", sut.find("noteId", conversation.getId()).orElseThrow().getTitle());
+ }
+
+ @Test
+ void rejectsDeletedConversation(@TempDir File directory) throws IOException {
+ var sut = new FileConversationRepository(directory);
+ var conversation = Conversation.create("noteId", "title", "holden");
+ sut.create(conversation);
+
+ sut.delete("noteId", conversation.getId());
+
+ assertTrue(sut.find("noteId", conversation.getId()).isEmpty());
+ assertTrue(sut.findAll("noteId").isEmpty());
+
+ assertThrows(IOException.class, () -> sut.delete("noteId", conversation.getId()));
+ assertThrows(IOException.class,
+ () -> sut.update(conversation, c -> fail("update callback shouldn't run"))
+ );
+ }
+}
diff --git a/zeppelin-server/src/test/java/org/apache/zeppelin/service/assistant/ListParagraphsToolTest.java b/zeppelin-server/src/test/java/org/apache/zeppelin/service/assistant/ListParagraphsToolTest.java
new file mode 100644
index 0000000000..4cdab27b63
--- /dev/null
+++ b/zeppelin-server/src/test/java/org/apache/zeppelin/service/assistant/ListParagraphsToolTest.java
@@ -0,0 +1,87 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You 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 org.apache.zeppelin.service.assistant;
+
+import static org.junit.jupiter.api.Assertions.*;
+import static org.mockito.ArgumentMatchers.*;
+import static org.mockito.Mockito.*;
+
+import java.util.Map;
+import java.util.Set;
+import org.apache.zeppelin.interpreter.InterpreterFactory;
+import org.apache.zeppelin.notebook.AuthorizationService;
+import org.apache.zeppelin.notebook.Note;
+import org.apache.zeppelin.notebook.Notebook;
+import org.apache.zeppelin.notebook.Notebook.NoteProcessor;
+import org.apache.zeppelin.rest.exception.ForbiddenException;
+import org.apache.zeppelin.service.NotebookService;
+import org.apache.zeppelin.user.AuthenticationInfo;
+import org.junit.jupiter.api.Test;
+
+class ListParagraphsToolTest {
+ private final AuthenticationInfo authInfo = AuthenticationInfo.ANONYMOUS;
+ private final Set<String> userAndRoles = Set.of("user");
+
+ @Test
+ void listsParagraphs() throws Exception {
+ var note = new Note();
+ note.setInterpreterFactory(mock(InterpreterFactory.class));
+ var notebook = mock(Notebook.class);
+ when(notebook.processNote(eq("noteId"), eq(false), any())).thenAnswer(invocation ->
+ ((NoteProcessor<?>) invocation.getArgument(2)).process(note));
+ var authorization = mock(AuthorizationService.class);
+ when(authorization.isReader("noteId", userAndRoles)).thenReturn(true);
+ var notebookService = new NotebookService(notebook, authorization, null, null);
+ var sut = new ListParagraphsTool(notebookService);
+
+ var shortParagraph = note.addNewParagraph(AuthenticationInfo.ANONYMOUS);
+ shortParagraph.setText("%md hello");
+ var longParagraph = note.addNewParagraph(AuthenticationInfo.ANONYMOUS);
+ var longText = "%python\n" + "x".repeat(500);
+ longParagraph.setText(longText);
+
+ var paragraphs = sut.call("noteId", Map.of(), authInfo, userAndRoles);
+ assertEquals(2, paragraphs.size());
+ assertEquals(shortParagraph.getId(), paragraphs.get(0).get("id"));
+ assertEquals(longParagraph.getId(), paragraphs.get(1).get("id"));
+ assertEquals("%md hello", paragraphs.get(0).get("text"));
+ assertEquals(longText.substring(0, 497) + "...", paragraphs.get(1).get("text"));
+ assertFalse(paragraphs.get(1).containsKey("interpreter"));
+ assertEquals(longText, longParagraph.getText());
+ assertEquals(1, paragraphs.get(1).get("index"));
+ }
+
+ @Test
+ void rejectsNonReaders() throws Exception {
+ var notebook = mock(Notebook.class);
+ when(notebook.processNote(eq("noteId"), eq(false), any()))
+ .thenAnswer(invocation -> ((NoteProcessor<?>) invocation.getArgument(2))
+ .process(new Note()));
+ var authorization = mock(AuthorizationService.class);
+ when(authorization.isReader("noteId", userAndRoles)).thenReturn(false);
+
+ var notebookService = new NotebookService(notebook, authorization, null, null);
+
+ var sut = new ListParagraphsTool(notebookService);
+
+ assertThrows(
+ ForbiddenException.class,
+ () -> sut.call("noteId", Map.of(), authInfo, userAndRoles)
+ );
+ }
+}
diff --git a/zeppelin-server/src/test/java/org/apache/zeppelin/service/assistant/ToolExecutorTest.java b/zeppelin-server/src/test/java/org/apache/zeppelin/service/assistant/ToolExecutorTest.java
new file mode 100644
index 0000000000..5f4ce1691b
--- /dev/null
+++ b/zeppelin-server/src/test/java/org/apache/zeppelin/service/assistant/ToolExecutorTest.java
@@ -0,0 +1,97 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You 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 org.apache.zeppelin.service.assistant;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+import java.io.IOException;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+import org.apache.zeppelin.user.AuthenticationInfo;
+import org.junit.jupiter.api.Test;
+
+class ToolExecutorTest {
+ private final AuthenticationInfo authInfo = AuthenticationInfo.ANONYMOUS;
+ private final Set<String> userAndRoles = Set.of("user");
+
+ @Test
+ void exposesTools() {
+ var tool = new EchoTool();
+ var sut = new ToolExecutor(List.of(tool));
+ var specs = sut.specs();
+ assertEquals(1, specs.size());
+ assertEquals(tool.name(), specs.get(0).name);
+ assertEquals(tool.description(), specs.get(0).description);
+ assertEquals(tool.parameters(), specs.get(0).parameters);
+ }
+
+ @Test
+ void callsTool() {
+ var sut = new ToolExecutor(List.of(new EchoTool()));
+ var args = Map.<String, Object>of("text", "hello");
+ var result = sut.callTool("noteId", "echo", args, authInfo, userAndRoles);
+ assertNull(result.error);
+ assertEquals(args, result.value);
+ }
+
+ @Test
+ void rejectsUnknownTool() {
+ var sut = new ToolExecutor(List.of(new EchoTool()));
+ var result = sut.callTool("noteId", "unknown_tool", Map.of(), authInfo, userAndRoles);
+ assertNotNull(result.error);
+ }
+
+ @Test
+ void returnsToolError() {
+ var tool = new EchoTool() {
+ @Override
+ public Object call(String noteId, Map<String, Object> args, AuthenticationInfo authInfo,
+ Set<String> userAndRoles) throws IOException {
+ throw new IOException("failed");
+ }
+ };
+ var sut = new ToolExecutor(List.of(tool));
+ var result = sut.callTool("noteId", "echo", Map.of(), authInfo, userAndRoles);
+ assertEquals("failed", result.error);
+ assertNull(result.value);
+ }
+
+ private static class EchoTool implements Tool {
+ @Override
+ public String name() {
+ return "echo";
+ }
+
+ @Override
+ public String description() {
+ return "Return the arguments.";
+ }
+
+ @Override
+ public Map<String, Object> parameters() {
+ return Map.of("type", "object");
+ }
+
+ @Override
+ public Object call(String noteId, Map<String, Object> args, AuthenticationInfo authInfo,
+ Set<String> userAndRoles) throws IOException {
+ return args;
+ }
+ }
+}
diff --git a/zeppelin-web-angular/projects/zeppelin-sdk/src/interfaces/public-api.ts b/zeppelin-web-angular/projects/zeppelin-sdk/src/interfaces/message-assistant.interface.ts
similarity index 58%
copy from zeppelin-web-angular/projects/zeppelin-sdk/src/interfaces/public-api.ts
copy to zeppelin-web-angular/projects/zeppelin-sdk/src/interfaces/message-assistant.interface.ts
index fca7b31a31..e3d0806130 100644
--- a/zeppelin-web-angular/projects/zeppelin-sdk/src/interfaces/public-api.ts
+++ b/zeppelin-web-angular/projects/zeppelin-sdk/src/interfaces/message-assistant.interface.ts
@@ -10,11 +10,23 @@
* limitations under the License.
*/
-export * from './message-common.interface';
-export * from './message-data-type-map.interface';
-export * from './message-interpreter.interface';
-export * from './message-job.interface';
-export * from './message-notebook.interface';
-export * from './message-operator.interface';
-export * from './message-paragraph.interface';
-export * from './websocket-message.interface';
+export interface AssistantSendMessage {
+ noteId: string;
+ conversationId: string;
+ content: string;
+}
+
+export type AssistantEventType =
+ | 'run.started'
+ | 'run.completed'
+ | 'run.failed'
+ | 'message.delta'
+ | 'message.done'
+ | 'tool_call.started'
+ | 'tool_call.done';
+
+export interface AssistantEvent {
+ conversationId: string;
+ type: AssistantEventType;
+ payload: unknown;
+}
diff --git a/zeppelin-web-angular/projects/zeppelin-sdk/src/interfaces/message-data-type-map.interface.ts b/zeppelin-web-angular/projects/zeppelin-sdk/src/interfaces/message-data-type-map.interface.ts
index 6c023a0923..9fcfe7205c 100644
--- a/zeppelin-web-angular/projects/zeppelin-sdk/src/interfaces/message-data-type-map.interface.ts
+++ b/zeppelin-web-angular/projects/zeppelin-sdk/src/interfaces/message-data-type-map.interface.ts
@@ -11,6 +11,7 @@
*/
import { AuthInfo, ErrorInfo } from './message-common.interface';
+import { AssistantEvent, AssistantSendMessage } from './message-assistant.interface';
import {
CheckpointNote,
CloneNote,
@@ -91,6 +92,7 @@ import { OP } from './message-operator.interface';
export type MessageDataTypeMap = MessageSendDataTypeMap | MessageReceiveDataTypeMap;
export interface MessageReceiveDataTypeMap {
+ [OP.ASSISTANT_EVENT]: AssistantEvent;
[OP.COMPLETION_LIST]: CompletionReceived;
[OP.NOTES_INFO]: NotesInfo;
[OP.NOTE]: Note;
@@ -127,6 +129,7 @@ export interface MessageReceiveDataTypeMap {
}
export interface MessageSendDataTypeMap {
+ [OP.ASSISTANT_SEND_MESSAGE]: AssistantSendMessage;
[OP.PING]: undefined;
[OP.LIST_NOTES]: undefined;
[OP.GET_HOME_NOTE]: undefined;
diff --git a/zeppelin-web-angular/projects/zeppelin-sdk/src/interfaces/message-operator.interface.ts b/zeppelin-web-angular/projects/zeppelin-sdk/src/interfaces/message-operator.interface.ts
index e1812877da..a87527623a 100644
--- a/zeppelin-web-angular/projects/zeppelin-sdk/src/interfaces/message-operator.interface.ts
+++ b/zeppelin-web-angular/projects/zeppelin-sdk/src/interfaces/message-operator.interface.ts
@@ -511,6 +511,18 @@ export enum OP {
*/
NOTE_RUNNING_STATUS = 'NOTE_RUNNING_STATUS',
+ /**
+ * [c-s]
+ * send a message to the notebook assistant
+ */
+ ASSISTANT_SEND_MESSAGE = 'ASSISTANT_SEND_MESSAGE',
+
+ /**
+ * [s-c]
+ * assistant run stream event
+ */
+ ASSISTANT_EVENT = 'ASSISTANT_EVENT',
+
/**
* [s-c]
* Notice
diff --git a/zeppelin-web-angular/projects/zeppelin-sdk/src/interfaces/public-api.ts b/zeppelin-web-angular/projects/zeppelin-sdk/src/interfaces/public-api.ts
index fca7b31a31..230906eba2 100644
--- a/zeppelin-web-angular/projects/zeppelin-sdk/src/interfaces/public-api.ts
+++ b/zeppelin-web-angular/projects/zeppelin-sdk/src/interfaces/public-api.ts
@@ -10,6 +10,7 @@
* limitations under the License.
*/
+export * from './message-assistant.interface';
export * from './message-common.interface';
export * from './message-data-type-map.interface';
export * from './message-interpreter.interface';