@databricks/appkit-ui 0.21.0 → 0.23.0

package/docs/plugins/serving.md

@@ -0,0 +1,223 @@
+# Serving plugin
+
+Provides an authenticated proxy to [Databricks Model Serving](https://docs.databricks.com/aws/en/machine-learning/model-serving) endpoints, with invoke and streaming support.
+
+**Key features:**
+
+* Named endpoint aliases for multiple serving endpoints
+* Non-streaming (`invoke`) and SSE streaming (`stream`) invocation
+* Automatic OpenAPI type generation for request/response schemas
+* Request body filtering based on endpoint schema
+* On-behalf-of (OBO) user execution
+
+## Basic usage[​](#basic-usage "Direct link to Basic usage")
+
+```ts
+import { createApp, server, serving } from "@databricks/appkit";
+
+await createApp({
+  plugins: [
+    server(),
+    serving(),
+  ],
+});
+
+```
+
+With no configuration, the plugin reads `DATABRICKS_SERVING_ENDPOINT_NAME` from the environment and registers it under the `default` alias.
+
+## Configuration options[​](#configuration-options "Direct link to Configuration options")
+
+| Option      | Type                             | Default                                                    | Description                            |
+| ----------- | -------------------------------- | ---------------------------------------------------------- | -------------------------------------- |
+| `endpoints` | `Record<string, EndpointConfig>` | `{ default: { env: "DATABRICKS_SERVING_ENDPOINT_NAME" } }` | Map of alias names to endpoint configs |
+| `timeout`   | `number`                         | `120000`                                                   | Request timeout in ms                  |
+
+### Endpoint aliases[​](#endpoint-aliases "Direct link to Endpoint aliases")
+
+Endpoint aliases let you reference multiple serving endpoints by name:
+
+```ts
+serving({
+  endpoints: {
+    llm: { env: "DATABRICKS_SERVING_ENDPOINT_NAME" },
+    classifier: { env: "DATABRICKS_SERVING_ENDPOINT_CLASSIFIER" },
+  },
+})
+
+```
+
+Each alias maps to an environment variable holding the actual endpoint name. If an endpoint serves multiple models, you can use `servedModel` to bypass traffic routing and target a specific model directly:
+
+```ts
+serving({
+  endpoints: {
+    llm: { env: "DATABRICKS_SERVING_ENDPOINT_NAME", servedModel: "llama-v2" },
+  },
+})
+
+```
+
+## Type generation[​](#type-generation "Direct link to Type generation")
+
+The `appKitServingTypesPlugin()` Vite plugin generates TypeScript types from your serving endpoints' OpenAPI schemas. **No manual setup needed** — the AppKit dev server includes this plugin automatically.
+
+The plugin auto-discovers endpoint configuration from your server file (`server/index.ts` or `server/server.ts`).
+
+Generated types provide:
+
+* **Alias autocomplete** in both backend (`AppKit.serving("alias")`) and frontend hooks (`useServingStream`, `useServingInvoke`)
+* **Typed request/response/chunk** per endpoint based on OpenAPI schemas
+
+If an endpoint's OpenAPI schema is unavailable (not deployed, env var not set), the plugin generates generic fallback types. The endpoint is still usable — just without typed request/response.
+
+note
+
+Endpoints that don't define a streaming response schema in their OpenAPI spec will have `chunk: unknown`. For these endpoints, use `useServingInvoke` instead of `useServingStream` — the `response` type will still be properly typed.
+
+## Environment variables[​](#environment-variables "Direct link to Environment variables")
+
+| Variable                           | Description                                                     |
+| ---------------------------------- | --------------------------------------------------------------- |
+| `DATABRICKS_SERVING_ENDPOINT_NAME` | Default endpoint name (used when `endpoints` config is omitted) |
+
+When using named endpoints, define a custom environment variable per alias (e.g. `DATABRICKS_SERVING_ENDPOINT_CLASSIFIER`).
+
+## Execution context[​](#execution-context "Direct link to Execution context")
+
+All serving routes execute on behalf of the authenticated user (OBO) by default, consistent with the Genie and Files plugins. This ensures per-user `CAN_QUERY` permissions are enforced on the serving endpoint.
+
+For programmatic access via `exports()`, use `.asUser(req)` to run in user context:
+
+```ts
+// Service principal context (default)
+const result = await AppKit.serving("llm").invoke({ messages });
+
+// User context (recommended in route handlers)
+const result = await AppKit.serving("llm").asUser(req).invoke({ messages });
+
+```
+
+## HTTP endpoints[​](#http-endpoints "Direct link to HTTP endpoints")
+
+### Named mode (with `endpoints` config)[​](#named-mode-with-endpoints-config "Direct link to named-mode-with-endpoints-config")
+
+* `POST /api/serving/:alias/invoke` — Non-streaming invocation
+* `POST /api/serving/:alias/stream` — SSE streaming invocation
+
+### Default mode (no `endpoints` config)[​](#default-mode-no-endpoints-config "Direct link to default-mode-no-endpoints-config")
+
+* `POST /api/serving/invoke` — Non-streaming invocation
+* `POST /api/serving/stream` — SSE streaming invocation
+
+### Request format[​](#request-format "Direct link to Request format")
+
+```text
+POST /api/serving/:alias/invoke
+Content-Type: application/json
+
+{
+  "messages": [
+    { "role": "user", "content": "Hello" }
+  ]
+}
+
+```
+
+## Programmatic access[​](#programmatic-access "Direct link to Programmatic access")
+
+The plugin exports `invoke` and `stream` methods for server-side use:
+
+```ts
+const AppKit = await createApp({
+  plugins: [
+    server(),
+    serving({
+      endpoints: {
+        llm: { env: "DATABRICKS_SERVING_ENDPOINT_NAME" },
+      },
+    }),
+  ],
+});
+
+// Non-streaming
+const result = await AppKit.serving("llm").invoke({
+  messages: [{ role: "user", content: "Hello" }],
+});
+
+// Streaming
+for await (const chunk of AppKit.serving("llm").stream({
+  messages: [{ role: "user", content: "Hello" }],
+})) {
+  console.log(chunk);
+}
+
+```
+
+## Frontend hooks[​](#frontend-hooks "Direct link to Frontend hooks")
+
+The `@databricks/appkit-ui` package provides React hooks for serving endpoints:
+
+### useServingStream[​](#useservingstream "Direct link to useServingStream")
+
+Streaming invocation via SSE:
+
+```tsx
+import { useServingStream } from "@databricks/appkit-ui/react";
+
+function ChatStream() {
+  const { stream, chunks, streaming, error, reset } = useServingStream(
+    { messages: [{ role: "user", content: "Hello" }] },
+    {
+      alias: "llm",
+      onComplete: (finalChunks) => {
+        // Called with all accumulated chunks when the stream finishes
+        console.log("Stream done, got", finalChunks.length, "chunks");
+      },
+    },
+  );
+
+  return (
+    <>
+      <button onClick={stream} disabled={streaming}>Send</button>
+      <button onClick={reset}>Reset</button>
+      {chunks.map((chunk, i) => <pre key={i}>{JSON.stringify(chunk)}</pre>)}
+      {error && <p>{error}</p>}
+    </>
+  );
+}
+
+```
+
+### useServingInvoke[​](#useservinginvoke "Direct link to useServingInvoke")
+
+Non-streaming invocation. `invoke()` returns a promise with the response data (or `null` on error):
+
+```tsx
+import { useServingInvoke } from "@databricks/appkit-ui/react";
+
+function Classify() {
+  const { invoke, data, loading, error } = useServingInvoke(
+    { inputs: ["sample text"] },
+    { alias: "classifier" },
+  );
+
+  async function handleClick() {
+    const result = await invoke();
+    if (result) {
+      console.log("Classification result:", result);
+    }
+  }
+
+  return (
+    <>
+      <button onClick={handleClick} disabled={loading}>Classify</button>
+      {data && <pre>{JSON.stringify(data)}</pre>}
+      {error && <p>{error}</p>}
+    </>
+  );
+}
+
+```
+
+Both hooks accept `autoStart: true` to invoke automatically on mount.

package/docs.md

@@ -19,7 +19,7 @@ AppKit simplifies building data applications on Databricks by providing:
 ## Prerequisites[​](#prerequisites "Direct link to Prerequisites")
 
 * [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).
+* Databricks CLI (v0.295.0 or higher): install and configure it according to the [official tutorial](https://docs.databricks.com/aws/en/dev-tools/cli/tutorial).
 
 ## Quick start options[​](#quick-start-options "Direct link to Quick start options")
 
@@ -37,7 +37,7 @@ Databricks AppKit is designed to work with AI coding assistants through Agent Sk
 Install Agent Skills and configure it for use with your preferred AI assistant:
 
 ```bash
-databricks experimental aitools skills install
+databricks experimental aitools install
 
 ```
 

package/llms.txt

@@ -27,6 +27,7 @@ npx @databricks/appkit docs <query>
 - [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 Agent Skills, and remote tunneling to deployed backends.
+- [FAQ](./docs/faq.md): Integrations
 - [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
@@ -36,6 +37,7 @@ npx @databricks/appkit docs <query>
 - [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.
+- [Templates](./docs/development/templates.md): AppKit uses a template system powered by the Databricks CLI's databricks apps init command. Templates define the project structure, and .tmpl files are processed with Go's text/template engine to generate customized output.
 - [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.
 
 ## Plugins
@@ -49,6 +51,7 @@ npx @databricks/appkit docs <query>
 - [Lakebase plugin](./docs/plugins/lakebase.md): Provides a PostgreSQL connection pool for Databricks Lakebase Autoscaling with automatic OAuth token refresh.
 - [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.
+- [Serving plugin](./docs/plugins/serving.md): Provides an authenticated proxy to Databricks Model Serving endpoints, with invoke and streaming support.
 
 ## appkit API reference [collapsed]
 
@@ -66,9 +69,12 @@ npx @databricks/appkit docs <query>
 - [Class: ValidationError](./docs/api/appkit/Class.ValidationError.md): Error thrown when input validation fails.
 - [Enumeration: RequestedClaimsPermissionSet](./docs/api/appkit/Enumeration.RequestedClaimsPermissionSet.md): Permission set for Unity Catalog table access
 - [Enumeration: ResourceType](./docs/api/appkit/Enumeration.ResourceType.md): Resource types from schema $defs.resourceType.enum
+- [Function: appKitServingTypesPlugin()](./docs/api/appkit/Function.appKitServingTypesPlugin.md): Vite plugin to generate TypeScript types for AppKit serving endpoints.
 - [Function: appKitTypesPlugin()](./docs/api/appkit/Function.appKitTypesPlugin.md): Vite plugin to generate types for AppKit queries.
 - [Function: createApp()](./docs/api/appkit/Function.createApp.md): Bootstraps AppKit with the provided configuration.
 - [Function: createLakebasePool()](./docs/api/appkit/Function.createLakebasePool.md): Create a Lakebase pool with appkit's logger integration.
+- [Function: extractServingEndpoints()](./docs/api/appkit/Function.extractServingEndpoints.md): Extract serving endpoint config from a server file by AST-parsing it.
+- [Function: findServerFile()](./docs/api/appkit/Function.findServerFile.md): Find the server entry file by checking candidate paths in order.
 - [Function: generateDatabaseCredential()](./docs/api/appkit/Function.generateDatabaseCredential.md): Generate OAuth credentials for Postgres database connection using the proper Postgres API.
 - [Function: getExecutionContext()](./docs/api/appkit/Function.getExecutionContext.md): Get the current execution context.
 - [Function: getLakebaseOrmConfig()](./docs/api/appkit/Function.getLakebaseOrmConfig.md): Get Lakebase connection configuration for ORMs that don't accept pg.Pool directly.
@@ -81,6 +87,7 @@ npx @databricks/appkit docs <query>
 - [Interface: BasePluginConfig](./docs/api/appkit/Interface.BasePluginConfig.md): Base configuration interface for AppKit plugins
 - [Interface: CacheConfig](./docs/api/appkit/Interface.CacheConfig.md): Configuration for the CacheInterceptor. Controls TTL, size limits, storage backend, and probabilistic cleanup.
 - [Interface: DatabaseCredential](./docs/api/appkit/Interface.DatabaseCredential.md): Database credentials with OAuth token for Postgres connection
+- [Interface: EndpointConfig](./docs/api/appkit/Interface.EndpointConfig.md): Properties
 - [Interface: GenerateDatabaseCredentialRequest](./docs/api/appkit/Interface.GenerateDatabaseCredentialRequest.md): Request parameters for generating database OAuth credentials
 - [Interface: ITelemetry](./docs/api/appkit/Interface.ITelemetry.md): Plugin-facing interface for OpenTelemetry instrumentation.
 - [Interface: LakebasePoolConfig](./docs/api/appkit/Interface.LakebasePoolConfig.md): Configuration for creating a Lakebase connection pool
@@ -90,13 +97,17 @@ npx @databricks/appkit docs <query>
 - [Interface: ResourceEntry](./docs/api/appkit/Interface.ResourceEntry.md): Internal representation of a resource in the registry.
 - [Interface: ResourceFieldEntry](./docs/api/appkit/Interface.ResourceFieldEntry.md): Defines a single field for a resource. Each field has its own environment variable and optional description. Single-value types use one key (e.g. id); multi-value types (database, secret) use multiple (e.g. instancename, databasename or scope, key).
 - [Interface: ResourceRequirement](./docs/api/appkit/Interface.ResourceRequirement.md): Declares a resource requirement for a plugin.
+- [Interface: ServingEndpointEntry](./docs/api/appkit/Interface.ServingEndpointEntry.md): Shape of a single registry entry.
+- [Interface: ServingEndpointRegistry](./docs/api/appkit/Interface.ServingEndpointRegistry.md): Registry interface for serving endpoint type generation.
 - [Interface: StreamExecutionSettings](./docs/api/appkit/Interface.StreamExecutionSettings.md): Execution settings for streaming endpoints. Extends PluginExecutionSettings with SSE stream configuration.
 - [Interface: TelemetryConfig](./docs/api/appkit/Interface.TelemetryConfig.md): OpenTelemetry configuration for AppKit applications
 - [Interface: ValidationResult](./docs/api/appkit/Interface.ValidationResult.md): Result of validating all registered resources against the environment.
 - [Type Alias: ConfigSchema](./docs/api/appkit/TypeAlias.ConfigSchema.md): Configuration schema definition for plugin config.
+- [Type Alias: ExecutionResult<T>](./docs/api/appkit/TypeAlias.ExecutionResult.md): Discriminated union for plugin execution results.
 - [Type Alias: IAppRouter](./docs/api/appkit/TypeAlias.IAppRouter.md): Express router type for plugin route registration
 - [Type Alias: PluginData<T, U, N>](./docs/api/appkit/TypeAlias.PluginData.md): Tuple of plugin class, config, and name. Created by toPlugin() and passed to createApp().
 - [Type Alias: ResourcePermission](./docs/api/appkit/TypeAlias.ResourcePermission.md): Union of all possible permission levels across all resource types.
+- [Type Alias: ServingFactory](./docs/api/appkit/TypeAlias.ServingFactory.md): Factory function returned by AppKit.serving.
 - [Type Alias: ToPlugin()<T, U, N>](./docs/api/appkit/TypeAlias.ToPlugin.md): Factory function type returned by toPlugin(). Accepts optional config and returns a PluginData tuple.
 - [Variable: sql](./docs/api/appkit/Variable.sql.md): SQL helper namespace
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@databricks/appkit-ui",
   "type": "module",
-  "version": "0.21.0",
+  "version": "0.23.0",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -19,7 +19,8 @@
     "llms.txt",
     "README.md",
     "DCO",
-    "NOTICE.md"
+    "NOTICE.md",
+    "sbom.cdx.json"
   ],
   "exports": {
     "./js": "./dist/js/index.js",
@@ -38,55 +39,56 @@
     "postinstall": "node scripts/postinstall.js"
   },
   "dependencies": {
-    "@radix-ui/react-accordion": "^1.2.12",
-    "@radix-ui/react-alert-dialog": "^1.1.15",
-    "@radix-ui/react-aspect-ratio": "^1.1.8",
-    "@radix-ui/react-avatar": "^1.1.11",
-    "@radix-ui/react-checkbox": "^1.3.3",
-    "@radix-ui/react-collapsible": "^1.1.12",
-    "@radix-ui/react-context-menu": "^2.2.16",
-    "@radix-ui/react-dialog": "^1.1.15",
-    "@radix-ui/react-dropdown-menu": "^2.1.16",
-    "@radix-ui/react-hover-card": "^1.1.15",
-    "@radix-ui/react-label": "^2.1.8",
-    "@radix-ui/react-menubar": "^1.1.16",
-    "@radix-ui/react-navigation-menu": "^1.2.14",
-    "@radix-ui/react-popover": "^1.1.15",
-    "@radix-ui/react-progress": "^1.1.8",
-    "@radix-ui/react-radio-group": "^1.3.8",
-    "@radix-ui/react-scroll-area": "^1.2.10",
-    "@radix-ui/react-select": "^2.2.6",
-    "@radix-ui/react-separator": "^1.1.8",
-    "@radix-ui/react-slider": "^1.3.6",
-    "@radix-ui/react-slot": "^1.2.4",
-    "@radix-ui/react-switch": "^1.2.6",
-    "@radix-ui/react-tabs": "^1.1.13",
-    "@radix-ui/react-toggle": "^1.1.10",
-    "@radix-ui/react-toggle-group": "^1.1.11",
-    "@radix-ui/react-tooltip": "^1.2.8",
-    "@tanstack/react-table": "^8.21.3",
-    "apache-arrow": "^21.1.0",
-    "class-variance-authority": "^0.7.1",
-    "clsx": "^2.1.1",
-    "cmdk": "^1.1.1",
-    "echarts": "^6.0.0",
-    "echarts-for-react": "^3.0.5",
-    "embla-carousel-react": "^8.6.0",
-    "input-otp": "^1.4.2",
-    "lucide-react": "^0.554.0",
-    "marked": "^17.0.3",
-    "next-themes": "^0.4.6",
-    "react-day-picker": "^9.11.3",
-    "react-hook-form": "^7.68.0",
-    "react-resizable-panels": "^3.0.6",
-    "sonner": "^2.0.7",
-    "tailwind-merge": "^3.4.0",
-    "vaul": "^1.1.2",
-    "@ast-grep/napi": "^0.37.0",
-    "ajv": "^8.17.1",
-    "ajv-formats": "^3.0.1",
-    "@clack/prompts": "^1.0.1",
-    "commander": "^12.1.0"
+    "@radix-ui/react-accordion": "1.2.12",
+    "@radix-ui/react-alert-dialog": "1.1.15",
+    "@radix-ui/react-aspect-ratio": "1.1.8",
+    "@radix-ui/react-avatar": "1.1.11",
+    "@radix-ui/react-checkbox": "1.3.3",
+    "@radix-ui/react-collapsible": "1.1.12",
+    "@radix-ui/react-context-menu": "2.2.16",
+    "@radix-ui/react-dialog": "1.1.15",
+    "@radix-ui/react-dropdown-menu": "2.1.16",
+    "@radix-ui/react-hover-card": "1.1.15",
+    "@radix-ui/react-label": "2.1.8",
+    "@radix-ui/react-menubar": "1.1.16",
+    "@radix-ui/react-navigation-menu": "1.2.14",
+    "@radix-ui/react-popover": "1.1.15",
+    "@radix-ui/react-progress": "1.1.8",
+    "@radix-ui/react-radio-group": "1.3.8",
+    "@radix-ui/react-scroll-area": "1.2.10",
+    "@radix-ui/react-select": "2.2.6",
+    "@radix-ui/react-separator": "1.1.8",
+    "@radix-ui/react-slider": "1.3.6",
+    "@radix-ui/react-slot": "1.2.4",
+    "@radix-ui/react-switch": "1.2.6",
+    "@radix-ui/react-tabs": "1.1.13",
+    "@radix-ui/react-toggle": "1.1.10",
+    "@radix-ui/react-toggle-group": "1.1.11",
+    "@radix-ui/react-tooltip": "1.2.8",
+    "@tanstack/react-table": "8.21.3",
+    "apache-arrow": "21.1.0",
+    "class-variance-authority": "0.7.1",
+    "clsx": "2.1.1",
+    "cmdk": "1.1.1",
+    "dompurify": "3.3.3",
+    "echarts": "6.0.0",
+    "echarts-for-react": "3.0.5",
+    "embla-carousel-react": "8.6.0",
+    "input-otp": "1.4.2",
+    "lucide-react": "0.554.0",
+    "marked": "17.0.3",
+    "next-themes": "0.4.6",
+    "react-day-picker": "9.12.0",
+    "react-hook-form": "7.68.0",
+    "react-resizable-panels": "3.0.6",
+    "sonner": "2.0.7",
+    "tailwind-merge": "3.4.0",
+    "vaul": "1.1.2",
+    "@ast-grep/napi": "0.37.0",
+    "ajv": "8.17.1",
+    "ajv-formats": "3.0.1",
+    "@clack/prompts": "1.0.1",
+    "commander": "12.1.0"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",
@@ -94,13 +96,13 @@
     "recharts": "^2.0.0 || ^3.0.0"
   },
   "devDependencies": {
-    "@types/react": "^19.0.0",
-    "@types/react-dom": "^19.0.0",
-    "react": "^19.0.0",
-    "react-dom": "^19.0.0",
-    "recharts": "^2.15.4",
-    "tailwindcss": "^4.0.14",
-    "tw-animate-css": "^1.4.0"
+    "@types/react": "19.2.2",
+    "@types/react-dom": "19.2.2",
+    "react": "19.2.0",
+    "react-dom": "19.2.0",
+    "recharts": "2.15.4",
+    "tailwindcss": "4.1.17",
+    "tw-animate-css": "1.4.0"
   },
   "publishConfig": {},
   "bin": {