databricks · KabeerThockchom · Apr 29, 2026
diff --git a/appkit-genie-advanced/.env.example b/appkit-genie-advanced/.env.example
@@ -0,0 +1,11 @@
+DATABRICKS_HOST=https://...
+
+# Comma-separated alias=spaceId pairs configured at server boot.
+# Example: GENIE_SPACES=sales=01ABC...,support=01DEF...
+# If unset, falls back to DATABRICKS_GENIE_SPACE_ID under the `default` alias.
+GENIE_SPACES=
+DATABRICKS_GENIE_SPACE_ID=your_genie_space_id
+
+DATABRICKS_APP_PORT=8000
+DATABRICKS_APP_NAME=appkit-genie-advanced
+FLASK_RUN_HOST=0.0.0.0
diff --git a/appkit-genie-advanced/.env.tmpl b/appkit-genie-advanced/.env.tmpl
@@ -0,0 +1,13 @@
+# This file is a Go template processed by `databricks apps init --template <path>`.
+# Template variables are substituted and the result is written as .env.
+{{- if ne .profile ""}}
+DATABRICKS_CONFIG_PROFILE={{.profile}}
+{{- else}}
+DATABRICKS_HOST={{.workspaceHost}}
+{{- end}}
+{{- if .dotEnv.content}}
+{{.dotEnv.content}}
+{{- end}}
+DATABRICKS_APP_PORT=8000
+DATABRICKS_APP_NAME={{.projectName}}
+FLASK_RUN_HOST=localhost
diff --git a/appkit-genie-advanced/.gitignore b/appkit-genie-advanced/.gitignore
@@ -0,0 +1,11 @@
+.DS_Store
+node_modules/
+client/dist/
+dist/
+build/
+.env
+.databricks/
+.smoke-test/
+test-results/
+playwright-report/
+.inspect/
diff --git a/appkit-genie-advanced/.prettierignore b/appkit-genie-advanced/.prettierignore
@@ -0,0 +1,36 @@
+# Dependencies
+node_modules
+
+# Build outputs
+dist
+build
+client/dist
+.next
+.databricks/
+
+# Environment files
+.env
+.env.local
+.env.*.local
+
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Coverage
+coverage
+
+# Cache
+.cache
+.turbo
+
+# Lock files
+package-lock.json
+yarn.lock
+pnpm-lock.yaml
+
+# Vendor
+vendor
diff --git a/appkit-genie-advanced/.prettierrc.json b/appkit-genie-advanced/.prettierrc.json
@@ -0,0 +1,12 @@
+{
+  "semi": true,
+  "trailingComma": "es5",
+  "singleQuote": true,
+  "printWidth": 120,
+  "tabWidth": 2,
+  "useTabs": false,
+  "arrowParens": "always",
+  "endOfLine": "lf",
+  "bracketSpacing": true,
+  "jsxSingleQuote": false
+}
diff --git a/appkit-genie-advanced/CLAUDE.md b/appkit-genie-advanced/CLAUDE.md
@@ -0,0 +1,18 @@
+# AI Assistant Instructions
+
+<!-- appkit-instructions-start -->
+## Databricks AppKit
+
+This project uses Databricks AppKit packages. For AI assistant guidance on using these packages, refer to:
+
+- **@databricks/appkit** (Backend SDK): [./node_modules/@databricks/appkit/CLAUDE.md](./node_modules/@databricks/appkit/CLAUDE.md)
+- **@databricks/appkit-ui** (UI Integration, Charts, Tables, SSE, and more.): [./node_modules/@databricks/appkit-ui/CLAUDE.md](./node_modules/@databricks/appkit-ui/CLAUDE.md)
+
+### Databricks Skills
+
+For enhanced AI assistance with Databricks CLI operations, authentication, data exploration, and app development, install the Databricks skills:
+
+```bash
+databricks experimental aitools skills install
+```
+<!-- appkit-instructions-end -->
diff --git a/appkit-genie-advanced/README.md b/appkit-genie-advanced/README.md
@@ -0,0 +1,142 @@
+# appkit-genie-advanced
+
+A Databricks App template that wraps an existing Genie Space with a richer UI than `appkit-genie`. Built on AppKit (React + TypeScript + Tailwind + Express).
+
+**What this template demonstrates beyond `appkit-genie`:**
+- **Multi-space picker** populated from the Genie REST API at runtime
+- **Conversation history sidebar** — browse and resume past conversations
+- **Live progress checklist** — Genie's `SUBMITTED → ASKING_AI → EXECUTING_QUERY → COMPLETED` pipeline visualized step-by-step
+- **Per-message thumbs feedback** — wired to the Genie feedback endpoint
+- **CSV download** for any query result, generated client-side
+- **Custom AppKit plugin** (`server/plugins/genie-advanced.ts`) that calls Genie REST endpoints AppKit doesn't expose by default (`listSpaces`, `getSpace`, `listConversations`, `sendMessageFeedback`, `getMessageAttachmentQueryResult`)
+
+## Bring your own Genie space
+
+The fastest path: point this template at any Genie space you have access to, set two env vars, and run.
+
+### 1. Find your Space ID
+
+Open your Genie space in Databricks. The URL contains the ID:
+
+```
+https://<workspace>.cloud.databricks.com/genie/rooms/01f13e5abd38168298e36375fa9d6f3c
+                                                    └────────── space ID ──────────┘
+```
+
+### 2. Configure environment
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env`:
+
+```env
+DATABRICKS_HOST=https://your-workspace.cloud.databricks.com
+# Single space (simplest):
+DATABRICKS_GENIE_SPACE_ID=01f13e5abd38168298e36375fa9d6f3c
+
+# OR multiple spaces (the picker shows all of them):
+# GENIE_SPACES=sales=01ABC...,support=01DEF...,ops=01GHI...
+```
+
+### 3. Auth
+
+```bash
+databricks auth login --host https://your-workspace.cloud.databricks.com
+```
+
+This writes a profile to `~/.databrickscfg`. If you use a non-default profile, also set `DATABRICKS_CONFIG_PROFILE=<profile-name>` in `.env`.
+
+### 4. Run
+
+```bash
+npm install
+npm run dev
+```
+
+Open the URL printed in the console (default `http://localhost:8000`) and click **Genie Advanced**. The space picker should populate with your space, the conversation list with any past conversations, and you can immediately start asking questions.
+
+## Routes
+
+The app exposes two pages so you can compare:
+
+- `/genie` — minimal AppKit `<GenieChat>` on a single hardcoded alias (same as the upstream `appkit-genie` template)
+- `/genie-advanced` — the full multi-pane UI described above
+
+## Custom plugin endpoints
+
+`server/plugins/genie-advanced.ts` registers a custom AppKit plugin. All routes execute on-behalf-of the requesting user (`asUser(req)`) so end-users only see spaces and conversations they have permission for.
+
+| Method | Path | Genie SDK call |
+|---|---|---|
+| GET | `/api/genieAdvanced/spaces` | `WorkspaceClient.genie.getSpace(...)` per configured alias |
+| GET | `/api/genieAdvanced/spaces/:alias/conversations` | `genie.listConversations({space_id})` |
+| GET | `/api/genieAdvanced/spaces/:alias/conversations/:cid/messages/:mid/attachments/:aid/result` | `genie.getMessageAttachmentQueryResult(...)` |
+| POST | `/api/genieAdvanced/spaces/:alias/conversations/:cid/messages/:mid/feedback` | `genie.sendMessageFeedback({rating})` |
+
+The chat itself uses AppKit's existing `genie()` plugin (`POST /api/genie/:alias/messages` SSE for new messages, `GET /api/genie/:alias/conversations/:cid` SSE for history replay).
+
+## Prerequisites
+
+- Node.js v22+ and npm
+- Databricks CLI (for deployment)
+- Access to a Databricks workspace with at least one Genie space
+
+## Code Quality
+
+```bash
+npm run typecheck
+npm run lint
+npm run format
+```
+
+## Deployment with Databricks Asset Bundles
+
+### 1. Configure Bundle
+
+Update `databricks.yml` with your workspace settings:
+
+```yaml
+targets:
+  default:
+    workspace:
+      host: https://your-workspace.cloud.databricks.com
+```
+
+Make sure to replace all placeholder values in `databricks.yml` with your actual resource IDs.
+
+### 2. Validate, Deploy, Run
+
+```bash
+databricks bundle validate
+databricks bundle deploy
+databricks bundle run <APP_NAME> -t dev
+```
+
+## Project Structure
+
+```
+client/src/
+├── App.tsx
+└── pages/
+    ├── genie/GeniePage.tsx              # minimal <GenieChat>
+    └── genie-advanced/
+        ├── GenieProPage.tsx              # 3-pane layout
+        ├── SpacePicker.tsx
+        ├── ConversationList.tsx
+        ├── MessageProgress.tsx           # streaming step checklist
+        ├── MessageActions.tsx            # thumbs + CSV
+        ├── api.ts                        # /api/genieAdvanced/* helpers
+        └── types.ts
+server/
+├── server.ts
+└── plugins/
+    └── genie-advanced.ts                      # custom AppKit plugin
+```
+
+## Tech Stack
+
+- **Backend**: Node.js, Express, AppKit
+- **Frontend**: React, TypeScript, Vite, Tailwind, React Router, AppKit-UI
+- **Databricks**: `@databricks/appkit`, `@databricks/sdk-experimental` (Genie API)
diff --git a/appkit-genie-advanced/app.yaml b/appkit-genie-advanced/app.yaml
@@ -0,0 +1,4 @@
+command: ['npm', 'run', 'start']
+env:
+  - name: DATABRICKS_GENIE_SPACE_ID
+    valueFrom: genie-space