feat(appkit): add Genie plugin for AI/BI space integration by calvarjorge · Pull Request #108 · databricks/appkit

calvarjorge · 2026-02-17T15:21:13Z

Summary

Add new Genie plugin
Single SSE endpoint (POST /api/genie/:alias/messages) handles both new and follow-up conversations
Space alias abstraction: users configure URL aliases, which map to a Genie Space ID in the backend.
Always executes as user (OBO) via asUser(req)
SSE event flow: message_start → status (×N) → message_result → query_result (×N per query attachment)
Configurable timeout (default 2min, 0 for indefinite)
No cache/retry (chat is stateful and non-idempotent)
Programmatic sendMessage API exposed via exports()
Conversation history SSE endpoint (GET /api/genie/:alias/conversations/:conversationId) replays full conversation using the same event types, enabling page refresh without losing chat state
- includeQueryResults query param (default true) controls whether query result data is fetched
- Messages streamed first, then query results fetched in parallel
- Server-side pagination with 200-message safety cap
- Programmatic getConversation API exposed via exports()
Fix pre-existing ajv type resolution issue in shared package

Add a new Genie plugin that provides an opinionated chat API powered by Databricks AI/BI Genie spaces. Users configure named space aliases in plugin config, and the backend resolves aliases to actual space IDs. Key design: - Single SSE endpoint: POST /api/genie/:alias/messages - Always executes as user (OBO) via asUser(req) - SSE event flow: message_start → status (×N) → message_result → query_result (×N) - Space alias abstraction keeps space IDs out of URLs and client code - No cache/retry (chat is stateful and non-idempotent) - Configurable timeout (default 2min, 0 for indefinite) Also fixes pre-existing ajv type resolution issue in shared package where pnpm hoisting caused TypeScript to resolve ajv@6 types instead of the declared ajv@8 dependency. Signed-off-by: Jorge Calvar <jorge.calvar@databricks.com>

Cast error entries to `any` when mapping validation errors so the code works regardless of which ajv version TypeScript resolves (v6 has `dataPath`, v8 has `instancePath`). Signed-off-by: Jorge Calvar <jorge.calvar@databricks.com>

Signed-off-by: Jorge Calvar <jorge.calvar@databricks.com>

Add genie manifest.json to tsdown copy config so it's available at runtime when loading from the built dist/ output. Signed-off-by: Jorge Calvar <jorge.calvar@databricks.com>

SSE endpoint (GET /api/genie/:alias/conversations/:conversationId) that replays full conversation history reusing existing event types, enabling page refresh without losing chat state. Signed-off-by: Jorge Calvar <jorge.calvar@databricks.com>

packages/appkit/src/plugins/genie/genie.ts

Use top-level @databricks/sdk-experimental export for Time/TimeUnits and import createLogger from logging index instead of direct file path. Signed-off-by: Jorge Calvar <jorge.calvar@databricks.com>

Signed-off-by: Jorge Calvar <jorge.calvar@databricks.com> # Conflicts: # packages/appkit/src/index.ts # packages/shared/src/cli/commands/plugin/sync/sync.ts

pkosiec

Nice work!

pkosiec · 2026-02-25T13:32:35Z

docs/docs/api/appkit/Variable.genie.md

we should add

/** * @internal */

comment to the genie const to avoid generating this

pkosiec · 2026-02-25T13:33:07Z

packages/appkit/src/plugins/genie/index.ts

We need to document the plugin in the plugins.md file in our docs, so that users know how to use it 👍

pkosiec · 2026-02-25T13:36:00Z

packages/appkit/src/plugins/genie/genie.ts

+          }
+        : undefined,
+      text: att.text ? { content: att.text.content } : undefined,
+      suggestedQuestions: att.suggested_questions?.questions,


do you have a screenshot of how the suggested questions look like? (I mean the user point of view, so it's probably a question to this PR: #116

pkosiec · 2026-02-25T13:41:11Z

packages/appkit/src/plugins/genie/genie.ts

+      return;
+    }
+
+    const includeQueryResults = req.query.includeQueryResults !== "false";


what's the use case of not querying the attachments? I'm just wondering if we need that?

the query results are used for the Genie response (so can be found there indirectly as well), maybe the user don't want the actual table data that was used to provide the response

…ugins.md Add @internal JSDoc to genie const to exclude it from generated API docs. Add Genie plugin section to plugins.md covering configuration, endpoints, SSE events, and programmatic usage. Signed-off-by: Jorge Calvar <jorge.calvar@databricks.com>

Signed-off-by: Jorge Calvar <jorge.calvar@databricks.com>

MarioCadenas · 2026-02-26T10:40:54Z

packages/appkit/src/plugins/genie/genie.ts

