@databricks/appkit-ui 0.22.0 → 0.23.0

package/docs/api/appkit/Function.appKitServingTypesPlugin.md

@@ -0,0 +1,24 @@
+# Function: appKitServingTypesPlugin()
+
+```ts
+function appKitServingTypesPlugin(options?: AppKitServingTypesPluginOptions): Plugin$1;
+
+```
+
+Vite plugin to generate TypeScript types for AppKit serving endpoints. Fetches OpenAPI schemas from Databricks and generates a .d.ts with ServingEndpointRegistry module augmentation.
+
+Endpoint discovery order:
+
+1. Explicit `endpoints` option (override)
+2. AST extraction from server file (server/index.ts or server/server.ts)
+3. DATABRICKS\_SERVING\_ENDPOINT\_NAME env var (single default endpoint)
+
+## Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter  | Type                              |
+| ---------- | --------------------------------- |
+| `options?` | `AppKitServingTypesPluginOptions` |
+
+## Returns[​](#returns "Direct link to Returns")
+
+`Plugin$1`

package/docs/api/appkit/Function.extractServingEndpoints.md

@@ -0,0 +1,22 @@
+# Function: extractServingEndpoints()
+
+```ts
+function extractServingEndpoints(serverFilePath: string): 
+  | Record<string, EndpointConfig>
+  | null;
+
+```
+
+Extract serving endpoint config from a server file by AST-parsing it. Looks for `serving({ endpoints: { alias: { env: "..." }, ... } })` calls and extracts the endpoint alias names and their environment variable mappings.
+
+## Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter        | Type     | Description                            |
+| ---------------- | -------- | -------------------------------------- |
+| `serverFilePath` | `string` | Absolute path to the server entry file |
+
+## Returns[​](#returns "Direct link to Returns")
+
+\| `Record`<`string`, [`EndpointConfig`](./docs/api/appkit/Interface.EndpointConfig.md)> | `null`
+
+Extracted endpoint config, or null if not found or not extractable

package/docs/api/appkit/Function.findServerFile.md

@@ -0,0 +1,20 @@
+# Function: findServerFile()
+
+```ts
+function findServerFile(basePath: string): string | null;
+
+```
+
+Find the server entry file by checking candidate paths in order.
+
+## Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter  | Type     | Description                           |
+| ---------- | -------- | ------------------------------------- |
+| `basePath` | `string` | Project root directory to search from |
+
+## Returns[​](#returns "Direct link to Returns")
+
+`string` | `null`
+
+Absolute path to the server file, or null if none found

package/docs/api/appkit/Interface.EndpointConfig.md

@@ -0,0 +1,23 @@
+# Interface: EndpointConfig
+
+## Properties[​](#properties "Direct link to Properties")
+
+### env[​](#env "Direct link to env")
+
+```ts
+env: string;
+
+```
+
+Environment variable holding the endpoint name.
+
+***
+
+### servedModel?[​](#servedmodel "Direct link to servedModel?")
+
+```ts
+optional servedModel: string;
+
+```
+
+Target a specific served model (bypasses traffic routing).

package/docs/api/appkit/Interface.ServingEndpointEntry.md

@@ -0,0 +1,30 @@
+# Interface: ServingEndpointEntry
+
+Shape of a single registry entry.
+
+## Properties[​](#properties "Direct link to Properties")
+
+### chunk[​](#chunk "Direct link to chunk")
+
+```ts
+chunk: unknown;
+
+```
+
+***
+
+### request[​](#request "Direct link to request")
+
+```ts
+request: Record<string, unknown>;
+
+```
+
+***
+
+### response[​](#response "Direct link to response")
+
+```ts
+response: unknown;
+
+```

package/docs/api/appkit/Interface.ServingEndpointRegistry.md

@@ -0,0 +1,3 @@
+# Interface: ServingEndpointRegistry
+
+Registry interface for serving endpoint type generation. Empty by default — augmented by the Vite type generator's `.d.ts` output via module augmentation. When populated, provides autocomplete for alias names and typed request/response/chunk per endpoint.

package/docs/api/appkit/TypeAlias.ExecutionResult.md

