@databricks/appkit 0.54.0 → 0.55.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (73) hide show
  1. package/CLAUDE.md +9 -1
  2. package/dist/appkit/package.js +1 -1
  3. package/dist/beta.d.ts +3 -1
  4. package/dist/beta.js +2 -1
  5. package/dist/cli/commands/plugin/create/create.js +12 -14
  6. package/dist/cli/commands/plugin/create/create.js.map +1 -1
  7. package/dist/cli/commands/plugin/promote/promote.js +2 -12
  8. package/dist/cli/commands/plugin/promote/promote.js.map +1 -1
  9. package/dist/connectors/ai-search/client.js +145 -0
  10. package/dist/connectors/ai-search/client.js.map +1 -0
  11. package/dist/connectors/ai-search/index.js +3 -0
  12. package/dist/connectors/context.js +38 -0
  13. package/dist/connectors/context.js.map +1 -0
  14. package/dist/connectors/index.js +2 -1
  15. package/dist/connectors/serving/client.d.ts.map +1 -1
  16. package/dist/connectors/serving/client.js +2 -26
  17. package/dist/connectors/serving/client.js.map +1 -1
  18. package/dist/core/appkit.d.ts.map +1 -1
  19. package/dist/core/appkit.js.map +1 -1
  20. package/dist/naming.js +29 -0
  21. package/dist/plugin/plugin.d.ts.map +1 -1
  22. package/dist/plugin/plugin.js +2 -1
  23. package/dist/plugin/plugin.js.map +1 -1
  24. package/dist/plugins/ai-search/ai-search.d.ts +63 -0
  25. package/dist/plugins/ai-search/ai-search.d.ts.map +1 -0
  26. package/dist/plugins/ai-search/ai-search.js +296 -0
  27. package/dist/plugins/ai-search/ai-search.js.map +1 -0
  28. package/dist/plugins/ai-search/defaults.js +14 -0
  29. package/dist/plugins/ai-search/defaults.js.map +1 -0
  30. package/dist/plugins/ai-search/index.d.ts +2 -0
  31. package/dist/plugins/ai-search/index.js +3 -0
  32. package/dist/plugins/ai-search/manifest.js +73 -0
  33. package/dist/plugins/ai-search/manifest.js.map +1 -0
  34. package/dist/plugins/ai-search/types.d.ts +80 -0
  35. package/dist/plugins/ai-search/types.d.ts.map +1 -0
  36. package/dist/plugins/beta-exports.generated.d.ts +3 -1
  37. package/dist/plugins/beta-exports.generated.js +2 -0
  38. package/dist/plugins/server/index.d.ts.map +1 -1
  39. package/dist/plugins/server/index.js +2 -1
  40. package/dist/plugins/server/index.js.map +1 -1
  41. package/dist/plugins/ui-variants/index.js.map +1 -1
  42. package/dist/plugins/ui-variants/manifest.js +1 -1
  43. package/dist/registry/resource-registry.d.ts.map +1 -1
  44. package/dist/registry/resource-registry.js +2 -7
  45. package/dist/registry/resource-registry.js.map +1 -1
  46. package/dist/schemas/manifest.d.ts.map +1 -1
  47. package/dist/schemas/manifest.js +3 -2
  48. package/dist/schemas/manifest.js.map +1 -1
  49. package/dist/shared/src/naming.js +13 -0
  50. package/dist/shared/src/naming.js.map +1 -0
  51. package/dist/shared/src/plugin.d.ts +6 -4
  52. package/dist/shared/src/plugin.d.ts.map +1 -1
  53. package/dist/shared/src/schemas/manifest.d.ts +2 -2
  54. package/dist/shared/src/schemas/manifest.d.ts.map +1 -1
  55. package/dist/utils/banner.js +19 -0
  56. package/dist/utils/banner.js.map +1 -0
  57. package/docs/api/appkit/Interface.BasePluginConfig.md +1 -0
  58. package/docs/api/appkit/Interface.IAiSearchConfig.md +71 -0
  59. package/docs/api/appkit/Interface.IndexConfig.md +110 -0
  60. package/docs/api/appkit/Interface.RerankerConfig.md +10 -0
  61. package/docs/api/appkit/Interface.SearchRequest.md +64 -0
  62. package/docs/api/appkit/Interface.SearchResponse.md +52 -0
  63. package/docs/api/appkit/Interface.SearchResult.md +25 -0
  64. package/docs/api/appkit/TypeAlias.SearchFilters.md +6 -0
  65. package/docs/api/appkit/Variable.aiSearch.md +6 -0
  66. package/docs/api/appkit.md +8 -0
  67. package/docs/plugins/{vector-search.md → ai-search.md} +70 -27
  68. package/llms.txt +9 -1
  69. package/package.json +1 -1
  70. package/sbom.cdx.json +1 -1
  71. package/dist/connectors/vector-search/client.js +0 -9
  72. package/dist/connectors/vector-search/client.js.map +0 -1
  73. package/dist/connectors/vector-search/index.js +0 -3