+    });
+  }
+
+  async _handleSendMessage(


we are not handling reconnections, or at least I don't see it? am I missing something?

MarioCadenas · 2026-02-26T11:45:37Z

packages/appkit/src/plugins/genie/genie.ts

+          const statusQueue: string[] = [];
+          let notifyGenerator: () => void = () => {};
+          let waiterDone = false;
+
+          const onProgress = async (message: GenieMessage): Promise<void> => {
+            if (message.status) {
+              statusQueue.push(message.status);
+              notifyGenerator();
+            }
+          };
+
+          let resultConversationId = "";
+          let resultMessageId = "";
+          let completedMessage: GenieMessage =
+            undefined as unknown as GenieMessage;
+          let waiterError: Error | null = null;
+
+          // Launch Genie API call
+          const waiterPromise = (async () => {
+            let messageWaiter: CreateMessageWaiter;
+
+            if (conversationId) {
+              messageWaiter = await workspaceClient.genie.createMessage({
+                space_id: spaceId,
+                conversation_id: conversationId,
+                content,
+              });
+              resultConversationId = conversationId;
+            } else {
+              const startWaiter: StartConversationWaiter =
+                await workspaceClient.genie.startConversation({
+                  space_id: spaceId,
+                  content,
+                });
+              resultConversationId = startWaiter.conversation_id;
+              resultMessageId = startWaiter.message_id;
+              messageWaiter = startWaiter as unknown as CreateMessageWaiter;
+            }
+
+            const result = await messageWaiter.wait({ onProgress });
+            completedMessage = result;
+            resultMessageId = result.message_id;
+            return result;
+          })()
+            .catch((err: Error) => {
+              waiterError = err;
+            })
+            .finally(() => {
+              waiterDone = true;
+              notifyGenerator();
+            });


as talked in private chat we will make a wrapper around this to make the stream callback much easier to read

i implemented the wrapper as we discussed, it makes the code easier to follow. the length of the func is reduced, although i don't think as much as we expected 😅

MarioCadenas · 2026-02-26T11:47:02Z

packages/appkit/src/plugins/genie/types.ts

+
+export interface IGenieConfig extends BasePluginConfig {
+  /** Map of alias → Genie Space ID */
+  spaces: Record<string, string>;


also as talked on zoom, we should have a default spaces defined so we can just put the genie plugin like genie() without having to configure it

MarioCadenas · 2026-02-26T11:47:45Z

packages/appkit/src/plugins/genie/manifest.json

+        "permission": "CAN_RUN",
+        "fields": {
+          "id": {
+            "env": "DATABRICKS_GENIE_SPACE_ID",


this env var and the env var we use as default in the default space should be the same

Signed-off-by: Jorge Calvar <jorge.calvar@databricks.com>

Pass deterministic streamId values to StreamManager so clients can reconnect and replay missed events using Last-Event-ID. Also adds a default bufferSize of 100 to the Genie stream settings. Signed-off-by: Jorge Calvar <jorge.calvar@databricks.com>

… var Make the `spaces` config optional. When omitted, fall back to { default: DATABRICKS_GENIE_SPACE_ID }. If the env var is also unset, routes gracefully 404 instead of crashing at startup. Signed-off-by: Jorge Calvar <jorge.calvar@databricks.com>

Replace manual concurrency code (statusQueue, notifyGenerator, waiterDone, waiterError, IIFE promise chain) with a reusable pollWaiter async generator that bridges callback-based waiter.wait({ onProgress }) into a for-await-of loop. Signed-off-by: Jorge Calvar <jorge.calvar@databricks.com>

calvarjorge added 4 commits February 17, 2026 16:20

docs: regenerate API docs for genie plugin export

62a84e4

Signed-off-by: Jorge Calvar <jorge.calvar@databricks.com>

fix(appkit): copy genie manifest.json to dist during build

e18c4e5

Add genie manifest.json to tsdown copy config so it's available at runtime when loading from the built dist/ output. Signed-off-by: Jorge Calvar <jorge.calvar@databricks.com>

calvarjorge marked this pull request as draft February 18, 2026 08:50

calvarjorge marked this pull request as ready for review February 18, 2026 16:38

MarioCadenas reviewed Feb 24, 2026

View reviewed changes

packages/appkit/src/plugins/genie/genie.ts Show resolved Hide resolved

fix(appkit): simplify genie plugin imports per PR feedback

4c53d0b

Use top-level @databricks/sdk-experimental export for Time/TimeUnits and import createLogger from logging index instead of direct file path. Signed-off-by: Jorge Calvar <jorge.calvar@databricks.com>

calvarjorge requested a review from MarioCadenas February 25, 2026 10:01

Merge remote-tracking branch 'origin/main' into feat/genie-plugin

6abe637

Signed-off-by: Jorge Calvar <jorge.calvar@databricks.com> # Conflicts: # packages/appkit/src/index.ts # packages/shared/src/cli/commands/plugin/sync/sync.ts

pkosiec reviewed Feb 25, 2026

View reviewed changes

calvarjorge added 2 commits February 25, 2026 16:26

docs: remove Variable.genie from generated API docs sidebar and index

ae6c955

Signed-off-by: Jorge Calvar <jorge.calvar@databricks.com>

MarioCadenas reviewed Feb 26, 2026

View reviewed changes

calvarjorge added 4 commits February 26, 2026 14:26

Merge remote-tracking branch 'origin/main' into feat/genie-plugin

c535337

Signed-off-by: Jorge Calvar <jorge.calvar@databricks.com>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(appkit): add Genie plugin for AI/BI space integration#108

feat(appkit): add Genie plugin for AI/BI space integration#108
calvarjorge wants to merge 13 commits intomainfrom
feat/genie-plugin

calvarjorge commented Feb 17, 2026 •

edited

Loading

Uh oh!

Uh oh!

pkosiec left a comment

Uh oh!

pkosiec Feb 25, 2026

Uh oh!

pkosiec Feb 25, 2026

Uh oh!

pkosiec Feb 25, 2026

Uh oh!

pkosiec Feb 25, 2026

Uh oh!

calvarjorge Feb 25, 2026

Uh oh!

MarioCadenas Feb 26, 2026

Uh oh!

MarioCadenas Feb 26, 2026

Uh oh!

calvarjorge Feb 26, 2026

Uh oh!

MarioCadenas Feb 26, 2026

Uh oh!

MarioCadenas Feb 26, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

calvarjorge commented Feb 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Uh oh!

Uh oh!

pkosiec left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

calvarjorge commented Feb 17, 2026 •

edited

Loading