@@ -0,0 +1,36 @@
+# Type Alias: ExecutionResult\<T>
+
+```ts
+type ExecutionResult<T> = 
+  | {
+  data: T;
+  ok: true;
+}
+  | {
+  message: string;
+  ok: false;
+  status: number;
+};
+
+```
+
+Discriminated union for plugin execution results.
+
+Replaces the previous `T | undefined` return type on `execute()`.
+
+On failure, the HTTP status code is preserved from:
+
+* `AppKitError` subclasses (via `statusCode`)
+* Any `Error` with a numeric `statusCode` property (e.g. `ApiError`)
+* All other errors default to status 500
+
+In production, error messages from non-AppKitError sources are handled as:
+
+* 4xx errors: original message is preserved (client-facing by design)
+* 5xx errors: replaced with "Server error" to prevent information leakage
+
+## Type Parameters[​](#type-parameters "Direct link to Type Parameters")
+
+| Type Parameter |
+| -------------- |
+| `T`            |

package/docs/api/appkit/TypeAlias.ServingFactory.md

@@ -0,0 +1,15 @@
+# Type Alias: ServingFactory
+
+```ts
+type ServingFactory = keyof ServingEndpointRegistry extends never ? (alias?: string) => ServingEndpointHandle : <K>(alias: K) => ServingEndpointHandle<ServingEndpointRegistry[K]["request"], ServingEndpointRegistry[K]["response"]>;
+
+```
+
+Factory function returned by `AppKit.serving`.
+
+This is a conditional type that adapts based on whether `ServingEndpointRegistry` has been populated via module augmentation (generated by `appKitServingTypesPlugin()`):
+
+* **Registry empty (default):** `(alias?: string) => ServingEndpointHandle` — accepts any alias string with untyped request/response.
+* **Registry populated:** `<K>(alias: K) => ServingEndpointHandle<...>` — restricts `alias` to known endpoint keys and infers typed request/response from the registry entry.
+
+Run `appKitServingTypesPlugin()` in your Vite config to generate the registry augmentation and enable full type safety.

package/docs/api/appkit.md

@@ -27,32 +27,37 @@ Core library for building Databricks applications with type-safe SQL queries, pl
 
 ## Interfaces[​](#interfaces "Direct link to Interfaces")
 
