@databricks/appkit-ui 0.12.1 → 0.13.0

package/docs/plugins/analytics.md

@@ -21,11 +21,18 @@ await createApp({
 
 ```
 
-## Where queries live[​](#where-queries-live "Direct link to Where queries live")
+## Query files[​](#query-files "Direct link to Query files")
 
 * Put `.sql` files in `config/queries/`
 * Query key is the filename without `.sql` (e.g. `spend_summary.sql` → `"spend_summary"`)
 
+### Execution context[​](#execution-context "Direct link to Execution context")
+
+* `queryKey.sql` executes as **service principal** (shared cache)
+* `queryKey.obo.sql` executes as **user** (OBO = on-behalf-of, per-user cache)
+
+The execution context is determined by the SQL file name, not by the hook call.
+
 ## SQL parameters[​](#sql-parameters "Direct link to SQL parameters")
 
 Use `:paramName` placeholders and optionally annotate parameter types using SQL comments:
@@ -64,3 +71,99 @@ The analytics plugin exposes these endpoints (mounted under `/api/analytics`):
 
 * `format: "JSON"` (default) returns JSON rows
 * `format: "ARROW"` returns an Arrow "statement\_id" payload over SSE, then the client fetches binary Arrow from `/api/analytics/arrow-result/:jobId`
+
+## Frontend usage[​](#frontend-usage "Direct link to Frontend usage")
+
+### useAnalyticsQuery[​](#useanalyticsquery "Direct link to useAnalyticsQuery")
+
+React hook that subscribes to an analytics query over SSE and returns its latest result.
+
+```ts
+import { useAnalyticsQuery } from "@databricks/appkit-ui/react";
+
+const { data, loading, error } = useAnalyticsQuery(queryKey, parameters, options);
+
+```
+
+**Return type:**
+
+```ts
+{
+  data: T | null;      // query result (typed array for JSON, TypedArrowTable for ARROW)
+  loading: boolean;    // true while the query is executing
+  error: string | null; // error message, or null on success
+}
+
+```
+
+**Options:**
+
+| Option              | Type                | Default  | Description                             |
+| ------------------- | ------------------- | -------- | --------------------------------------- |
+| `format`            | `"JSON" \| "ARROW"` | `"JSON"` | Response format                         |
+| `maxParametersSize` | `number`            | `102400` | Max serialized parameters size in bytes |
+| `autoStart`         | `boolean`           | `true`   | Start query on mount                    |
+
+**Example with loading/error/empty handling:**
+
+```tsx
+import { useAnalyticsQuery } from "@databricks/appkit-ui/react";
+import { sql } from "@databricks/appkit-ui/js";
+import { Skeleton } from "@databricks/appkit-ui";
+
+function SpendTable() {
+  const params = useMemo(() => ({
+    startDate: sql.date("2025-01-01"),
+    endDate: sql.date("2025-12-31"),
+  }), []);
+
+  const { data, loading, error } = useAnalyticsQuery("spend_summary", params);
+
+  if (loading) return <Skeleton className="h-32 w-full" />;
+  if (error) return <div className="text-destructive">{error}</div>;
+  if (!data?.length) return <div className="text-muted-foreground">No results</div>;
+
+  return (
+    <ul>
+      {data.map((row) => (
+        <li key={row.id}>{row.name}: ${row.cost_usd}</li>
+      ))}
+    </ul>
+  );
+}
+
+```
+
+### Type-safe queries[​](#type-safe-queries "Direct link to Type-safe queries")
+
+Augment the `QueryRegistry` interface to get full type inference on parameters and results:
+
+```ts
+// config/appKitTypes.d.ts
+declare module "@databricks/appkit-ui/react" {
+  interface QueryRegistry {
+    spend_summary: {
+      name: "spend_summary";
+      parameters: { startDate: string; endDate: string };
+      result: Array<{ id: string; name: string; cost_usd: number }>;
+    };
+  }
+}
+
+```
+
+See [Type generation](./docs/development/type-generation.md) for automatic generation from SQL files.
+
+### Memoization[​](#memoization "Direct link to Memoization")
+
+**Always wrap parameters in `useMemo`** to avoid refetch loops. The hook re-executes whenever the parameters reference changes:
+
+```ts
+// Good
+const params = useMemo(() => ({ status: sql.string("active") }), []);
+const { data } = useAnalyticsQuery("users", params);
+
+// Bad - creates a new object every render, causing infinite refetches
+const { data } = useAnalyticsQuery("users", { status: sql.string("active") });
+
+```

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/server.md

@@ -31,7 +31,7 @@ The Server plugin uses the deferred initialization phase to access routes from o
 The smallest valid AppKit server:
 
 ```ts
-// server/index.ts
+// server/server.ts
 import { createApp, server } from "@databricks/appkit";
 
 await createApp({

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/docs.md

@@ -21,7 +21,38 @@ AppKit simplifies building data applications on Databricks by providing:
 * [Node.js](https://nodejs.org) v22+ environment with `npm`
 * Databricks CLI (v0.287.0 or higher): install and configure it according to the [official tutorial](https://docs.databricks.com/aws/en/dev-tools/cli/tutorial).
 
-## Quick start[​](#quick-start "Direct link to Quick start")
+## Quick start options[​](#quick-start-options "Direct link to Quick start options")
+
+There are two ways to get started with AppKit:
+
+* **AI-assisted** (recommended): Use an AI coding assistant with Agent Skills to explore data, run CLI commands, and scaffold your app interactively.
+* **Manual**: Use the Databricks CLI directly to create, bootstrap, and deploy your app.
+
+Choose the path that best fits your workflow; both approaches produce the same kind of AppKit-based Databricks application.
+
+## AI-first quick start[​](#ai-first-quick-start "Direct link to AI-first quick start")
+
+Databricks AppKit is designed to work with AI coding assistants through Agent Skills.
+
+Install Agent Skills and configure it for use with your preferred AI assistant:
+
+```bash
+databricks experimental aitools skills install
+
+```
+
+Once configured for your development environment, you can use your AI assistant to create and deploy new Databricks applications, as well as to iteratively evolve your app's codebase.
+
+Just prompt your AI assistant to create a new Databricks app, such as:
+
+```text
+Create a new Databricks app that displays a dashboard of the nyc taxi trips dataset.
+
+```
+
+To learn more about the Agent Skills, see the [AI-assisted development](./docs/development/ai-assisted-development.md) documentation.
+
+## Manual quick start[​](#manual-quick-start "Direct link to Manual quick start")
 
 Learn how to create and deploy a sample Databricks application that uses AppKit with the Databricks CLI.
 

package/llms.txt

@@ -26,14 +26,14 @@ npx @databricks/appkit docs <query>
 - [Architecture](./docs/architecture.md): AppKit follows a plugin-based architecture designed for building production-ready Databricks applications. This document provides a high-level overview of the system components and their interactions.
 - [Configuration](./docs/configuration.md): This guide covers environment variables and configuration options for AppKit applications.
 - [Core principles](./docs/core-principles.md): Learn about the fundamental concepts and principles behind AppKit.
-- [Development](./docs/development.md): AppKit provides multiple development workflows to suit different needs: local development with hot reload, AI-assisted development with MCP, and remote tunneling to deployed backends.
+- [Development](./docs/development.md): AppKit provides multiple development workflows to suit different needs: local development with hot reload, AI-assisted development with Agent Skills, and remote tunneling to deployed backends.
 - [Plugins](./docs/plugins.md): Plugins are modular extensions that add capabilities to your AppKit application. They follow a defined lifecycle and have access to shared services like caching, telemetry, and streaming.
 
 ## Development
 
-- [AI-Assisted development](./docs/development/ai-assisted-development.md): AppKit-specific agent skills for AI coding assistants are coming soon. This documentation will be updated with instructions when available.
+- [AI-Assisted development](./docs/development/ai-assisted-development.md): AppKit integrates with AI coding assistants through the Agent Skills.
 - [LLM Guide](./docs/development/llm-guide.md): This document provides prescriptive guidance for AI coding assistants generating code with Databricks AppKit. It is intentionally opinionated to ensure consistent, production-ready code generation.
-- [Local development](./docs/development/local-development.md): Once your app is bootstrapped according to the Quick start guide, you can start the development server with hot reload for both UI and backend code.
+- [Local development](./docs/development/local-development.md): Once your app is bootstrapped according to the Manual quick start guide, you can start the development server with hot reload for both UI and backend code.
 - [Project setup](./docs/development/project-setup.md): This guide covers the recommended project structure and scaffolding for AppKit applications.
 - [Remote Bridge](./docs/development/remote-bridge.md): Remote bridge allows you to develop against a deployed backend while keeping your UI and queries local. This is useful for testing against production data or debugging deployed backend code without redeploying your app.
 - [Type generation](./docs/development/type-generation.md): AppKit can automatically generate TypeScript types for your SQL queries, providing end-to-end type safety from database to UI.
@@ -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.1",
+  "version": "0.13.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/databricks/appkit.git"