@dbx-tools/search 0.6.107 → 0.6.111

package/README.md

@@ -1,44 +1,35 @@
 # @dbx-tools/search
 
-A Meilisearch-style shortcut over Databricks AI Search (Vector Search): a search
-client, agent tools, and an AppKit plugin.
+Extensions for AppKit's beta AI Search plugin: agent tools, federated search,
+index lifecycle helpers, and an AppKit-compatible Lakebase full-text provider.
 
-Import this package when an AppKit or Mastra backend needs to search a
+Use native AppKit `aiSearch` for
 [Databricks AI Search](https://docs.databricks.com/aws/en/ai-search/ai-search)
-index - for autocomplete, docs lookup, RAG retrieval, or a universal search box
-across several indexes. It wraps the low-level SDK
-(`vectorSearchIndexes.queryIndex({ index_name, columns, query_text, query_type,
-num_results, filters_json })` and its columnar response) behind an ergonomic
-client, and ships the agent tools, HTTP routes, and boot config a search UI
-needs - so search is one plugin and, in the simple case, zero config.
+queries. Add this package when an agent needs `search` /
+`universal_search`, an app needs to create, sync, or seed indexes, or a
+deployment needs the same AppKit query contract backed by PostgreSQL full-text
+search instead of Vector Search.
 
 **Key features:**
 
-- A small, Meilisearch-shaped client: `client.index("catalog.schema.docs")`,
-  `index.search(query)`, `index.autocomplete(prefix)`, `index.addDocuments(...)`,
-  and `client.universalSearch(query)` to fan a query across many indexes and
-  merge the hits.
-- Hybrid matching by default (semantic similarity fused with BM25 keyword
-  ranking), with `vector` and `keyword` modes when you want one or the other.
+- Vector Search reads delegate to AppKit `aiSearch`, which owns OBO execution,
+  caching, reranking, pagination, route validation, and response decoding.
+- `lakebaseAiSearch()` implements the same `aiSearch` alias, route,
+  client-config, and `SearchResponse` contract with PostgreSQL `tsvector`.
 - Agent tools for both Mastra (`searchTool()` etc.) and AppKit agents (through
-  the plugin's `ToolProvider`): `search` and `universal_search` reads, plus the
-  opt-in write tools `add_documents`, `create_index`, and `sync_index`.
-- HTTP routes under `/api/search` a browser search box calls directly:
-  `POST /` (search), `POST /universal` (federated), `GET /indexes` (catalogue),
-  and, when writes are enabled, `POST /documents` (upsert),
-  `POST /index` (create), and `POST /index/sync` (refresh).
-- A `clientConfig()` payload so a UI knows the indexes, default, and page size at
-  boot with no round-trip (read it with `usePluginClientConfig("search")`).
+  the extension plugin's `ToolProvider`): `search` and `universal_search`
+  reads, plus provider-aware write tools. Lakebase exposes `add_documents`;
+  native Vector Search can also expose `create_index` and `sync_index`.
+- AppKit-compatible query routes under `/api/ai-search/:alias`; extension
+  routes under `/api/search` cover universal search and optional lifecycle
+  operations.
 - Sensible-default config that infers almost everything: name a default index
   (or set `DATABRICKS_VECTOR_SEARCH_INDEX`) and the columns, page size, mode,
   aliases, and route path all have defaults you can override when you need to go
   deeper.
-- OBO throughout: routes wrap in `asUser(req)` and the client resolves the
-  execution-context workspace client, so search runs as the requesting user and
-  Unity Catalog ACLs apply.
-- Filters as plain `{ column: value }` (or `{ column: { ">=": n } }`) compiled to
-  the index `filters_json` for you; the columnar response is unpacked into
-  `{ id, score, fields }` hits.
+- OBO for Vector Search comes from native AppKit `aiSearch`. Lakebase full-text
+  search uses the sibling `lakebase` plugin's service-principal pool.
+- Filters use AppKit's scalar/array shape: `{ column: valueOrValues }`.
 - Embedding-model resolution for index creation reuses
   [`@dbx-tools/model`](../model): a loose name fuzzy-matches the live catalogue,
   or the best embedding endpoint is chosen automatically.
@@ -52,28 +43,24 @@ needs - so search is one plugin and, in the simple case, zero config.
   endpoint + index and seeds documents in the background using the app's SDK
   auth (env or `DATABRICKS_CONFIG_PROFILE`), so a fresh deployment is searchable
   with no manual setup.
-- A **Lakebase full-text fallback**: when no Vector Search endpoint is
-  configured but the AppKit `lakebase` plugin is registered, search transparently
-  runs on a Postgres `tsvector` index instead - same `provision` / `search` /
-  `add_documents` calls, same `{ id, score, fields }` hits, so tools, routes, and
-  the UI can't tell which backend answered. No endpoint, no embeddings, no Delta
-  table - just a table the plugin creates and seeds on boot.
+- An explicit **Lakebase full-text provider**: register `lakebaseAiSearch`
+  instead of native `aiSearch` to serve the same aliases, query routes, filters,
+  and result shape from a Postgres `tsvector` index.
 
 ## Why Use This Over Native AppKit
 
-AppKit exposes Vector Search as a resource type and a low-level serving surface,
-but nothing that makes a search box or an agent tool a one-liner. Use this
-package when you want search to be a drop-in: the friendly client hides the
-verbose `queryIndex` request and columnar response, the plugin gives agents a
-`search` tool and a browser a `POST /api/search` route in one registration,
-universal search fans across indexes, and the config infers everything from a
-single index name. Reach for the raw SDK when you need index lifecycle
-operations this package does not wrap.
+Do not use this package instead of native AppKit for ordinary Vector Search
+queries. Register `aiSearch` from `@databricks/appkit/beta`.
+
+Use this package for capabilities AppKit does not ship: agent tool providers,
+federated fan-out, index lifecycle and seeding, reusable result components, or
+the Lakebase full-text implementation of the AppKit AI Search contract.
 
 ## Quick Start
 
 ```ts
 import { createApp, server } from "@databricks/appkit";
+import { aiSearch } from "@databricks/appkit/beta";
 import { plugin as searchPlugin, tool as searchToolApi } from "@dbx-tools/search";
 import { agents, plugin as mastraPlugin } from "@dbx-tools/appkit-mastra";
 
@@ -85,47 +72,50 @@ const support = agents.createAgent({
 await createApp({
   plugins: [
     server(),
-    // zero-config: reads DATABRICKS_VECTOR_SEARCH_INDEX / SEARCH_INDEX
-    searchPlugin.search(),
+    aiSearch({
+      indexes: {
+        docs: {
+          indexName: "main.support.docs",
+          columns: ["id", "title", "url", "body"],
+        },
+      },
+    }),
+    searchPlugin.search({
+      index: "main.support.docs",
+      indexes: [{ name: "main.support.docs", alias: "docs" }],
+    }),
     mastraPlugin.mastra({ agents: support }),
   ],
 });
 ```
 
-Going deeper:
+Use Lakebase full-text search without changing the AppKit UI hook:
 
 ```ts
-searchPlugin.search({
-  index: "main.support.docs",
-  indexes: [
-    "main.support.docs",
-    { name: "main.catalog.products", alias: "products", columns: ["name", "sku", "price"] },
+import { lakebase } from "@databricks/appkit";
+import { lakebaseAiSearch } from "@dbx-tools/search";
+
+createApp({
+  plugins: [
+    lakebase(),
+    lakebaseAiSearch({
+      indexes: {
+        docs: {
+          indexName: "docs",
+          columns: ["id", "title", "body"],
+          queryType: "full_text",
+        },
+      },
+    }),
   ],
-  columns: ["title", "url", "body"],
-  mode: "hybrid",
-  pageSize: 10,
-  allowWrite: false,
 });
 ```
 
-## Use The Client Directly
-
-```ts
-import { createSearchClient } from "@dbx-tools/search";
-
-const client = createSearchClient();
-const docs = client.index("main.support.docs");
-
-const { hits } = await docs.search("reset my password", { limit: 5 });
-const suggestions = await docs.autocomplete("rese");
-const everywhere = await client.universalSearch("invoice error 402");
-
-await docs.addDocuments([{ id: "42", title: "Reset", body: "…" }]);
-```
-
 ## Manage Indexes
 
-Create and maintain indexes with the same infer-everything ergonomics. A Delta
+`SearchClient` is the lifecycle client; query execution requires the registered
+AppKit-compatible provider. Create and maintain indexes with the same
+infer-everything ergonomics. A Delta
 Sync index computes embeddings from a source Delta table and stays synced; the
 embedding model, endpoint, primary key (`id`), and text column
 (`text`/`content`/`body`) are all inferred when omitted.
@@ -207,16 +197,14 @@ Idempotent: later boots see the endpoint, index, and rows already present and do
 nothing. Point `ensureOnSetup.sourceTable` at a Delta table to provision a Delta
 Sync index instead of a managed direct-access one.
 
-### Lakebase full-text fallback
+### Lakebase full-text provider
 
-When you have **no** Vector Search endpoint configured but the AppKit `lakebase`
-plugin is registered, the plugin transparently falls back to a Postgres
-full-text index. It provisions one table per index (a generated `tsvector`
-column with a GIN index), seeds the same `ensureOnSetup.documents`, and answers
-queries with a prefix `to_tsquery` + `ts_rank`. The pool is built from the
-`lakebase` plugin's service-principal config exactly like
-[`@dbx-tools/appkit-mastra`](../appkit-mastra) builds its memory pool - no auth
-is re-implemented.
+`lakebaseAiSearch()` is an AppKit `aiSearch` provider backed by a Postgres
+full-text index. It provisions one table per alias (a generated `tsvector`
+column with a GIN index), seeds configured documents, and answers queries with
+a prefix `to_tsquery` + `ts_rank`. The pool comes from the native `lakebase`
+plugin's service-principal config, so database authentication is not
+re-implemented.
 
 Queries are compiled from the search box rather than handed to
 `websearch_to_tsquery`, which is too literal for type-ahead in two ways:
@@ -229,40 +217,39 @@ Queries are compiled from the search box rather than handed to
 - **Prefixes.** Every term is matched as a prefix, so `intel` reaches
   `intelligence` and `store intel` finds `racetrac-store-intelligence`.
 
-All terms must match. When none do, the search relaxes instead of returning an
+All terms must match. When none do, search relaxes instead of returning an
 empty box: any single term counts, plus a substring pass that catches a
 fragment which is not a prefix (`telligence`). The substring pass cannot use
 the GIN index, so it only runs after the indexed pass finds nothing.
 
-The point is parity: the client returns the identical `SearchResult` /
-`SearchHit` (`{ id, score, fields }`) / `UpsertResult` shapes, so the agent
-tools, the `/api/search` routes, and the React search box behave the same
-whichever backend is active. Register `lakebase()`, omit `endpoint`, and search
-works with no Vector Search infrastructure:
+The provider returns AppKit's `SearchResponse` and mounts the same
+`/api/ai-search/:alias` query surface. AppKit UI's `useAiSearchQuery` and
+`@dbx-tools/ui-search` work without a backend-specific client:
 
 ```ts
 import { createApp, lakebase } from "@databricks/appkit";
-import { plugin as searchPlugin } from "@dbx-tools/search";
-
-const { search } = searchPlugin;
+import { lakebaseAiSearch } from "@dbx-tools/search";
 
 createApp({
   plugins: [
-    lakebase(), // register it and search uses Postgres full-text
-    search({
-      // no `endpoint` -> Lakebase full-text fallback
-      index: "docs",
-      ensureOnSetup: {
-        documents: [{ id: "1", title: "Overview", text: "Search over Postgres full-text." }],
+    lakebase(),
+    lakebaseAiSearch({
+      indexes: {
+        docs: {
+          indexName: "docs",
+          queryType: "full_text",
+          columns: ["id", "title", "text"],
+          documents: [{ id: "1", title: "Overview", text: "Search over Postgres full-text." }],
+        },
       },
     }),
   ],
 });
 ```
 
-Selection is automatic and logged at boot (`backend: "vector-search"` vs
-`"lakebase"`). Configure an `endpoint` and Vector Search wins; drop it and the
-Lakebase fallback takes over.
+Register either native `aiSearch` for Vector Search or `lakebaseAiSearch` for
+Postgres full text. Both use the registered plugin name `aiSearch`, so they are
+alternatives and must not be registered together.
 
 ## Configuration
 
@@ -279,16 +266,14 @@ default.
 | `mode`           | `SEARCH_MODE`                                    | `hybrid`                | `hybrid` / `vector` / `keyword`.                                                           |
 | `embeddingModel` | `SEARCH_EMBEDDING_MODEL`                         | best embedding endpoint | Embedding endpoint for index creation.                                                     |
 | `timeoutMs`      | `SEARCH_TIMEOUT_MS`                              | `30000`                 | Per-call timeout.                                                                          |
-| `allowWrite`     | `SEARCH_WRITE`                                   | `false`                 | Enable the write tools (`add_documents` / `create_index` / `sync_index`) and their routes. |
-| `ensureOnSetup`  | –                                                | –                       | Provision the endpoint + index and seed documents at boot (background).                    |
+| `allowWrite`     | `SEARCH_WRITE`                                   | `false`                 | Enable provider-supported write tools and routes.                                           |
+| `ensureOnSetup`  | –                                                | –                       | Provision and seed a native Vector Search index at boot.                                    |
 
 ## Modules
 
-- `client` - `SearchClient`, `SearchIndex`, `createSearchClient`, the search
-  methods, and the index lifecycle (`createIndex` / `ensureIndex` / `syncIndex`
-  / `deleteIndex` / `listIndexes` / `ensureEndpoint`), plus the `SearchOptions` /
-  `UniversalSearchOptions` / `IndexInfo` / `CreateIndexOptions` /
-  `EnsureEndpointOptions` types.
+- `client` - `SearchClient`, `SearchIndex`, and the Vector Search lifecycle
+  (`createIndex` / `ensureIndex` / `syncIndex` / `deleteIndex` / `listIndexes`
+  / `ensureEndpoint`), plus provider-backed federated reads.
 - `plugin` - `SearchPlugin` and the `search()` factory (`ToolProvider`,
   routes, `clientConfig`, `exports`).
 - `tool` - the `searchTool()`, `universalSearchTool()`, `addDocumentsTool()`,
@@ -299,11 +284,12 @@ default.
 - `config` - `resolveSearchConfig`, `resolveIndexName`, `SEARCH_CONFIG_SCHEMA`,
   the config env constants, and the `SearchPluginConfig` /
   `ResolvedSearchConfig` types.
-- `query` - `toQueryType`, `compileFilter`, `toHits`, `toRequestColumns`,
-  `toDocumentArray` (contract ↔ serving-API translation).
-- `lakebase` - `LakebaseSearchBackend`, the Postgres full-text FALLBACK used
-  when no Vector Search endpoint is configured (provision + seed + `tsvector`
-  search, same hit shape as Vector Search).
+- `native` - adapter from an AppKit-compatible `aiSearch` provider to the
+  extension tools and universal-search client.
+- `lakebase-plugin` - `lakebaseAiSearch`, the AppKit-compatible PostgreSQL
+  full-text provider.
+- `lakebase` - `LakebaseSearchBackend`, the provider's `tsvector` runtime.
+- `query` - `toDocumentArray`, shared by write routes and tools.
 - `runtime` - `getSearchRuntime` / `resetSearchRuntime` (the shared client).
 - `schema` - the tool descriptions and re-exported request schemas.
 

package/index.ts

@@ -7,19 +7,23 @@ export * as client from "./src/client.ts";
 export * as config from "./src/config.ts";
 export * as indexTools from "./src/index-tools.ts";
 export * as lakebase from "./src/lakebase.ts";
+export * as lakebasePlugin from "./src/lakebase-plugin.ts";
+export * as native from "./src/native.ts";
 export * as plugin from "./src/plugin.ts";
 export * as query from "./src/query.ts";
 export * as runtime from "./src/runtime.ts";
 export * as schema from "./src/schema.ts";
 export * as tool from "./src/tool.ts";
 export { SearchIndex, SearchClient } from "./src/client.ts";
-export type { SearchOptions, UniversalSearchOptions, IndexInfo, CreateIndexOptions, EnsureEndpointOptions, ProvisionOptions } from "./src/client.ts";
+export type { SearchReadBackend, SearchOptions, UniversalSearchOptions, IndexInfo, CreateIndexOptions, EnsureEndpointOptions, ProvisionOptions } from "./src/client.ts";
 export { INDEX_ENV, DATABRICKS_INDEX_ENV, ENDPOINT_ENV, DEFAULT_MODE, DEFAULT_PAGE_SIZE, DEFAULT_TIMEOUT_MS, DEFAULT_BASE_PATH, SEARCH_CONFIG_SCHEMA } from "./src/config.ts";
 export type { SearchIndexConfig, SearchPluginConfig, EnsureOnSetupConfig, ResolvedIndexConfig, ResolvedSearchConfig } from "./src/config.ts";
 export { LakebaseSearchBackend } from "./src/lakebase.ts";
 export type { LakebaseSearchOptions, LakebaseProvisionOptions } from "./src/lakebase.ts";
+export { LakebaseAiSearchPlugin, lakebaseAiSearch } from "./src/lakebase-plugin.ts";
+export type { LakebaseAiSearchIndexConfig, LakebaseAiSearchConfig } from "./src/lakebase-plugin.ts";
+export type { AiSearchProvider } from "./src/native.ts";
 export { SearchPlugin, search } from "./src/plugin.ts";
-export type { QueryResponseLike } from "./src/query.ts";
 export type { SearchRuntimeOptions, SearchRuntime } from "./src/runtime.ts";
 export { SEARCH_TOOL_DESCRIPTION, UNIVERSAL_SEARCH_TOOL_DESCRIPTION, ADD_DOCUMENTS_TOOL_DESCRIPTION, CREATE_INDEX_TOOL_DESCRIPTION, SYNC_INDEX_TOOL_DESCRIPTION, searchToolSchema, universalSearchToolSchema, searchResultSchema, createIndexToolSchema, indexInfoSchema, syncIndexToolSchema } from "./src/schema.ts";
 export type { SearchToolOptions } from "./src/tool.ts";

package/lib/index.d.ts

@@ -3,19 +3,23 @@ export * as client from "./src/client.ts";
 export * as config from "./src/config.ts";
 export * as indexTools from "./src/index-tools.ts";
 export * as lakebase from "./src/lakebase.ts";
+export * as lakebasePlugin from "./src/lakebase-plugin.ts";
+export * as native from "./src/native.ts";
 export * as plugin from "./src/plugin.ts";
 export * as query from "./src/query.ts";
 export * as runtime from "./src/runtime.ts";
 export * as schema from "./src/schema.ts";
 export * as tool from "./src/tool.ts";
 export { SearchIndex, SearchClient } from "./src/client.ts";
-export type { SearchOptions, UniversalSearchOptions, IndexInfo, CreateIndexOptions, EnsureEndpointOptions, ProvisionOptions } from "./src/client.ts";
+export type { SearchReadBackend, SearchOptions, UniversalSearchOptions, IndexInfo, CreateIndexOptions, EnsureEndpointOptions, ProvisionOptions } from "./src/client.ts";
 export { INDEX_ENV, DATABRICKS_INDEX_ENV, ENDPOINT_ENV, DEFAULT_MODE, DEFAULT_PAGE_SIZE, DEFAULT_TIMEOUT_MS, DEFAULT_BASE_PATH, SEARCH_CONFIG_SCHEMA } from "./src/config.ts";
 export type { SearchIndexConfig, SearchPluginConfig, EnsureOnSetupConfig, ResolvedIndexConfig, ResolvedSearchConfig } from "./src/config.ts";
 export { LakebaseSearchBackend } from "./src/lakebase.ts";
 export type { LakebaseSearchOptions, LakebaseProvisionOptions } from "./src/lakebase.ts";
+export { LakebaseAiSearchPlugin, lakebaseAiSearch } from "./src/lakebase-plugin.ts";
+export type { LakebaseAiSearchIndexConfig, LakebaseAiSearchConfig } from "./src/lakebase-plugin.ts";
+export type { AiSearchProvider } from "./src/native.ts";
 export { SearchPlugin, search } from "./src/plugin.ts";
-export type { QueryResponseLike } from "./src/query.ts";
 export type { SearchRuntimeOptions, SearchRuntime } from "./src/runtime.ts";
 export { SEARCH_TOOL_DESCRIPTION, UNIVERSAL_SEARCH_TOOL_DESCRIPTION, ADD_DOCUMENTS_TOOL_DESCRIPTION, CREATE_INDEX_TOOL_DESCRIPTION, SYNC_INDEX_TOOL_DESCRIPTION, searchToolSchema, universalSearchToolSchema, searchResultSchema, createIndexToolSchema, indexInfoSchema, syncIndexToolSchema } from "./src/schema.ts";
 export type { SearchToolOptions } from "./src/tool.ts";

package/lib/index.js

@@ -6,6 +6,8 @@ export * as client from "./src/client.js";
 export * as config from "./src/config.js";
 export * as indexTools from "./src/index-tools.js";
 export * as lakebase from "./src/lakebase.js";
+export * as lakebasePlugin from "./src/lakebase-plugin.js";
+export * as native from "./src/native.js";
 export * as plugin from "./src/plugin.js";
 export * as query from "./src/query.js";
 export * as runtime from "./src/runtime.js";
@@ -14,6 +16,7 @@ export * as tool from "./src/tool.js";
 export { SearchIndex, SearchClient } from "./src/client.js";
 export { INDEX_ENV, DATABRICKS_INDEX_ENV, ENDPOINT_ENV, DEFAULT_MODE, DEFAULT_PAGE_SIZE, DEFAULT_TIMEOUT_MS, DEFAULT_BASE_PATH, SEARCH_CONFIG_SCHEMA } from "./src/config.js";
 export { LakebaseSearchBackend } from "./src/lakebase.js";
+export { LakebaseAiSearchPlugin, lakebaseAiSearch } from "./src/lakebase-plugin.js";
 export { SearchPlugin, search } from "./src/plugin.js";
 export { SEARCH_TOOL_DESCRIPTION, UNIVERSAL_SEARCH_TOOL_DESCRIPTION, ADD_DOCUMENTS_TOOL_DESCRIPTION, CREATE_INDEX_TOOL_DESCRIPTION, SYNC_INDEX_TOOL_DESCRIPTION, searchToolSchema, universalSearchToolSchema, searchResultSchema, createIndexToolSchema, indexInfoSchema, syncIndexToolSchema } from "./src/schema.js";
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSwyQ0FBMkM7QUFDM0MsbURBQW1EO0FBQ25ELHdFQUF3RTtBQUV4RSxNQUFNLENBQUMsTUFBTSxrQkFBa0IsR0FBRyxtQkFBbUIsQ0FBQztBQUN0RCxPQUFPLEtBQUssTUFBTSxNQUFNLGlCQUFpQixDQUFDO0FBQzFDLE9BQU8sS0FBSyxNQUFNLE1BQU0saUJBQWlCLENBQUM7QUFDMUMsT0FBTyxLQUFLLFVBQVUsTUFBTSxzQkFBc0IsQ0FBQztBQUNuRCxPQUFPLEtBQUssUUFBUSxNQUFNLG1CQUFtQixDQUFDO0FBQzlDLE9BQU8sS0FBSyxNQUFNLE1BQU0saUJBQWlCLENBQUM7QUFDMUMsT0FBTyxLQUFLLEtBQUssTUFBTSxnQkFBZ0IsQ0FBQztBQUN4QyxPQUFPLEtBQUssT0FBTyxNQUFNLGtCQUFrQixDQUFDO0FBQzVDLE9BQU8sS0FBSyxNQUFNLE1BQU0saUJBQWlCLENBQUM7QUFDMUMsT0FBTyxLQUFLLElBQUksTUFBTSxlQUFlLENBQUM7QUFDdEMsT0FBTyxFQUFFLFdBQVcsRUFBRSxZQUFZLEVBQUUsTUFBTSxpQkFBaUIsQ0FBQztBQUU1RCxPQUFPLEVBQUUsU0FBUyxFQUFFLG9CQUFvQixFQUFFLFlBQVksRUFBRSxZQUFZLEVBQUUsaUJBQWlCLEVBQUUsa0JBQWtCLEVBQUUsaUJBQWlCLEVBQUUsb0JBQW9CLEVBQUUsTUFBTSxpQkFBaUIsQ0FBQztBQUU5SyxPQUFPLEVBQUUscUJBQXFCLEVBQUUsTUFBTSxtQkFBbUIsQ0FBQztBQUUxRCxPQUFPLEVBQUUsWUFBWSxFQUFFLE1BQU0sRUFBRSxNQUFNLGlCQUFpQixDQUFDO0FBR3ZELE9BQU8sRUFBRSx1QkFBdUIsRUFBRSxpQ0FBaUMsRUFBRSw4QkFBOEIsRUFBRSw2QkFBNkIsRUFBRSwyQkFBMkIsRUFBRSxnQkFBZ0IsRUFBRSx5QkFBeUIsRUFBRSxrQkFBa0IsRUFBRSxxQkFBcUIsRUFBRSxlQUFlLEVBQUUsbUJBQW1CLEVBQUUsTUFBTSxpQkFBaUIsQ0FBQyIsInNvdXJjZXNDb250ZW50IjpbIi8vIEdFTkVSQVRFRCBieSBwcm9qZW4gd2F0Y2ggLSBETyBOT1QgRURJVC5cbi8vIFJlZ2VuZXJhdGVkIGZyb20gdGhlIGV4cG9ydGluZyBtb2R1bGVzIGluIC4vc3JjLlxuLy8gSGFuZCBlZGl0cyBhcmUgb3ZlcndyaXR0ZW4gb24gdGhlIG5leHQgd2F0Y2g7IHRoaXMgZmlsZSBpcyByZWFkLW9ubHkuXG5cbmV4cG9ydCBjb25zdCBQQUNLQUdFX0lERU5USUZJRVIgPSBcIkBkYngtdG9vbHMvc2VhcmNoXCI7XG5leHBvcnQgKiBhcyBjbGllbnQgZnJvbSBcIi4vc3JjL2NsaWVudC50c1wiO1xuZXhwb3J0ICogYXMgY29uZmlnIGZyb20gXCIuL3NyYy9jb25maWcudHNcIjtcbmV4cG9ydCAqIGFzIGluZGV4VG9vbHMgZnJvbSBcIi4vc3JjL2luZGV4LXRvb2xzLnRzXCI7XG5leHBvcnQgKiBhcyBsYWtlYmFzZSBmcm9tIFwiLi9zcmMvbGFrZWJhc2UudHNcIjtcbmV4cG9ydCAqIGFzIHBsdWdpbiBmcm9tIFwiLi9zcmMvcGx1Z2luLnRzXCI7XG5leHBvcnQgKiBhcyBxdWVyeSBmcm9tIFwiLi9zcmMvcXVlcnkudHNcIjtcbmV4cG9ydCAqIGFzIHJ1bnRpbWUgZnJvbSBcIi4vc3JjL3J1bnRpbWUudHNcIjtcbmV4cG9ydCAqIGFzIHNjaGVtYSBmcm9tIFwiLi9zcmMvc2NoZW1hLnRzXCI7XG5leHBvcnQgKiBhcyB0b29sIGZyb20gXCIuL3NyYy90b29sLnRzXCI7XG5leHBvcnQgeyBTZWFyY2hJbmRleCwgU2VhcmNoQ2xpZW50IH0gZnJvbSBcIi4vc3JjL2NsaWVudC50c1wiO1xuZXhwb3J0IHR5cGUgeyBTZWFyY2hPcHRpb25zLCBVbml2ZXJzYWxTZWFyY2hPcHRpb25zLCBJbmRleEluZm8sIENyZWF0ZUluZGV4T3B0aW9ucywgRW5zdXJlRW5kcG9pbnRPcHRpb25zLCBQcm92aXNpb25PcHRpb25zIH0gZnJvbSBcIi4vc3JjL2NsaWVudC50c1wiO1xuZXhwb3J0IHsgSU5ERVhfRU5WLCBEQVRBQlJJQ0tTX0lOREVYX0VOViwgRU5EUE9JTlRfRU5WLCBERUZBVUxUX01PREUsIERFRkFVTFRfUEFHRV9TSVpFLCBERUZBVUxUX1RJTUVPVVRfTVMsIERFRkFVTFRfQkFTRV9QQVRILCBTRUFSQ0hfQ09ORklHX1NDSEVNQSB9IGZyb20gXCIuL3NyYy9jb25maWcudHNcIjtcbmV4cG9ydCB0eXBlIHsgU2VhcmNoSW5kZXhDb25maWcsIFNlYXJjaFBsdWdpbkNvbmZpZywgRW5zdXJlT25TZXR1cENvbmZpZywgUmVzb2x2ZWRJbmRleENvbmZpZywgUmVzb2x2ZWRTZWFyY2hDb25maWcgfSBmcm9tIFwiLi9zcmMvY29uZmlnLnRzXCI7XG5leHBvcnQgeyBMYWtlYmFzZVNlYXJjaEJhY2tlbmQgfSBmcm9tIFwiLi9zcmMvbGFrZWJhc2UudHNcIjtcbmV4cG9ydCB0eXBlIHsgTGFrZWJhc2VTZWFyY2hPcHRpb25zLCBMYWtlYmFzZVByb3Zpc2lvbk9wdGlvbnMgfSBmcm9tIFwiLi9zcmMvbGFrZWJhc2UudHNcIjtcbmV4cG9ydCB7IFNlYXJjaFBsdWdpbiwgc2VhcmNoIH0gZnJvbSBcIi4vc3JjL3BsdWdpbi50c1wiO1xuZXhwb3J0IHR5cGUgeyBRdWVyeVJlc3BvbnNlTGlrZSB9IGZyb20gXCIuL3NyYy9xdWVyeS50c1wiO1xuZXhwb3J0IHR5cGUgeyBTZWFyY2hSdW50aW1lT3B0aW9ucywgU2VhcmNoUnVudGltZSB9IGZyb20gXCIuL3NyYy9ydW50aW1lLnRzXCI7XG5leHBvcnQgeyBTRUFSQ0hfVE9PTF9ERVNDUklQVElPTiwgVU5JVkVSU0FMX1NFQVJDSF9UT09MX0RFU0NSSVBUSU9OLCBBRERfRE9DVU1FTlRTX1RPT0xfREVTQ1JJUFRJT04sIENSRUFURV9JTkRFWF9UT09MX0RFU0NSSVBUSU9OLCBTWU5DX0lOREVYX1RPT0xfREVTQ1JJUFRJT04sIHNlYXJjaFRvb2xTY2hlbWEsIHVuaXZlcnNhbFNlYXJjaFRvb2xTY2hlbWEsIHNlYXJjaFJlc3VsdFNjaGVtYSwgY3JlYXRlSW5kZXhUb29sU2NoZW1hLCBpbmRleEluZm9TY2hlbWEsIHN5bmNJbmRleFRvb2xTY2hlbWEgfSBmcm9tIFwiLi9zcmMvc2NoZW1hLnRzXCI7XG5leHBvcnQgdHlwZSB7IFNlYXJjaFRvb2xPcHRpb25zIH0gZnJvbSBcIi4vc3JjL3Rvb2wudHNcIjtcbiJdfQ==
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSwyQ0FBMkM7QUFDM0MsbURBQW1EO0FBQ25ELHdFQUF3RTtBQUV4RSxNQUFNLENBQUMsTUFBTSxrQkFBa0IsR0FBRyxtQkFBbUIsQ0FBQztBQUN0RCxPQUFPLEtBQUssTUFBTSxNQUFNLGlCQUFpQixDQUFDO0FBQzFDLE9BQU8sS0FBSyxNQUFNLE1BQU0saUJBQWlCLENBQUM7QUFDMUMsT0FBTyxLQUFLLFVBQVUsTUFBTSxzQkFBc0IsQ0FBQztBQUNuRCxPQUFPLEtBQUssUUFBUSxNQUFNLG1CQUFtQixDQUFDO0FBQzlDLE9BQU8sS0FBSyxjQUFjLE1BQU0sMEJBQTBCLENBQUM7QUFDM0QsT0FBTyxLQUFLLE1BQU0sTUFBTSxpQkFBaUIsQ0FBQztBQUMxQyxPQUFPLEtBQUssTUFBTSxNQUFNLGlCQUFpQixDQUFDO0FBQzFDLE9BQU8sS0FBSyxLQUFLLE1BQU0sZ0JBQWdCLENBQUM7QUFDeEMsT0FBTyxLQUFLLE9BQU8sTUFBTSxrQkFBa0IsQ0FBQztBQUM1QyxPQUFPLEtBQUssTUFBTSxNQUFNLGlCQUFpQixDQUFDO0FBQzFDLE9BQU8sS0FBSyxJQUFJLE1BQU0sZUFBZSxDQUFDO0FBQ3RDLE9BQU8sRUFBRSxXQUFXLEVBQUUsWUFBWSxFQUFFLE1BQU0saUJBQWlCLENBQUM7QUFFNUQsT0FBTyxFQUFFLFNBQVMsRUFBRSxvQkFBb0IsRUFBRSxZQUFZLEVBQUUsWUFBWSxFQUFFLGlCQUFpQixFQUFFLGtCQUFrQixFQUFFLGlCQUFpQixFQUFFLG9CQUFvQixFQUFFLE1BQU0saUJBQWlCLENBQUM7QUFFOUssT0FBTyxFQUFFLHFCQUFxQixFQUFFLE1BQU0sbUJBQW1CLENBQUM7QUFFMUQsT0FBTyxFQUFFLHNCQUFzQixFQUFFLGdCQUFnQixFQUFFLE1BQU0sMEJBQTBCLENBQUM7QUFHcEYsT0FBTyxFQUFFLFlBQVksRUFBRSxNQUFNLEVBQUUsTUFBTSxpQkFBaUIsQ0FBQztBQUV2RCxPQUFPLEVBQUUsdUJBQXVCLEVBQUUsaUNBQWlDLEVBQUUsOEJBQThCLEVBQUUsNkJBQTZCLEVBQUUsMkJBQTJCLEVBQUUsZ0JBQWdCLEVBQUUseUJBQXlCLEVBQUUsa0JBQWtCLEVBQUUscUJBQXFCLEVBQUUsZUFBZSxFQUFFLG1CQUFtQixFQUFFLE1BQU0saUJBQWlCLENBQUMiLCJzb3VyY2VzQ29udGVudCI6WyIvLyBHRU5FUkFURUQgYnkgcHJvamVuIHdhdGNoIC0gRE8gTk9UIEVESVQuXG4vLyBSZWdlbmVyYXRlZCBmcm9tIHRoZSBleHBvcnRpbmcgbW9kdWxlcyBpbiAuL3NyYy5cbi8vIEhhbmQgZWRpdHMgYXJlIG92ZXJ3cml0dGVuIG9uIHRoZSBuZXh0IHdhdGNoOyB0aGlzIGZpbGUgaXMgcmVhZC1vbmx5LlxuXG5leHBvcnQgY29uc3QgUEFDS0FHRV9JREVOVElGSUVSID0gXCJAZGJ4LXRvb2xzL3NlYXJjaFwiO1xuZXhwb3J0ICogYXMgY2xpZW50IGZyb20gXCIuL3NyYy9jbGllbnQudHNcIjtcbmV4cG9ydCAqIGFzIGNvbmZpZyBmcm9tIFwiLi9zcmMvY29uZmlnLnRzXCI7XG5leHBvcnQgKiBhcyBpbmRleFRvb2xzIGZyb20gXCIuL3NyYy9pbmRleC10b29scy50c1wiO1xuZXhwb3J0ICogYXMgbGFrZWJhc2UgZnJvbSBcIi4vc3JjL2xha2ViYXNlLnRzXCI7XG5leHBvcnQgKiBhcyBsYWtlYmFzZVBsdWdpbiBmcm9tIFwiLi9zcmMvbGFrZWJhc2UtcGx1Z2luLnRzXCI7XG5leHBvcnQgKiBhcyBuYXRpdmUgZnJvbSBcIi4vc3JjL25hdGl2ZS50c1wiO1xuZXhwb3J0ICogYXMgcGx1Z2luIGZyb20gXCIuL3NyYy9wbHVnaW4udHNcIjtcbmV4cG9ydCAqIGFzIHF1ZXJ5IGZyb20gXCIuL3NyYy9xdWVyeS50c1wiO1xuZXhwb3J0ICogYXMgcnVudGltZSBmcm9tIFwiLi9zcmMvcnVudGltZS50c1wiO1xuZXhwb3J0ICogYXMgc2NoZW1hIGZyb20gXCIuL3NyYy9zY2hlbWEudHNcIjtcbmV4cG9ydCAqIGFzIHRvb2wgZnJvbSBcIi4vc3JjL3Rvb2wudHNcIjtcbmV4cG9ydCB7IFNlYXJjaEluZGV4LCBTZWFyY2hDbGllbnQgfSBmcm9tIFwiLi9zcmMvY2xpZW50LnRzXCI7XG5leHBvcnQgdHlwZSB7IFNlYXJjaFJlYWRCYWNrZW5kLCBTZWFyY2hPcHRpb25zLCBVbml2ZXJzYWxTZWFyY2hPcHRpb25zLCBJbmRleEluZm8sIENyZWF0ZUluZGV4T3B0aW9ucywgRW5zdXJlRW5kcG9pbnRPcHRpb25zLCBQcm92aXNpb25PcHRpb25zIH0gZnJvbSBcIi4vc3JjL2NsaWVudC50c1wiO1xuZXhwb3J0IHsgSU5ERVhfRU5WLCBEQVRBQlJJQ0tTX0lOREVYX0VOViwgRU5EUE9JTlRfRU5WLCBERUZBVUxUX01PREUsIERFRkFVTFRfUEFHRV9TSVpFLCBERUZBVUxUX1RJTUVPVVRfTVMsIERFRkFVTFRfQkFTRV9QQVRILCBTRUFSQ0hfQ09ORklHX1NDSEVNQSB9IGZyb20gXCIuL3NyYy9jb25maWcudHNcIjtcbmV4cG9ydCB0eXBlIHsgU2VhcmNoSW5kZXhDb25maWcsIFNlYXJjaFBsdWdpbkNvbmZpZywgRW5zdXJlT25TZXR1cENvbmZpZywgUmVzb2x2ZWRJbmRleENvbmZpZywgUmVzb2x2ZWRTZWFyY2hDb25maWcgfSBmcm9tIFwiLi9zcmMvY29uZmlnLnRzXCI7XG5leHBvcnQgeyBMYWtlYmFzZVNlYXJjaEJhY2tlbmQgfSBmcm9tIFwiLi9zcmMvbGFrZWJhc2UudHNcIjtcbmV4cG9ydCB0eXBlIHsgTGFrZWJhc2VTZWFyY2hPcHRpb25zLCBMYWtlYmFzZVByb3Zpc2lvbk9wdGlvbnMgfSBmcm9tIFwiLi9zcmMvbGFrZWJhc2UudHNcIjtcbmV4cG9ydCB7IExha2ViYXNlQWlTZWFyY2hQbHVnaW4sIGxha2ViYXNlQWlTZWFyY2ggfSBmcm9tIFwiLi9zcmMvbGFrZWJhc2UtcGx1Z2luLnRzXCI7XG5leHBvcnQgdHlwZSB7IExha2ViYXNlQWlTZWFyY2hJbmRleENvbmZpZywgTGFrZWJhc2VBaVNlYXJjaENvbmZpZyB9IGZyb20gXCIuL3NyYy9sYWtlYmFzZS1wbHVnaW4udHNcIjtcbmV4cG9ydCB0eXBlIHsgQWlTZWFyY2hQcm92aWRlciB9IGZyb20gXCIuL3NyYy9uYXRpdmUudHNcIjtcbmV4cG9ydCB7IFNlYXJjaFBsdWdpbiwgc2VhcmNoIH0gZnJvbSBcIi4vc3JjL3BsdWdpbi50c1wiO1xuZXhwb3J0IHR5cGUgeyBTZWFyY2hSdW50aW1lT3B0aW9ucywgU2VhcmNoUnVudGltZSB9IGZyb20gXCIuL3NyYy9ydW50aW1lLnRzXCI7XG5leHBvcnQgeyBTRUFSQ0hfVE9PTF9ERVNDUklQVElPTiwgVU5JVkVSU0FMX1NFQVJDSF9UT09MX0RFU0NSSVBUSU9OLCBBRERfRE9DVU1FTlRTX1RPT0xfREVTQ1JJUFRJT04sIENSRUFURV9JTkRFWF9UT09MX0RFU0NSSVBUSU9OLCBTWU5DX0lOREVYX1RPT0xfREVTQ1JJUFRJT04sIHNlYXJjaFRvb2xTY2hlbWEsIHVuaXZlcnNhbFNlYXJjaFRvb2xTY2hlbWEsIHNlYXJjaFJlc3VsdFNjaGVtYSwgY3JlYXRlSW5kZXhUb29sU2NoZW1hLCBpbmRleEluZm9TY2hlbWEsIHN5bmNJbmRleFRvb2xTY2hlbWEgfSBmcm9tIFwiLi9zcmMvc2NoZW1hLnRzXCI7XG5leHBvcnQgdHlwZSB7IFNlYXJjaFRvb2xPcHRpb25zIH0gZnJvbSBcIi4vc3JjL3Rvb2wudHNcIjtcbiJdfQ==

package/lib/src/client.d.ts

@@ -1,25 +1,16 @@
 /**
- * A small, Meilisearch-shaped client over Databricks AI Search (Vector
- * Search). The whole point of this module is ergonomics: the Databricks SDK's
- * `vectorSearchIndexes.queryIndex({ index_name, columns, query_text,
- * query_type, num_results, filters_json })` is powerful but verbose, and the
- * response is columnar. This client hides all of that behind two objects:
- *
- * ```ts
- * const client = createSearchClient();
- * const index = client.index("main.support.docs");
- * const { hits } = await index.search("reset my password", { limit: 5 });
- * await index.addDocuments([{ id: "42", title: "Reset", body: "..." }]);
- * ```
+ * Search extension client. Reads delegate to the registered AppKit-compatible
+ * `aiSearch` provider; this module owns federated fan-out and the Vector Search
+ * lifecycle APIs AppKit does not expose.
  *
  * `client.search(query, opts)` searches the default index; `client.index(name)`
  * returns a handle bound to one index; `client.universalSearch(query)` fans a
  * query across several indexes and merges the results (Meilisearch's federated
  * / multi-search, the "universal search" the caller asked for). Everything is
- * async and cancellable, resolves the OBO workspace client from the active
- * AppKit execution context (falling back to a service-principal client outside
- * a request), and returns the browser-safe shapes from
- * `@dbx-tools/shared-search`.
+ * async and cancellable and returns the browser-safe shapes from
+ * `@dbx-tools/shared-search`. Lifecycle methods cross AppKit's explicit legacy
+ * client handoff because the public facade does not yet expose index creation,
+ * sync, or deletion.
  *
  * Autocomplete is just a search with a small `limit` and the raw query text -
  * hybrid mode already prefix-matches, so no separate endpoint is needed; the
@@ -28,10 +19,16 @@
  * @module
  */
 import { appkit } from "@dbx-tools/appkit";
-import type { SearchDocument, SearchMode, SearchResult, UpsertResult } from "@dbx-tools/shared-search";
+import type { SearchDocument, SearchMode, SearchRequest, SearchResult, UpsertResult } from "@dbx-tools/shared-search";
 import { type ResolvedSearchConfig } from "./config.ts";
-import type { LakebaseSearchBackend } from "./lakebase.ts";
-type WorkspaceClientLike = appkit.WorkspaceClientLike;
+type WorkspaceClientLike = ReturnType<appkit.WorkspaceClientLike["toLegacyWorkspaceClient"]>;
+/** Query backend used when AppKit owns the Vector Search execution path. */
+export interface SearchReadBackend {
+    /** Whether Vector Search lifecycle methods are valid for this provider. */
+    supportsLifecycle: boolean;
+    search(index: string, query: string, options?: SearchOptions): Promise<SearchResult>;
+    addDocuments?(index: string, documents: SearchDocument[], signal?: AbortSignal): Promise<UpsertResult>;
+}
 /** Options accepted by a single-index search. */
 export interface SearchOptions {
     /** Maximum hits to return. Defaults to the configured page size. */
@@ -40,8 +37,8 @@ export interface SearchOptions {
     mode?: SearchMode;
     /** Columns to return per hit. Defaults to the index's configured columns. */
     columns?: readonly string[];
-    /** Attribute filters as `{ column: value }` or `{ column: { ">=": n } }`. */
-    filter?: Record<string, unknown>;
+    /** AppKit AI Search scalar/array filters. */
+    filter?: SearchRequest["filter"];
     /** Drop hits below this score. */
     scoreThreshold?: number;
     /** External cancellation. */
@@ -178,23 +175,8 @@ export interface ProvisionOptions extends CreateIndexOptions {
 export declare class SearchClient {
     private readonly config;
     private readonly workspaceClientFactory;
-    /**
-     * Optional Lakebase full-text FALLBACK backend. Present only when no Vector
-     * Search endpoint is configured but a Lakebase pool is available; when set,
-     * search / provision / write operations delegate to it and return the exact
-     * same shapes, so nothing downstream can tell which backend answered.
-     */
-    private readonly lakebase?;
-    constructor(config?: ResolvedSearchConfig, workspaceClientFactory?: () => WorkspaceClientLike, 
-    /**
-     * Optional Lakebase full-text FALLBACK backend. Present only when no Vector
-     * Search endpoint is configured but a Lakebase pool is available; when set,
-     * search / provision / write operations delegate to it and return the exact
-     * same shapes, so nothing downstream can tell which backend answered.
-     */
-    lakebase?: LakebaseSearchBackend | undefined);
-    /** True when this client is answering out of the Lakebase fallback backend. */
-    get usesLakebase(): boolean;
+    private readonly readBackend?;
+    constructor(config?: ResolvedSearchConfig, workspaceClientFactory?: () => WorkspaceClientLike, readBackend?: SearchReadBackend | undefined);
     /** A handle bound to one index (by full UC name or configured alias). */
     index(reference: string): SearchIndex;
     /**
@@ -204,10 +186,6 @@ export declare class SearchClient {
     search(query: string, options?: SearchOptions & {
         index?: string;
     }): Promise<SearchResult>;
-    /** Cache of index-name -> is-DIRECT_ACCESS, so a search embeds its query only when needed. */
-    private readonly directAccessCache;
-    /** Whether an index is DIRECT_ACCESS (memoized); a lookup failure assumes Delta Sync. */
-    private isDirectAccess;
     /**
      * Fan a query across several indexes and merge the hits, sorted by score -
      * the "universal search" a single box over many collections needs. Each
@@ -224,6 +202,8 @@ export declare class SearchClient {
      * `ENDPOINT_NOT_FOUND` instead of naming the real problem.
      */
     private requireIndexName;
+    /** Reject Vector Search lifecycle calls against a non-Vector provider. */
+    private requireLifecycle;
     /** Fetch an index's live definition. */
     getIndex(reference: string, signal?: AbortSignal): Promise<IndexInfo>;
     /** Add or update documents in a direct-access index. */
@@ -300,5 +280,5 @@ export declare class SearchClient {
     private withClient;
 }
 /** Construct a {@link SearchClient} from a resolved config. */
-export declare function createSearchClient(config?: ResolvedSearchConfig, workspaceClientFactory?: () => WorkspaceClientLike, lakebase?: LakebaseSearchBackend): SearchClient;
+export declare function createSearchClient(config?: ResolvedSearchConfig, workspaceClientFactory?: () => WorkspaceClientLike, readBackend?: SearchReadBackend): SearchClient;
 export {};