-| Interface                                                                                                   | Description                                                                                                                                                                                                                                                   |
-| ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [BasePluginConfig](./docs/api/appkit/Interface.BasePluginConfig.md)                                   | Base configuration interface for AppKit plugins                                                                                                                                                                                                               |
-| [CacheConfig](./docs/api/appkit/Interface.CacheConfig.md)                                             | Configuration for the CacheInterceptor. Controls TTL, size limits, storage backend, and probabilistic cleanup.                                                                                                                                                |
-| [DatabaseCredential](./docs/api/appkit/Interface.DatabaseCredential.md)                               | Database credentials with OAuth token for Postgres connection                                                                                                                                                                                                 |
-| [GenerateDatabaseCredentialRequest](./docs/api/appkit/Interface.GenerateDatabaseCredentialRequest.md) | Request parameters for generating database OAuth credentials                                                                                                                                                                                                  |
-| [ITelemetry](./docs/api/appkit/Interface.ITelemetry.md)                                               | Plugin-facing interface for OpenTelemetry instrumentation. Provides a thin abstraction over OpenTelemetry APIs for plugins.                                                                                                                                   |
-| [LakebasePoolConfig](./docs/api/appkit/Interface.LakebasePoolConfig.md)                               | Configuration for creating a Lakebase connection pool                                                                                                                                                                                                         |
-| [PluginManifest](./docs/api/appkit/Interface.PluginManifest.md)                                       | Plugin manifest that declares metadata and resource requirements. Attached to plugin classes as a static property. Extends the shared PluginManifest with strict resource types.                                                                              |
-| [RequestedClaims](./docs/api/appkit/Interface.RequestedClaims.md)                                     | Optional claims for fine-grained Unity Catalog table permissions When specified, the returned token will be scoped to only the requested tables                                                                                                               |
-| [RequestedResource](./docs/api/appkit/Interface.RequestedResource.md)                                 | Resource to request permissions for in Unity Catalog                                                                                                                                                                                                          |
-| [ResourceEntry](./docs/api/appkit/Interface.ResourceEntry.md)                                         | Internal representation of a resource in the registry. Extends ResourceRequirement with resolution state and plugin ownership.                                                                                                                                |
-| [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. instance\_name, database\_name or scope, key). |
-| [ResourceRequirement](./docs/api/appkit/Interface.ResourceRequirement.md)                             | Declares a resource requirement for a plugin. Can be defined statically in a manifest or dynamically via getResourceRequirements(). Narrows the generated base: type → ResourceType enum, permission → ResourcePermission union.                              |
-| [StreamExecutionSettings](./docs/api/appkit/Interface.StreamExecutionSettings.md)                     | Execution settings for streaming endpoints. Extends PluginExecutionSettings with SSE stream configuration.                                                                                                                                                    |
-| [TelemetryConfig](./docs/api/appkit/Interface.TelemetryConfig.md)                                     | OpenTelemetry configuration for AppKit applications                                                                                                                                                                                                           |
-| [ValidationResult](./docs/api/appkit/Interface.ValidationResult.md)                                   | Result of validating all registered resources against the environment.                                                                                                                                                                                        |
+| Interface                                                                                                   | Description                                                                                                                                                                                                                                                     |
+| ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [BasePluginConfig](./docs/api/appkit/Interface.BasePluginConfig.md)                                   | Base configuration interface for AppKit plugins                                                                                                                                                                                                                 |
+| [CacheConfig](./docs/api/appkit/Interface.CacheConfig.md)                                             | Configuration for the CacheInterceptor. Controls TTL, size limits, storage backend, and probabilistic cleanup.                                                                                                                                                  |
+| [DatabaseCredential](./docs/api/appkit/Interface.DatabaseCredential.md)                               | Database credentials with OAuth token for Postgres connection                                                                                                                                                                                                   |
+| [EndpointConfig](./docs/api/appkit/Interface.EndpointConfig.md)                                       | -                                                                                                                                                                                                                                                               |
+| [GenerateDatabaseCredentialRequest](./docs/api/appkit/Interface.GenerateDatabaseCredentialRequest.md) | Request parameters for generating database OAuth credentials                                                                                                                                                                                                    |
+| [ITelemetry](./docs/api/appkit/Interface.ITelemetry.md)                                               | Plugin-facing interface for OpenTelemetry instrumentation. Provides a thin abstraction over OpenTelemetry APIs for plugins.                                                                                                                                     |
+| [LakebasePoolConfig](./docs/api/appkit/Interface.LakebasePoolConfig.md)                               | Configuration for creating a Lakebase connection pool                                                                                                                                                                                                           |
+| [PluginManifest](./docs/api/appkit/Interface.PluginManifest.md)                                       | Plugin manifest that declares metadata and resource requirements. Attached to plugin classes as a static property. Extends the shared PluginManifest with strict resource types.                                                                                |
+| [RequestedClaims](./docs/api/appkit/Interface.RequestedClaims.md)                                     | Optional claims for fine-grained Unity Catalog table permissions When specified, the returned token will be scoped to only the requested tables                                                                                                                 |
+| [RequestedResource](./docs/api/appkit/Interface.RequestedResource.md)                                 | Resource to request permissions for in Unity Catalog                                                                                                                                                                                                            |
+| [ResourceEntry](./docs/api/appkit/Interface.ResourceEntry.md)                                         | Internal representation of a resource in the registry. Extends ResourceRequirement with resolution state and plugin ownership.                                                                                                                                  |
+| [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. instance\_name, database\_name or scope, key).   |
+| [ResourceRequirement](./docs/api/appkit/Interface.ResourceRequirement.md)                             | Declares a resource requirement for a plugin. Can be defined statically in a manifest or dynamically via getResourceRequirements(). Narrows the generated base: type → ResourceType enum, permission → ResourcePermission union.                                |
+| [ServingEndpointEntry](./docs/api/appkit/Interface.ServingEndpointEntry.md)                           | Shape of a single registry entry.                                                                                                                                                                                                                               |
+| [ServingEndpointRegistry](./docs/api/appkit/Interface.ServingEndpointRegistry.md)                     | Registry interface for serving endpoint type generation. Empty by default — augmented by the Vite type generator's `.d.ts` output via module augmentation. When populated, provides autocomplete for alias names and typed request/response/chunk per endpoint. |
+| [StreamExecutionSettings](./docs/api/appkit/Interface.StreamExecutionSettings.md)                     | Execution settings for streaming endpoints. Extends PluginExecutionSettings with SSE stream configuration.                                                                                                                                                      |
+| [TelemetryConfig](./docs/api/appkit/Interface.TelemetryConfig.md)                                     | OpenTelemetry configuration for AppKit applications                                                                                                                                                                                                             |
+| [ValidationResult](./docs/api/appkit/Interface.ValidationResult.md)                                   | Result of validating all registered resources against the environment.                                                                                                                                                                                          |
 
 ## Type Aliases[​](#type-aliases "Direct link to Type Aliases")
 
 | Type Alias                                                                    | Description                                                                                                 |
 | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
 | [ConfigSchema](./docs/api/appkit/TypeAlias.ConfigSchema.md)             | Configuration schema definition for plugin config. Re-exported from the standard JSON Schema Draft 7 types. |
