@databricks/appkit-ui 0.12.2 → 0.13.0

package/docs/plugins/genie.md

@@ -0,0 +1,162 @@
+# Genie plugin
+
+Integrates [Databricks AI/BI Genie](https://docs.databricks.com/en/genie/index.html) spaces into your AppKit application, enabling natural language data queries via a conversational interface.
+
+**Key features:**
+
+* Named space aliases for multiple Genie spaces
+* SSE streaming with real-time status updates
+* Conversation history replay with automatic reconnection
+* Query result attachment fetching
+* On-behalf-of (OBO) user execution
+
+## Basic usage[​](#basic-usage "Direct link to Basic usage")
+
+```ts
+import { createApp, genie, server } from "@databricks/appkit";
+
+await createApp({
+  plugins: [
+    server(),
+    genie(),
+  ],
+});
+
+```
+
+## Configuration options[​](#configuration-options "Direct link to Configuration options")
+
+| Option    | Type                     | Default                                  | Description                                      |
+| --------- | ------------------------ | ---------------------------------------- | ------------------------------------------------ |
+| `spaces`  | `Record<string, string>` | `{ default: DATABRICKS_GENIE_SPACE_ID }` | Map of alias names to Genie Space IDs            |
+| `timeout` | `number`                 | `120000`                                 | Polling timeout in ms. Set to `0` for indefinite |
+
+### Space aliases[​](#space-aliases "Direct link to Space aliases")
+
+Space aliases let you reference multiple Genie spaces by name. The alias is used in API routes and the frontend `<GenieChat>` component:
+
+```ts
+genie({
+  spaces: {
+    sales: "01ABCDEF12345678",
+    support: "01GHIJKL87654321",
+  },
+});
+
+```
+
+If you omit `spaces`, the plugin reads `DATABRICKS_GENIE_SPACE_ID` from the environment and registers it under the `default` alias.
+
+## Environment variables[​](#environment-variables "Direct link to Environment variables")
+
+| Variable                    | Description                                                   |
+| --------------------------- | ------------------------------------------------------------- |
+| `DATABRICKS_GENIE_SPACE_ID` | Default Genie Space ID (used when `spaces` config is omitted) |
+
+## HTTP endpoints[​](#http-endpoints "Direct link to HTTP endpoints")
+
+The genie plugin exposes these endpoints (mounted under `/api/genie`):
+
+* `POST /api/genie/:alias/messages` — Send a message to a Genie space (SSE stream)
+* `GET /api/genie/:alias/conversations/:conversationId` — Replay conversation history (SSE stream)
+
+### Send a message[​](#send-a-message "Direct link to Send a message")
+
+```text
+POST /api/genie/:alias/messages
+Content-Type: application/json
+
+{
+  "content": "What were total sales last quarter?",
+  "conversationId": "optional-existing-conversation-id"
+}
+
+```
+
+The response is an SSE stream that emits these event types:
+
+| Event type       | Description                                                     |
+| ---------------- | --------------------------------------------------------------- |
+| `message_start`  | Conversation and message IDs assigned                           |
+| `status`         | Processing status updates (e.g. `ASKING_AI`, `EXECUTING_QUERY`) |
+| `message_result` | Final message with text and query attachments                   |
+| `query_result`   | Tabular data for a query attachment                             |
+| `error`          | Error details                                                   |
+
+### Get conversation history[​](#get-conversation-history "Direct link to Get conversation history")
+
+```text
+GET /api/genie/:alias/conversations/:conversationId
+
+```
+
+Returns an SSE stream of `message_result` and `query_result` events for all messages in the conversation.
+
+## Programmatic access[​](#programmatic-access "Direct link to Programmatic access")
+
+The plugin exports `sendMessage` and `getConversation` for server-side use:
+
+```ts
+const AppKit = await createApp({
+  plugins: [server(), genie({ spaces: { demo: "space-id" } })],
+});
+
+// Stream events
+for await (const event of AppKit.genie.sendMessage("demo", "Show revenue by region")) {
+  console.log(event.type, event);
+}
+
+// Fetch full conversation
+const history = await AppKit.genie.getConversation("demo", "conversation-id");
+
+```
+
+## Frontend components[​](#frontend-components "Direct link to Frontend components")
+
+The `@databricks/appkit-ui` package provides ready-to-use React components for Genie:
+
+### GenieChat[​](#geniechat "Direct link to GenieChat")
+
+A full-featured chat interface that handles streaming, history, and reconnection:
+
+```tsx
+import { GenieChat } from "@databricks/appkit-ui/react";
+
+function GeniePage() {
+  return (
+    <div style={{ height: 600 }}>
+      <GenieChat alias="demo" />
+    </div>
+  );
+}
+
+```
+
+The `alias` prop must match a key in the `spaces` configuration on the server.
+
+### useGenieChat hook[​](#usegeniechat-hook "Direct link to useGenieChat hook")
+
+For custom chat UIs, use the `useGenieChat` hook directly:
+
+```tsx
+import { useGenieChat } from "@databricks/appkit-ui/react";
+
+function CustomChat() {
+  const { messages, status, sendMessage, reset } = useGenieChat({
+    alias: "demo",
+  });
+
+  return (
+    <>
+      {messages.map((msg) => (
+        <div key={msg.id}>{msg.content}</div>
+      ))}
+      <button onClick={() => sendMessage("Show top customers")}>Ask</button>
+      <button onClick={reset}>New conversation</button>
+    </>
+  );
+}
+
+```
+
+See the [GenieChat](./docs/api/appkit-ui/genie/GenieChat.md) component reference for the full props API.

package/docs/plugins.md

@@ -9,12 +9,13 @@ For complete API documentation, see the [`Plugin`](./docs/api/appkit/Class.Plugi
 Configure plugins when creating your AppKit instance:
 
 ```typescript
-import { createApp, server, analytics } from "@databricks/appkit";
+import { createApp, server, analytics, genie } from "@databricks/appkit";
 
 const AppKit = await createApp({
   plugins: [
     server({ port: 8000 }),
     analytics(),
+    genie(),
   ],
 });
 

package/llms.txt

@@ -44,6 +44,7 @@ npx @databricks/appkit docs <query>
 - [Caching](./docs/plugins/caching.md): AppKit provides both global and plugin-level caching capabilities.
 - [Creating custom plugins](./docs/plugins/custom-plugins.md): If you need custom API routes or background logic, implement an AppKit plugin. The fastest way is to use the CLI:
 - [Execution context](./docs/plugins/execution-context.md): AppKit manages Databricks authentication via two contexts:
+- [Genie plugin](./docs/plugins/genie.md): Integrates Databricks AI/BI Genie spaces into your AppKit application, enabling natural language data queries via a conversational interface.
 - [Lakebase plugin](./docs/plugins/lakebase.md): Currently, the Lakebase plugin currently requires a one-time manual setup to connect your Databricks App with your Lakebase database. An automated setup process is planned for an upcoming future release.
 - [Plugin management](./docs/plugins/plugin-management.md): AppKit includes a CLI for managing plugins. All commands are available under npx @databricks/appkit plugin.
 - [Server plugin](./docs/plugins/server.md): Provides HTTP server capabilities with development and production modes.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@databricks/appkit-ui",
   "type": "module",
-  "version": "0.12.2",
+  "version": "0.13.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/databricks/appkit.git"