@databricks/appkit-ui 0.22.0 → 0.24.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/plugins/vector-search.md

@@ -0,0 +1,247 @@
+# Vector Search plugin
+
+Query Databricks Vector Search indexes with hybrid search, reranking, and cursor pagination from your AppKit application.
+
+**Key features:**
+
+* Named index aliases for multiple Vector Search indexes
+* Hybrid, ANN, and full-text query modes
+* Optional reranking with column-level control
+* Cursor-based pagination for large result sets
+* Service principal (default) and on-behalf-of-user auth
+* Self-managed embedding indexes via custom `embeddingFn`
+
+## Basic usage[​](#basic-usage "Direct link to Basic usage")
+
+```ts
+import { createApp, vectorSearch, server } from "@databricks/appkit";
+
+await createApp({
+  plugins: [
+    server(),
+    vectorSearch({
+      indexes: {
+        products: {
+          indexName: "catalog.schema.products_idx",
+          columns: ["id", "name", "description"],
+          queryType: "hybrid",
+          numResults: 20,
+        },
+      },
+    }),
+  ],
+});
+
+```
+
+## Configuration options[​](#configuration-options "Direct link to Configuration options")
+
+| Option    | Type                          | Default | Description                                              |
+| --------- | ----------------------------- | ------- | -------------------------------------------------------- |
+| `indexes` | `Record<string, IndexConfig>` | —       | **Required.** Map of alias names to index configurations |
+| `timeout` | `number`                      | `30000` | Query timeout in ms                                      |
+
+### Index aliases[​](#index-aliases "Direct link to Index aliases")
+
+Index aliases let you reference multiple Vector Search indexes by name. The alias is used in API routes and programmatic calls:
+
+```ts
+vectorSearch({
+  indexes: {
+    products: {
+      indexName: "catalog.schema.products_idx",
+      columns: ["id", "name", "description"],
+    },
+    docs: {
+      indexName: "catalog.schema.docs_idx",
+      columns: ["id", "title", "content", "url"],
+      queryType: "full_text",
+    },
+  },
+});
+
+```
+
+## IndexConfig[​](#indexconfig "Direct link to IndexConfig")
+
+| Field          | Type                                         | Default               | Description                                                                     |
+| -------------- | -------------------------------------------- | --------------------- | ------------------------------------------------------------------------------- |
+| `indexName`    | `string`                                     | —                     | **Required.** Three-level Unity Catalog name (`catalog.schema.index`)           |
+| `columns`      | `string[]`                                   | —                     | **Required.** Columns to return in query results                                |
+| `queryType`    | `"ann" \| "hybrid" \| "full_text"`           | `"hybrid"`            | Search mode                                                                     |
+| `numResults`   | `number`                                     | `20`                  | Maximum results per query                                                       |
+| `reranker`     | `boolean \| { columnsToRerank: string[] }`   | —                     | Enable reranking. Pass `true` to rerank all result columns, or specify a subset |
+| `auth`         | `"service-principal" \| "on-behalf-of-user"` | `"service-principal"` | Authentication mode for query execution                                         |
+| `pagination`   | `boolean`                                    | —                     | Enable cursor-based pagination                                                  |
+| `endpointName` | `string`                                     | —                     | Vector Search endpoint name. Required when `pagination` is `true`               |
+| `embeddingFn`  | `(text: string) => Promise<number[]>`        | —                     | Custom embedding function for self-managed embedding indexes                    |
+
+### Query types[​](#query-types "Direct link to Query types")
+
+* **`hybrid`** — Combines vector similarity and keyword search. Best for general-purpose retrieval.
+* **`ann`** — Approximate nearest neighbor search using embeddings only. Best for semantic similarity.
+* **`full_text`** — Keyword-based search with no embedding required.
+
+### Reranking[​](#reranking "Direct link to Reranking")
+
+Reranking improves result relevance by running a second-stage model over the initial candidates:
+
+```ts
+vectorSearch({
+  indexes: {
+    products: {
+      indexName: "catalog.schema.products_idx",
+      columns: ["id", "name", "description", "category"],
+      reranker: { columnsToRerank: ["name", "description"] },
+    },
+  },
+});
+
+```
+
+Pass `reranker: true` to rerank across all returned columns.
+
+### On-behalf-of-user auth[​](#on-behalf-of-user-auth "Direct link to On-behalf-of-user auth")
+
+By default, queries run as the app's service principal. Set `auth: "on-behalf-of-user"` to execute queries as the signed-in user instead:
+
+```ts
+vectorSearch({
+  indexes: {
+    documents: {
+      indexName: "catalog.schema.documents_idx",
+      columns: ["id", "title", "body"],
+      auth: "on-behalf-of-user",
+    },
+  },
+});
+
+```
+
+### Pagination[​](#pagination "Direct link to Pagination")
+
+Enable cursor pagination to page through large result sets:
+
+```ts
+vectorSearch({
+  indexes: {
+    products: {
+      indexName: "catalog.schema.products_idx",
+      columns: ["id", "name", "description"],
+      pagination: true,
+      endpointName: "my-vector-search-endpoint",
+    },
+  },
+});
+
+```
+
+`endpointName` is required when `pagination` is `true`. Use the `/:alias/next-page` route to fetch subsequent pages.
+
+### Self-managed embedding indexes[​](#self-managed-embedding-indexes "Direct link to Self-managed embedding indexes")
+
+For indexes that manage their own embeddings, provide an `embeddingFn` that takes a query string and returns a vector:
+
+```ts
+import { embed } from "./my-embedding-client";
+
+vectorSearch({
+  indexes: {
+    products: {
+      indexName: "catalog.schema.products_idx",
+      columns: ["id", "name", "description"],
+      queryType: "ann",
+      embeddingFn: (text) => embed(text),
+    },
+  },
+});
+
+```
+
+## HTTP routes[​](#http-routes "Direct link to HTTP routes")
+
+Routes are mounted at `/api/vector-search`.
+
+| Method | Path                | Description                                                  |
+| ------ | ------------------- | ------------------------------------------------------------ |
+| `POST` | `/:alias/query`     | Query an index by alias                                      |
+| `POST` | `/:alias/next-page` | Fetch the next page of results (requires `pagination: true`) |
+| `GET`  | `/:alias/config`    | Return the resolved config for an index alias                |
+
+### Query an index[​](#query-an-index "Direct link to Query an index")
+
+```text
+POST /api/vector-search/:alias/query
+Content-Type: application/json
+
+{
+  "queryText": "machine learning guide",
+  "numResults": 10
+}
+
+```
+
+Response:
+
+```json
+{
+  "results": [
+    { "id": "42", "name": "Intro to ML", "description": "..." }
+  ],
+  "nextPageToken": "eyJvZmZzZXQiOjEwfQ=="
+}
+
+```
+
+`nextPageToken` is only present when `pagination` is enabled and more results are available.
+
+### Fetch the next page[​](#fetch-the-next-page "Direct link to Fetch the next page")
+
+```text
+POST /api/vector-search/:alias/next-page
+Content-Type: application/json
+
+{
+  "queryText": "machine learning guide",
+  "pageToken": "eyJvZmZzZXQiOjEwfQ=="
+}
+
+```
+
+### Get index config[​](#get-index-config "Direct link to Get index config")
+
+```text
+GET /api/vector-search/:alias/config
+
+```
+
+Returns the resolved `IndexConfig` for the alias (excluding `embeddingFn`).
+
+## Programmatic access[​](#programmatic-access "Direct link to Programmatic access")
+
+The plugin exposes a `query` method for server-side use:
+
+```ts
+const AppKit = await createApp({
+  plugins: [
+    server(),
+    vectorSearch({
+      indexes: {
+        products: {
+          indexName: "catalog.schema.products_idx",
+          columns: ["id", "name", "description"],
+        },
+      },
+    }),
+  ],
+});
+
+const result = await AppKit.vectorSearch.query("products", {
+  queryText: "machine learning guide",
+});
+
+console.log(result.results);
+
+```
+
+Pass optional overrides as a second argument to `query` to adjust `numResults` or other per-call settings.

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
@@ -50,6 +51,8 @@ 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.
+- [Vector Search plugin](./docs/plugins/vector-search.md): Query Databricks Vector Search indexes with hybrid search, reranking, and cursor pagination from your AppKit application.
 
 ## appkit API reference [collapsed]
 
@@ -67,9 +70,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.
@@ -82,6 +88,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
@@ -91,13 +98,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.22.0",
+  "version": "0.24.0",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",