+| [ExecutionResult](./docs/api/appkit/TypeAlias.ExecutionResult.md)       | Discriminated union for plugin execution results.                                                           |
 | [IAppRouter](./docs/api/appkit/TypeAlias.IAppRouter.md)                 | Express router type for plugin route registration                                                           |
 | [PluginData](./docs/api/appkit/TypeAlias.PluginData.md)                 | Tuple of plugin class, config, and name. Created by `toPlugin()` and passed to `createApp()`.               |
 | [ResourcePermission](./docs/api/appkit/TypeAlias.ResourcePermission.md) | Union of all possible permission levels across all resource types.                                          |
+| [ServingFactory](./docs/api/appkit/TypeAlias.ServingFactory.md)         | Factory function returned by `AppKit.serving`.                                                              |
 | [ToPlugin](./docs/api/appkit/TypeAlias.ToPlugin.md)                     | Factory function type returned by `toPlugin()`. Accepts optional config and returns a PluginData tuple.     |
 
 ## Variables[​](#variables "Direct link to Variables")
@@ -63,17 +68,20 @@ Core library for building Databricks applications with type-safe SQL queries, pl
 
 ## Functions[​](#functions "Direct link to Functions")
 
-| Function                                                                                     | Description                                                                                                                                     |
-| -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
-| [appKitTypesPlugin](./docs/api/appkit/Function.appKitTypesPlugin.md)                   | Vite plugin to generate types for AppKit queries. Calls generateFromEntryPoint under the hood.                                                  |
-| [createApp](./docs/api/appkit/Function.createApp.md)                                   | Bootstraps AppKit with the provided configuration.                                                                                              |
-| [createLakebasePool](./docs/api/appkit/Function.createLakebasePool.md)                 | Create a Lakebase pool with appkit's logger integration. Telemetry automatically uses appkit's OpenTelemetry configuration via global registry. |
-| [generateDatabaseCredential](./docs/api/appkit/Function.generateDatabaseCredential.md) | Generate OAuth credentials for Postgres database connection using the proper Postgres API.                                                      |
-| [getExecutionContext](./docs/api/appkit/Function.getExecutionContext.md)               | Get the current execution context.                                                                                                              |
-| [getLakebaseOrmConfig](./docs/api/appkit/Function.getLakebaseOrmConfig.md)             | Get Lakebase connection configuration for ORMs that don't accept pg.Pool directly.                                                              |
-| [getLakebasePgConfig](./docs/api/appkit/Function.getLakebasePgConfig.md)               | Get Lakebase connection configuration for PostgreSQL clients.                                                                                   |
-| [getPluginManifest](./docs/api/appkit/Function.getPluginManifest.md)                   | Loads and validates the manifest from a plugin constructor. Normalizes string type/permission to strict ResourceType/ResourcePermission.        |
-| [getResourceRequirements](./docs/api/appkit/Function.getResourceRequirements.md)       | Gets the resource requirements from a plugin's manifest.                                                                                        |
-| [getUsernameWithApiLookup](./docs/api/appkit/Function.getUsernameWithApiLookup.md)     | Resolves the PostgreSQL username for a Lakebase connection.                                                                                     |
-| [getWorkspaceClient](./docs/api/appkit/Function.getWorkspaceClient.md)                 | Get workspace client from config or SDK default auth chain                                                                                      |
-| [isSQLTypeMarker](./docs/api/appkit/Function.isSQLTypeMarker.md)                       | Type guard to check if a value is a SQL type marker                                                                                             |
+| Function                                                                                     | Description                                                                                                                                                                                                                   |
+| -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [appKitServingTypesPlugin](./docs/api/appkit/Function.appKitServingTypesPlugin.md)     | Vite plugin to generate TypeScript types for AppKit serving endpoints. Fetches OpenAPI schemas from Databricks and generates a .d.ts with ServingEndpointRegistry module augmentation.                                        |
+| [appKitTypesPlugin](./docs/api/appkit/Function.appKitTypesPlugin.md)                   | Vite plugin to generate types for AppKit queries. Calls generateFromEntryPoint under the hood.                                                                                                                                |
+| [createApp](./docs/api/appkit/Function.createApp.md)                                   | Bootstraps AppKit with the provided configuration.                                                                                                                                                                            |
+| [createLakebasePool](./docs/api/appkit/Function.createLakebasePool.md)                 | Create a Lakebase pool with appkit's logger integration. Telemetry automatically uses appkit's OpenTelemetry configuration via global registry.                                                                               |
+| [extractServingEndpoints](./docs/api/appkit/Function.extractServingEndpoints.md)       | Extract serving endpoint config from a server file by AST-parsing it. Looks for `serving({ endpoints: { alias: { env: "..." }, ... } })` calls and extracts the endpoint alias names and their environment variable mappings. |
+| [findServerFile](./docs/api/appkit/Function.findServerFile.md)                         | Find the server entry file by checking candidate paths in order.                                                                                                                                                              |
+| [generateDatabaseCredential](./docs/api/appkit/Function.generateDatabaseCredential.md) | Generate OAuth credentials for Postgres database connection using the proper Postgres API.                                                                                                                                    |
+| [getExecutionContext](./docs/api/appkit/Function.getExecutionContext.md)               | Get the current execution context.                                                                                                                                                                                            |
+| [getLakebaseOrmConfig](./docs/api/appkit/Function.getLakebaseOrmConfig.md)             | Get Lakebase connection configuration for ORMs that don't accept pg.Pool directly.                                                                                                                                            |
+| [getLakebasePgConfig](./docs/api/appkit/Function.getLakebasePgConfig.md)               | Get Lakebase connection configuration for PostgreSQL clients.                                                                                                                                                                 |
+| [getPluginManifest](./docs/api/appkit/Function.getPluginManifest.md)                   | Loads and validates the manifest from a plugin constructor. Normalizes string type/permission to strict ResourceType/ResourcePermission.                                                                                      |
+| [getResourceRequirements](./docs/api/appkit/Function.getResourceRequirements.md)       | Gets the resource requirements from a plugin's manifest.                                                                                                                                                                      |
+| [getUsernameWithApiLookup](./docs/api/appkit/Function.getUsernameWithApiLookup.md)     | Resolves the PostgreSQL username for a Lakebase connection.                                                                                                                                                                   |
+| [getWorkspaceClient](./docs/api/appkit/Function.getWorkspaceClient.md)                 | Get workspace client from config or SDK default auth chain                                                                                                                                                                    |
+| [isSQLTypeMarker](./docs/api/appkit/Function.isSQLTypeMarker.md)                       | Type guard to check if a value is a SQL type marker                                                                                                                                                                           |