package/docs/api/appkit/Interface.SearchRequest.md ADDED
@@ -0,0 +1,64 @@
1
+ # Interface: SearchRequest
2
+
3
+ ## Properties[​](#properties "Direct link to Properties")
4
+
5
+ ### columns?[​](#columns "Direct link to columns?")
6
+
7
+ ```ts
8
+ optional columns: string[];
9
+
10
+ ```
11
+
12
+ ***
13
+
14
+ ### filters?[​](#filters "Direct link to filters?")
15
+
16
+ ```ts
17
+ optional filters: SearchFilters;
18
+
19
+ ```
20
+
21
+ ***
22
+
23
+ ### numResults?[​](#numresults "Direct link to numResults?")
24
+
25
+ ```ts
26
+ optional numResults: number;
27
+
28
+ ```
29
+
30
+ ***
31
+
32
+ ### queryText?[​](#querytext "Direct link to queryText?")
33
+
34
+ ```ts
35
+ optional queryText: string;
36
+
37
+ ```
38
+
39
+ ***
40
+
41
+ ### queryType?[​](#querytype "Direct link to queryType?")
42
+
43
+ ```ts
44
+ optional queryType: SearchQueryType;
45
+
46
+ ```
47
+
48
+ ***
49
+
50
+ ### queryVector?[​](#queryvector "Direct link to queryVector?")
51
+
52
+ ```ts
53
+ optional queryVector: number[];
54
+
55
+ ```
56
+
57
+ ***
58
+
59
+ ### reranker?[​](#reranker "Direct link to reranker?")
60
+
61
+ ```ts
62
+ optional reranker: boolean;
63
+
64
+ ```
package/docs/api/appkit/Interface.SearchResponse.md ADDED
@@ -0,0 +1,52 @@
1
+ # Interface: SearchResponse\<T>
2
+
3
+ ## Type Parameters[​](#type-parameters "Direct link to Type Parameters")
4
+
5
+ | Type Parameter | Default type |
6
+ | ------------------------------------------- | ----------------------------- |
7
+ | `T` *extends* `Record`<`string`, `unknown`> | `Record`<`string`, `unknown`> |
8
+
9
+ ## Properties[​](#properties "Direct link to Properties")
10
+
11
+ ### nextPageToken[​](#nextpagetoken "Direct link to nextPageToken")
12
+
13
+ ```ts
14
+ nextPageToken: string | null;
15
+
16
+ ```
17
+
18
+ ***
19
+
20
+ ### queryTimeMs[​](#querytimems "Direct link to queryTimeMs")
21
+
22
+ ```ts
23
+ queryTimeMs: number;
24
+
25
+ ```
26
+
27
+ ***
28
+
29
+ ### queryType[​](#querytype "Direct link to queryType")
30
+
31
+ ```ts
32
+ queryType: SearchQueryType;
33
+
34
+ ```
35
+
36
+ ***
37
+
38
+ ### results[​](#results "Direct link to results")
39
+
40
+ ```ts
41
+ results: SearchResult<T>[];
42
+
43
+ ```
44
+
45
+ ***
46
+
47
+ ### totalCount[​](#totalcount "Direct link to totalCount")
48
+
49
+ ```ts
50
+ totalCount: number;
51
+
52
+ ```
package/docs/api/appkit/Interface.SearchResult.md ADDED
@@ -0,0 +1,25 @@
1
+ # Interface: SearchResult\<T>
2
+
3
+ ## Type Parameters[​](#type-parameters "Direct link to Type Parameters")
4
+
5
+ | Type Parameter | Default type |
6
+ | ------------------------------------------- | ----------------------------- |
7
+ | `T` *extends* `Record`<`string`, `unknown`> | `Record`<`string`, `unknown`> |
8
+
9
+ ## Properties[​](#properties "Direct link to Properties")
10
+
11
+ ### data[​](#data "Direct link to data")
12
+
13
+ ```ts
14
+ data: T;
15
+
16
+ ```
17
+
18
+ ***
19
+
20
+ ### score[​](#score "Direct link to score")
21
+
22
+ ```ts
23
+ score: number;
24
+
25
+ ```
package/docs/api/appkit/TypeAlias.SearchFilters.md ADDED
@@ -0,0 +1,6 @@
1
+ # Type Alias: SearchFilters
2
+
3
+ ```ts
4
+ type SearchFilters = Record<string, string | number | boolean | (string | number)[]>;
5
+
6
+ ```
package/docs/api/appkit/Variable.aiSearch.md ADDED
@@ -0,0 +1,6 @@
1
+ # Variable: aiSearch
2
+
3
+ ```ts
4
+ const aiSearch: ToPlugin<typeof AiSearchPlugin, IAiSearchConfig, "aiSearch">;
5
+
6
+ ```
package/docs/api/appkit.md CHANGED
@@ -50,7 +50,9 @@ Documentation merge entry for Typedoc — combines the stable `@databricks/appki
50
50
  | [GenerateDatabaseCredentialRequest](./docs/api/appkit/Interface.GenerateDatabaseCredentialRequest.md) | Request parameters for generating database OAuth credentials |
51
51
  | [GenerationParams](./docs/api/appkit/Interface.GenerationParams.md) | Optional generation parameters forwarded to the OpenAI-compatible serving request body. Names match the serving API wire keys. Only keys that are set are sent — undefined values are omitted so the endpoint applies its own defaults. Ranges are not validated here; the serving endpoint validates. |
52
52
  | [HostedSupervisorTool](./docs/api/appkit/Interface.HostedSupervisorTool.md) | Tagged record returned by every [supervisorTools](./docs/api/appkit/Variable.supervisorTools.md) factory. The `__kind` discriminator lets the agents plugin (and standalone `runAgent`) classify these tools without a structural match against the wire format — keeps the SA wire shape free to evolve and avoids namespace collisions with MCP hosted tools (which use `type: "genie-space"` hyphenated, vs SA's `type: "genie_space"` underscored). |
53
+ | [IAiSearchConfig](./docs/api/appkit/Interface.IAiSearchConfig.md) | Base configuration interface for AppKit plugins |
53
54
  | [IJobsConfig](./docs/api/appkit/Interface.IJobsConfig.md) | Configuration for the Jobs plugin. |
55
+ | [IndexConfig](./docs/api/appkit/Interface.IndexConfig.md) | - |
54
56
  | [ITelemetry](./docs/api/appkit/Interface.ITelemetry.md) | Plugin-facing interface for OpenTelemetry instrumentation. Provides a thin abstraction over OpenTelemetry APIs for plugins. |
55
57
  | [JobAPI](./docs/api/appkit/Interface.JobAPI.md) | User-facing API for a single configured job. |
56
58
  | [JobConfig](./docs/api/appkit/Interface.JobConfig.md) | Per-job configuration options. |
@@ -66,10 +68,14 @@ Documentation merge entry for Typedoc — combines the stable `@databricks/appki
66
68
  | [RegisteredAgent](./docs/api/appkit/Interface.RegisteredAgent.md) | - |