package/docs/faq.md

@@ -0,0 +1,66 @@
+# FAQ
+
+## Integrations[​](#integrations "Direct link to Integrations")
+
+### What Databricks services are available through AppKit?[​](#what-databricks-services-are-available-through-appkit "Direct link to What Databricks services are available through AppKit?")
+
+AppKit provides built-in integrations with the following Databricks services via its [plugin system](./docs/plugins.md):
+
+| Plugin                                         | Databricks Service                | What It Does                                                                            |
+| ---------------------------------------------- | --------------------------------- | --------------------------------------------------------------------------------------- |
+| [Analytics](./docs/plugins/analytics.md) | SQL Warehouses                    | Execute parameterized SQL queries with built-in caching, retry, and Arrow support       |
+| [Lakebase](./docs/plugins/lakebase.md)   | Lakebase Autoscaling (PostgreSQL) | Relational database access via standard pg.Pool with automatic OAuth token refresh      |
+| [Genie](./docs/plugins/genie.md)         | AI/BI Genie Spaces                | Natural language data queries with conversation management and streaming                |
+| [Files](./docs/plugins/files.md)         | Unity Catalog Volumes             | Multi-volume file operations (list, read, upload, download, delete, preview)            |
+| [Serving](./docs/plugins/serving.md)     | Model Serving                     | Authenticated proxy to Model Serving endpoints with invoke and streaming support        |
+| [Server](./docs/plugins/server.md)       | N/A                               | Express HTTP server with static file serving, Vite dev mode, and plugin route injection |
+
+Stay tuned for new plugins as we constantly expand integrations!
+
+### Can I add custom integrations?[​](#can-i-add-custom-integrations "Direct link to Can I add custom integrations?")
+
+Yes. AppKit's plugin architecture is extensible - you can create custom plugins using the CLI (`npx appkit plugin create`) or manually. See the [creating custom plugins guide](./docs/plugins/custom-plugins.md).
+
+## Authentication[​](#authentication "Direct link to Authentication")
+
+### How does authentication work in AppKit apps?[​](#how-does-authentication-work-in-appkit-apps "Direct link to How does authentication work in AppKit apps?")
+
+AppKit apps are designed to run on [Databricks Apps](https://docs.databricks.com/aws/en/dev-tools/databricks-apps/), which handles user authentication and authorization. Databricks Apps forwards user identity to the app via request headers, and AppKit integrates with this through the `.asUser(req)` pattern for on-behalf-of (OBO) execution — allowing plugins to act on behalf of the authenticated user.
+
+For details on how authentication and authorization work in Databricks Apps, see the [official auth documentation](https://docs.databricks.com/aws/en/dev-tools/databricks-apps/auth).
+
+## Databases[​](#databases "Direct link to Databases")
+
+*Also: Lakebase, PostgreSQL, OLTP*
+
+### How does AppKit handle databases?[​](#how-does-appkit-handle-databases "Direct link to How does AppKit handle databases?")
+
+AppKit is a TypeScript SDK (Express + React) and does not manage databases directly.
+
+To add database support, use the [Lakebase plugin](./docs/plugins/lakebase.md), which integrates with Lakebase Autoscaling.
+
+AppKit also uses Lakebase for caching when it is available (see the [caching](#does-appkit-support-caching) section below).
+
+You can manage Lakebase Autoscaling projects and branches using the dedicated agent skill from [Databricks Agent Skills](./docs/development/ai-assisted-development.md), installed with the Databricks CLI.
+
+### How does database setup and permission management work in AppKit?[​](#how-does-database-setup-and-permission-management-work-in-appkit "Direct link to How does database setup and permission management work in AppKit?")
+
+AppKit apps can have an attached Lakebase Autoscaling instance. No database is bundled by default - you add one by configuring the [Lakebase plugin](./docs/plugins/lakebase.md). When running `databricks apps init` and selecting the Lakebase plugin, the selected database is automatically attached as an app resource after deployment.
+
+With [AI-assisted development](./docs/development/ai-assisted-development.md), you can also ask the Agent to create a Lakebase project and branch for you.
+
+When deployed, a Databricks app uses its Service Principal for schema and table creation. If you configure the Lakebase Autoscaling project as an [app resource](https://docs.databricks.com/aws/en/dev-tools/databricks-apps/resources), the necessary connect and create permissions are granted automatically to the app's Service Principal.
+
+### Does AppKit support Lakebase Provisioned?[​](#does-appkit-support-lakebase-provisioned "Direct link to Does AppKit support Lakebase Provisioned?")
+
+No. AppKit only supports Lakebase Autoscaling. Lakebase Provisioned databases are not supported by the [Lakebase plugin](./docs/plugins/lakebase.md) or Lakebase agent skill from [Databricks Agent Skills](./docs/development/ai-assisted-development.md).
+
+## Caching[​](#caching "Direct link to Caching")
+
+### Does AppKit support caching?[​](#does-appkit-support-caching "Direct link to Does AppKit support caching?")
+
+Yes. The [Analytics plugin](./docs/plugins/analytics.md) - used for executing SQL queries against Databricks SQL Warehouses - supports an optional cache layer.
+
+Caching is configured per plugin and can use either [Lakebase Autoscaling](https://docs.databricks.com/aws/en/oltp/) or an in-memory store, depending on the configuration.
+
+If the Lakebase Autoscaling connection is configured, the AppKit-based app creates an `appkit` schema in the configured database with internal tables required for caching.

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.