67
69
  | [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 |
68
70
  | [RequestedResource](./docs/api/appkit/Interface.RequestedResource.md) | Resource to request permissions for in Unity Catalog |
71
+ | [RerankerConfig](./docs/api/appkit/Interface.RerankerConfig.md) | - |
69
72
  | [ResourceEntry](./docs/api/appkit/Interface.ResourceEntry.md) | Internal representation of a resource in the registry. Extends ResourceRequirement with resolution state and plugin ownership. |
70
73
  | [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(). |
71
74
  | [RunAgentInput](./docs/api/appkit/Interface.RunAgentInput.md) | - |
72
75
  | [RunAgentResult](./docs/api/appkit/Interface.RunAgentResult.md) | - |
76
+ | [SearchRequest](./docs/api/appkit/Interface.SearchRequest.md) | - |
77
+ | [SearchResponse](./docs/api/appkit/Interface.SearchResponse.md) | - |
78
+ | [SearchResult](./docs/api/appkit/Interface.SearchResult.md) | - |
73
79
  | [ServingEndpointEntry](./docs/api/appkit/Interface.ServingEndpointEntry.md) | Shape of a single registry entry. |
74
80
  | [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. |
75
81
  | [StreamExecutionSettings](./docs/api/appkit/Interface.StreamExecutionSettings.md) | Execution settings for streaming endpoints. Extends PluginExecutionSettings with SSE stream configuration. |
@@ -111,6 +117,7 @@ Documentation merge entry for Typedoc — combines the stable `@databricks/appki
111
117
  | [ResolvedToolEntry](./docs/api/appkit/TypeAlias.ResolvedToolEntry.md) | Internal tool-index entry after a tool record has been resolved to a dispatchable form. |
112
118
  | [ResourceFieldEntry](./docs/api/appkit/TypeAlias.ResourceFieldEntry.md) | - |
113
119
  | [ResourcePermission](./docs/api/appkit/TypeAlias.ResourcePermission.md) | Union of all possible permission levels across all resource types. |
120
+ | [SearchFilters](./docs/api/appkit/TypeAlias.SearchFilters.md) | - |
114
121
  | [ServingFactory](./docs/api/appkit/TypeAlias.ServingFactory.md) | Factory function returned by `AppKit.serving`. |
115
122
  | [SupervisorTool](./docs/api/appkit/TypeAlias.SupervisorTool.md) | Tools supported by the Databricks AI Gateway Responses API. The shapes match the wire format the endpoint expects, so the adapter passes the array straight into the request body. |
116
123
  | [ToolRegistry](./docs/api/appkit/TypeAlias.ToolRegistry.md) | - |
@@ -121,6 +128,7 @@ Documentation merge entry for Typedoc — combines the stable `@databricks/appki
121
128
  | Variable | Description |
122
129
  | ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
123
130
  | [agents](./docs/api/appkit/Variable.agents.md) | Plugin factory for the agents plugin. Reads `config/agents/*.md` by default, resolves toolkits/tools from registered plugins, exposes `appkit.agents.*` runtime API and mounts `POST /invocations` and `POST /responses` (aliased non-streaming invoke endpoints) plus `POST /chat` (streaming, HITL-capable). |
131
+ | [aiSearch](./docs/api/appkit/Variable.aiSearch.md) | - |
124
132
  | [READ\_ACTIONS](./docs/api/appkit/Variable.READ_ACTIONS.md) | Actions that only read data. |
125
133
  | [sql](./docs/api/appkit/Variable.sql.md) | SQL helper namespace |
126
134
  | [SUPERVISOR\_EXTENSION\_KEY](./docs/api/appkit/Variable.SUPERVISOR_EXTENSION_KEY.md) | Namespace key under which the adapter reads its hosted-tool payload from [AgentInput.extensions](./docs/api/appkit/Interface.AgentInput.md#extensions). Exported so the agents plugin and standalone `runAgent` (the producers) can write under the same key the adapter reads. |
package/docs/plugins/{vector-search.md → ai-search.md} RENAMED
@@ -1,4 +1,8 @@
1
- # Vector Search plugin
1
+ # AI Search plugin
2
+
3
+ Beta plugin
4
+
5
+ This plugin is currently **beta**. APIs may change between minor releases. Import from `@databricks/appkit/beta`. See [Plugin Stability Tiers](./docs/plugins/stability.md).
2
6
 
3
7
  Query Databricks Vector Search indexes with hybrid search, reranking, and cursor pagination from your AppKit application.
4
8
 
@@ -14,12 +18,13 @@ Query Databricks Vector Search indexes with hybrid search, reranking, and cursor
14
18
  ## Basic usage[​](#basic-usage "Direct link to Basic usage")
15
19
 
16
20
  ```ts
17
- import { createApp, vectorSearch, server } from "@databricks/appkit";
21
+ import { createApp, server } from "@databricks/appkit";
22
+ import { aiSearch } from "@databricks/appkit/beta";
18
23
 
19
24
  await createApp({
20
25
  plugins: [
21
26
  server(),
22
- vectorSearch({
27
+ aiSearch({
23
28
  indexes: {
24
29
  products: {
25
30
  indexName: "catalog.schema.products_idx",
@@ -46,7 +51,7 @@ await createApp({
46
51
  Index aliases let you reference multiple Vector Search indexes by name. The alias is used in API routes and programmatic calls:
47
52
 
48
53
  ```ts
49
- vectorSearch({
54
+ aiSearch({
50
55
  indexes: {
51
56
  products: {
52
57
  indexName: "catalog.schema.products_idx",
@@ -62,19 +67,23 @@ vectorSearch({
62
67
 
63
68
  ```
64
69
 
70
+ note
71
+
72
+ An alias without its own `indexName` falls back to the `DATABRICKS_VS_INDEX_NAME` env var. If several aliases omit `indexName`, they all resolve to that one physical index (with their own per-alias `columns`, `queryType`, etc.). Give each alias an explicit `indexName` when you mean distinct indexes.
73
+
65
74
  ## IndexConfig[​](#indexconfig "Direct link to IndexConfig")
66
75
 
67
- | Field | Type | Default | Description |
68
- | -------------- | -------------------------------------------- | --------------------- | ------------------------------------------------------------------------------- |
69
- | `indexName` | `string` | — | **Required.** Three-level Unity Catalog name (`catalog.schema.index`) |
70
- | `columns` | `string[]` | — | **Required.** Columns to return in query results |
71
- | `queryType` | `"ann" \| "hybrid" \| "full_text"` | `"hybrid"` | Search mode |
72
- | `numResults` | `number` | `20` | Maximum results per query |
73
- | `reranker` | `boolean \| { columnsToRerank: string[] }` | — | Enable reranking. Pass `true` to rerank all result columns, or specify a subset |
74
- | `auth` | `"service-principal" \| "on-behalf-of-user"` | `"service-principal"` | Authentication mode for query execution |
75
- | `pagination` | `boolean` | — | Enable cursor-based pagination |
76
- | `endpointName` | `string` | — | Vector Search endpoint name. Required when `pagination` is `true` |
77
- | `embeddingFn` | `(text: string) => Promise<number[]>` | — | Custom embedding function for self-managed embedding indexes |
76
+ | Field | Type | Default | Description |
77
+ | -------------- | -------------------------------------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
78
+ | `indexName` | `string` | `DATABRICKS_VS_INDEX_NAME` | Three-level Unity Catalog name (`catalog.schema.index`). Defaults to the `DATABRICKS_VS_INDEX_NAME` env var when omitted. |
79
+ | `columns` | `string[]` | auto-discovered in dev | Columns to return in query results. Optional in development — when omitted, the plugin reads them from the index's source table and warns. **Set explicitly for production**, where a missing value is not auto-filled. |
80
+ | `queryType` | `"ann" \| "hybrid" \| "full_text"` | `"hybrid"` | Search mode |
81
+ | `numResults` | `number` | `20` | Maximum results per query |
82
+ | `reranker` | `boolean \| { columnsToRerank: string[] }` | — | Enable reranking. Pass `true` to rerank all result columns, or specify a subset |
83
+ | `auth` | `"service-principal" \| "on-behalf-of-user"` | `"service-principal"` | Authentication mode for query execution |
84
+ | `pagination` | `boolean` | — | Enable cursor-based pagination |
85
+ | `endpointName` | `string` | — | Vector Search endpoint name. Required when `pagination` is `true` |
86
+ | `embeddingFn` | `(text: string) => Promise<number[]>` | — | Custom embedding function for self-managed embedding indexes |
78
87
 
79
88
  ### Query types[​](#query-types "Direct link to Query types")
80
89
 
@@ -87,7 +96,7 @@ vectorSearch({
87
96
  Reranking improves result relevance by running a second-stage model over the initial candidates:
88
97
 
89
98
  ```ts
90
- vectorSearch({
99
+ aiSearch({
91
100
  indexes: {
92
101
  products: {
93
102
  indexName: "catalog.schema.products_idx",
@@ -106,7 +115,7 @@ Pass `reranker: true` to rerank across all returned columns.
106
115
  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:
107
116
 
108
117
  ```ts
109
- vectorSearch({
118
+ aiSearch({
110
119
  indexes: {
111
120
  documents: {
112
121
  indexName: "catalog.schema.documents_idx",
@@ -123,7 +132,7 @@ vectorSearch({
123
132
  Enable cursor pagination to page through large result sets:
124
133
 
125
134
  ```ts
126
- vectorSearch({
135
+ aiSearch({
127
136
  indexes: {
128
137
  products: {
129
138
  indexName: "catalog.schema.products_idx",
@@ -145,7 +154,7 @@ For indexes that manage their own embeddings, provide an `embeddingFn` that take
145
154
  ```ts
146
155
  import { embed } from "./my-embedding-client";
147
156
 
148
- vectorSearch({
157
+ aiSearch({
149
158
  indexes: {
150
159
  products: {
151
160
  indexName: "catalog.schema.products_idx",
@@ -160,7 +169,7 @@ vectorSearch({
160
169
 
161
170
  ## HTTP routes[​](#http-routes "Direct link to HTTP routes")
162
171
 
163
- Routes are mounted at `/api/vector-search`.
172
+ Routes are mounted at `/api/ai-search`.
164
173
 
165
174
  | Method | Path | Description |
166
175
  | ------ | ------------------- | ------------------------------------------------------------ |
@@ -171,7 +180,7 @@ Routes are mounted at `/api/vector-search`.
171
180
  ### Query an index[​](#query-an-index "Direct link to Query an index")
172
181
 
173
182
  ```text
174
- POST /api/vector-search/:alias/query
183
+ POST /api/ai-search/:alias/query
175
184
  Content-Type: application/json
176
185
 
177
186
  {
@@ -186,19 +195,25 @@ Response:
186
195
  ```json
187
196
  {
188
197
  "results": [
189
- { "id": "42", "name": "Intro to ML", "description": "..." }
198
+ {
199
+ "score": 0.87,
200
+ "data": { "id": "42", "name": "Intro to ML", "description": "..." }
201
+ }
190
202
  ],
203
+ "totalCount": 1,
204
+ "queryTimeMs": 35,
205
+ "queryType": "hybrid",
191
206
  "nextPageToken": "eyJvZmZzZXQiOjEwfQ=="
192
207
  }
193
208
 
194
209
  ```
195
210
 
196
- `nextPageToken` is only present when `pagination` is enabled and more results are available.
211
+ Each result carries its relevance `score` and the returned columns under `data`. `nextPageToken` is `null` unless `pagination` is enabled and more results are available.
197
212
 
198
213
  ### Fetch the next page[​](#fetch-the-next-page "Direct link to Fetch the next page")
199
214
 
200
215
  ```text
201
- POST /api/vector-search/:alias/next-page
216
+ POST /api/ai-search/:alias/next-page
202
217
  Content-Type: application/json
203
218
 
204
219
  {
@@ -211,7 +226,7 @@ Content-Type: application/json
211
226
  ### Get index config[​](#get-index-config "Direct link to Get index config")
212
227
 
213
228
  ```text
214
- GET /api/vector-search/:alias/config
229
+ GET /api/ai-search/:alias/config
215
230
 
216
231
  ```
217
232
 
@@ -222,10 +237,13 @@ Returns the resolved `IndexConfig` for the alias (excluding `embeddingFn`).
222
237
  The plugin exposes a `query` method for server-side use:
223
238
 
224
239
  ```ts
240
+ import { createApp, server } from "@databricks/appkit";
241
+ import { aiSearch } from "@databricks/appkit/beta";
242
+
225
243
  const AppKit = await createApp({
226
244
  plugins: [
227
245
  server(),
228
- vectorSearch({
246
+ aiSearch({
229
247
  indexes: {
230
248
  products: {
231
249
  indexName: "catalog.schema.products_idx",
@@ -236,7 +254,7 @@ const AppKit = await createApp({
236
254
  ],
237
255
  });
238
256
 
239
- const result = await AppKit.vectorSearch.query("products", {
257
+ const result = await AppKit.aiSearch.query("products", {
240
258
  queryText: "machine learning guide",
241
259
  });
242
260
 
@@ -245,3 +263,28 @@ console.log(result.results);
245
263
  ```
246
264
 
247
265
  Pass optional overrides as a second argument to `query` to adjust `numResults` or other per-call settings.
266
+
267
+ ## React hook[​](#react-hook "Direct link to React hook")
268
+
269
+ `useAiSearchQuery` reads the configured indexes from the plugin's client config and posts to the right `/:alias/query` route, so the UI never hardcodes an alias. With one index configured it needs no arguments; pass `{ alias }` to target a specific one.
270
+
271
+ ```tsx
272
+ import { useAiSearchQuery } from "@databricks/appkit-ui/react/beta";
273
+
274
+ function Search() {
275
+ const { search, data, loading, error } = useAiSearchQuery();
276
+
277
+ return (
278
+ <>
279
+ <input onKeyDown={(e) => e.key === "Enter" && search(e.currentTarget.value)} />
280
+ {error && <p>{error}</p>}
281
+ {data?.results.map((r, i) => (
282
+ <div key={i}>{JSON.stringify(r.data)}</div>
283
+ ))}
284
+ </>
285
+ );
286
+ }
287
+
288
+ ```
289
+
290
+ `search` also accepts a full request object (`{ queryText, numResults, filters, ... }`) for per-call control. The hook's `indexes` field lists every configured index, which you can use to build an index picker.
package/llms.txt CHANGED
@@ -44,6 +44,7 @@ npx @databricks/appkit docs <query>
44
44
  ## Plugins
45
45
 
46
46
  - [Agents](./docs/plugins/agents.md): This plugin is currently beta. APIs may change between minor releases. Import from @databricks/appkit/beta. See Plugin Stability Tiers.
47
+ - [AI Search plugin](./docs/plugins/ai-search.md): This plugin is currently beta. APIs may change between minor releases. Import from @databricks/appkit/beta. See Plugin Stability Tiers.
47
48
  - [Analytics plugin](./docs/plugins/analytics.md): Enables SQL query execution against Databricks SQL Warehouses.
48
49
  - [Caching](./docs/plugins/caching.md): AppKit provides both global and plugin-level caching capabilities.
49
50
  - [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:
@@ -57,7 +58,6 @@ npx @databricks/appkit docs <query>
57
58
  - [Plugin management](./docs/plugins/plugin-management.md): AppKit includes a CLI for managing plugins. All commands are available under npx @databricks/appkit plugin.
58
59
  - [Server plugin](./docs/plugins/server.md): Provides HTTP server capabilities with development and production modes.
59
60
  - [Plugin Stability Tiers](./docs/plugins/stability.md): AppKit plugins have a two-tier stability system that communicates API maturity and breaking-change expectations.
60
- - [Vector Search plugin](./docs/plugins/vector-search.md): Query Databricks Vector Search indexes with hybrid search, reranking, and cursor pagination from your AppKit application.
61
61
 
62
62
  ## appkit API reference [collapsed]
63
63
 
@@ -131,7 +131,9 @@ npx @databricks/appkit docs <query>
131
131
  - [Interface: GenerateDatabaseCredentialRequest](./docs/api/appkit/Interface.GenerateDatabaseCredentialRequest.md): Request parameters for generating database OAuth credentials
132
132
  - [Interface: GenerationParams](./docs/api/appkit/Interface.GenerationParams.md): Optional generation parameters forwarded to the OpenAI-compatible serving
133
133
  - [Interface: HostedSupervisorTool](./docs/api/appkit/Interface.HostedSupervisorTool.md): Tagged record returned by every supervisorTools factory. The
134
+ - [Interface: IAiSearchConfig](./docs/api/appkit/Interface.IAiSearchConfig.md): Base configuration interface for AppKit plugins
134
135
  - [Interface: IJobsConfig](./docs/api/appkit/Interface.IJobsConfig.md): Configuration for the Jobs plugin.
136
+ - [Interface: IndexConfig](./docs/api/appkit/Interface.IndexConfig.md): Properties
135
137
  - [Interface: ITelemetry](./docs/api/appkit/Interface.ITelemetry.md): Plugin-facing interface for OpenTelemetry instrumentation.
136
138
  - [Interface: JobAPI](./docs/api/appkit/Interface.JobAPI.md): User-facing API for a single configured job.
137
139
  - [Interface: JobConfig](./docs/api/appkit/Interface.JobConfig.md): Per-job configuration options.
@@ -147,10 +149,14 @@ npx @databricks/appkit docs <query>
147
149
  - [Interface: RegisteredAgent](./docs/api/appkit/Interface.RegisteredAgent.md): Properties
148
150
  - [Interface: RequestedClaims](./docs/api/appkit/Interface.RequestedClaims.md): Optional claims for fine-grained Unity Catalog table permissions
149
151
  - [Interface: RequestedResource](./docs/api/appkit/Interface.RequestedResource.md): Resource to request permissions for in Unity Catalog
152
+ - [Interface: RerankerConfig](./docs/api/appkit/Interface.RerankerConfig.md): Properties
150
153
  - [Interface: ResourceEntry](./docs/api/appkit/Interface.ResourceEntry.md): Internal representation of a resource in the registry.
151
154
  - [Interface: ResourceRequirement](./docs/api/appkit/Interface.ResourceRequirement.md): Declares a resource requirement for a plugin.
152
155
  - [Interface: RunAgentInput](./docs/api/appkit/Interface.RunAgentInput.md): Properties
153
156
  - [Interface: RunAgentResult](./docs/api/appkit/Interface.RunAgentResult.md): Properties
157
+ - [Interface: SearchRequest](./docs/api/appkit/Interface.SearchRequest.md): Properties
158
+ - [Interface: SearchResponse<T>](./docs/api/appkit/Interface.SearchResponse.md): Type Parameters
159
+ - [Interface: SearchResult<T>](./docs/api/appkit/Interface.SearchResult.md): Type Parameters
154
160
  - [Interface: ServingEndpointEntry](./docs/api/appkit/Interface.ServingEndpointEntry.md): Shape of a single registry entry.
155
161
  - [Interface: ServingEndpointRegistry](./docs/api/appkit/Interface.ServingEndpointRegistry.md): Registry interface for serving endpoint type generation.
156
162
  - [Interface: StreamExecutionSettings](./docs/api/appkit/Interface.StreamExecutionSettings.md): Execution settings for streaming endpoints. Extends PluginExecutionSettings with SSE stream configuration.
@@ -187,11 +193,13 @@ npx @databricks/appkit docs <query>
187
193
  - [Type Alias: ResolvedToolEntry](./docs/api/appkit/TypeAlias.ResolvedToolEntry.md): Internal tool-index entry after a tool record has been resolved to a dispatchable form.
188
194
  - [Type Alias: ResourceFieldEntry](./docs/api/appkit/TypeAlias.ResourceFieldEntry.md)
189
195
  - [Type Alias: ResourcePermission](./docs/api/appkit/TypeAlias.ResourcePermission.md): Union of all possible permission levels across all resource types.
196
+ - [Type Alias: SearchFilters](./docs/api/appkit/TypeAlias.SearchFilters.md)
190
197
  - [Type Alias: ServingFactory](./docs/api/appkit/TypeAlias.ServingFactory.md): Factory function returned by AppKit.serving.
191
198
  - [Type Alias: SupervisorTool](./docs/api/appkit/TypeAlias.SupervisorTool.md): Tools supported by the Databricks AI Gateway Responses API. The shapes match
192
199
  - [Type Alias: ToolRegistry](./docs/api/appkit/TypeAlias.ToolRegistry.md)
193
200
  - [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.
194
201
  - [Variable: agents](./docs/api/appkit/Variable.agents.md): Plugin factory for the agents plugin. Reads config/agents/*.md by default,
202
+ - [Variable: aiSearch](./docs/api/appkit/Variable.aiSearch.md)
195
203
  - [Variable: READ_ACTIONS](./docs/api/appkit/Variable.READ_ACTIONS.md): Actions that only read data.
196
204
  - [Variable: sql](./docs/api/appkit/Variable.sql.md): SQL helper namespace
197
205
  - [Variable: SUPERVISOR_EXTENSION_KEY](./docs/api/appkit/Variable.SUPERVISOR_EXTENSION_KEY.md): Namespace key under which the adapter reads its hosted-tool payload
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@databricks/appkit",
3
3
  "type": "module",
4
- "version": "0.54.0",
4
+ "version": "0.55.0",
5
5
  "main": "./dist/index.js",
6
6
  "types": "./dist/index.d.ts",
7
7
  "bin": {