@functional-systems/lambdadb-mcp 0.1.3-dev.10 → 0.1.3-dev.11

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+- Pin the stable LambdaDB SDK to 0.8.0; expose Bayesian candidate budgets and
+  native embedding configuration in MCP guidance while preserving free-form
+  queries, SDK/server validation, rerank defaults, errors and response metadata.
+- Retain legacy `managedEmbedding: true` and existing tool names/inputs. Native
+  embedding-only requests require a supporting server; no defaults are promoted.
+- Add Bayesian/native contract tests, installed-package coverage, practical MCP
+  examples and an opt-in live suite with verified temporary-collection cleanup.
+
 ## [0.1.2] - 2026-10-04
 
 - Pin the LambdaDB TypeScript SDK to 0.7.0 and expose all 49 fixed lowercase

package/README.md

@@ -103,8 +103,8 @@ Optional write tools:
 
 ## API contract and tool inputs
 
-The LambdaDB SDK is pinned to `@functional-systems/lambdadb@0.7.0`, checked against
-the published package and [v0.7.0 release](https://github.com/lambdadb/lambdadb-typescript-client/releases/tag/v0.7.0).
+The LambdaDB SDK is pinned to `@functional-systems/lambdadb@0.8.0`, checked against
+the published package and [v0.8.0 release](https://github.com/lambdadb/lambdadb-typescript-client/releases/tag/v0.8.0).
 This dependency update applies to builds containing this change. Publishing the SDK
 alone does not update previously published or installed MCP packages.
 
@@ -174,6 +174,114 @@ This MCP update does not migrate existing Collections or indexes. Partial update
 segment merging, and old Tags do not upgrade old indexes. If migration is needed,
 plan and authorize reinsertion into a new Collection separately.
 
+### Bayesian hybrid search
+
+Arguments for `lambdadb_query_collection` using an existing two-dimensional
+caller-provided vector field `embedding` and text field `body`:
+
+```json
+{
+  "collectionName": "articles",
+  "query": {
+    "bayesian": [
+      { "queryString": { "query": "body:restore" } },
+      { "knn": { "field": "embedding", "queryVector": [1, 0], "k": 30 } }
+    ]
+  },
+  "size": 10,
+  "candidateSize": 30
+}
+```
+
+Bayesian requires exactly two signals. Boolean subqueries may combine clauses
+within a signal, but explicit boosts (even `1`) on either signal or its Boolean
+descendants and nested rank-fusion queries are unsupported. Do not supply fusion
+weights. Without rerank, top-level `candidateSize` is required and must satisfy
+`1 <= size <= candidateSize <= 100`; omitted `size` retains the server default of
+10. The budget is per signal, independent of final output size and `knn.k`.
+
+With rerank, omit top-level `candidateSize` and use `rerank.candidateSize`:
+
+```json
+{
+  "collectionName": "articles",
+  "query": {
+    "bayesian": [
+      { "queryString": { "query": "body:restore" } },
+      { "knn": { "field": "embedding", "queryVector": [1, 0], "k": 30 } }
+    ]
+  },
+  "size": 10,
+  "rerank": {
+    "provider": "typesafe",
+    "model": "jev-1.13.0",
+    "queryText": "How do I restore a previous version?",
+    "fields": ["body"],
+    "candidateSize": 30
+  }
+}
+```
+
+Omitted/null `rerank.candidateSize` retains `max(50, size)`; omitted/null `rerank`
+requires the top-level Bayesian budget. Ordinary text/KNN/RRF/Min-Max/L2 queries
+must omit top-level `candidateSize`. MCP preserves free-form queries, passes
+integer candidate budgets unchanged, and leaves Bayesian structure, bounds and
+cross-field validation to the server, retaining service errors. No query defaults,
+weights or candidate counts are inserted by MCP. Bayesian scores are heuristic
+fusion scores; applied reranking preserves them in `retrievalScore` and retains
+all rerank status metadata, including through SDK-managed `docsUrl` downloads.
+
+The [Bayesian contract](https://github.com/lambdadb/lambdadb-typescript-client/blob/v0.8.0/docs/bayesian-search.md)
+and native embedding additions below are pinned to backend
+`9072a1bc8925954369a887f558f1eaf387b7ea0e`. A source pin does not establish deployment
+in another environment. Existing fusion methods and tool names remain unchanged.
+
+### Native embedding configuration
+
+With write tools enabled, call `lambdadb_create_collection` with:
+
+```json
+{
+  "collectionName": "native-articles",
+  "indexConfigs": {
+    "body": { "type": "text" },
+    "embedding": {
+      "type": "vector",
+      "embedding": {
+        "provider": "openai",
+        "model": "text-embedding-3-small",
+        "sourceField": "body",
+        "dimensions": 512,
+        "similarity": "cosine"
+      }
+    }
+  }
+}
+```
+
+Then call `lambdadb_upsert_docs` with
+`{"collectionName":"native-articles","docs":[{"id":"one","body":"Restore a saved version."}]}`.
+The source must be a text field; omit the generated vector from documents.
+Use `knn.queryText` instead of `queryVector` for this field, including in either
+Bayesian example above. For example, call `lambdadb_query_collection` with:
+
+```json
+{
+  "collectionName": "native-articles",
+  "query": { "knn": { "field": "embedding", "queryText": "Restore a version", "k": 30 } },
+  "size": 10
+}
+```
+
+Native dimensions and similarity are optional and belong inside `embedding`.
+MCP does not infer a flag, provider, model or native dimensions/similarity default.
+The SDK rejects `managedEmbedding: false` with `embedding`, and native embedding
+with top-level dimensions/similarity. Caller-provided vectors continue to use
+top-level dimensions/similarity. Free-form nested object configurations retain
+server validation. For older servers, explicitly add `managedEmbedding: true`
+beside `type`; it is preserved. Normalized collection metadata may still contain
+that true flag. See the [native embedding contract](https://github.com/lambdadb/lambdadb-typescript-client/blob/v0.8.0/docs/native-embeddings.md).
+
 ### Optional managed reranking
 
 `lambdadb_query_collection` accepts per-query `rerank`; omission or `null`
@@ -205,7 +313,7 @@ Optional `criteria` replaces the default with 2–10 distinct nonblank descripti
 ordered from lowest to highest relevance (2 KiB each, 8 KiB total UTF-8).
 Omitted/null criteria uses defaults; text, order, nulls and omission are preserved.
 
-Final `size`, vector-leg `knn.k`, and merged `candidateSize` are separate.
+Final `size`, vector-leg `knn.k`, and merged `rerank.candidateSize` are separate.
 Require `1 <= size <= candidateSize <= 100`; omitted/null candidateSize defaults
 on the server to `max(50, size)`, with final size defaulting to 10. MCP never
 increases `k`. Reranking requires a scoring retrieval query, forbids `sort`,
@@ -294,7 +402,9 @@ MCP JSON Schema and actual tool-to-SDK HTTP path, including match-all, facet-onl
 document+facet, omitted/null/default bucket options, boundaries, invalid requests,
 and all 49 analyzers. Rerank tests cover JSON Schema, request preservation,
 local bounds/UTF-8 rejection, score envelopes, skipped/fallback results and
-metadata downloads. They do not require credentials
+metadata downloads. Bayesian tests cover untouched free-form requests, candidate
+budgets, server errors, native/legacy configurations and contradictory inputs.
+They do not require credentials
 or create remote collections. `test:package` additionally installs the actual
 tarball in a clean consumer directory and repeats the tool contracts over real
 stdio, checking version identity, config errors, stdout and process termination.
@@ -340,9 +450,23 @@ Cleanup deletes the collection and verifies its absence even after a failed chec
 It does not assert fixed model scores or relevance rankings, and a fallback result
 does not pass as applied inference. Provider failures remain fixture tests; this
 suite does not deliberately induce failures or verify search quality, load,
-production deployment or billing readiness. Both live suites are outside default
+production deployment or billing readiness. These live suites are outside default
 checks and credential-free CI.
 
+Bayesian/native embedding verification also requires explicit managed inference
+opt-in for OpenAI embeddings and TypeSafe reranking:
+
+```bash
+LAMBDADB_RUN_LIVE_TESTS=1 LAMBDADB_RUN_LIVE_RERANK_TESTS=1 LAMBDADB_LIVE_CONFIRM_PROJECT=YOUR_DEV_PROJECT npm run test:live:bayesian
+```
+
+This suite creates one owned collection with native, legacy and caller-provided
+vector fields. It checks real embedding generation and text queries, Bayesian
+budgets and server rejections, existing fusion methods, applied reranking with
+retrieval scores and actual docsUrl hydration, then deletes and verifies absence.
+These live suites are outside default checks and credential-free CI. Verify the
+target's deployment provenance before running; the source pin alone is insufficient.
+
 If the environment file is outside the worktree:
 
 ```bash

package/dist/tools/read.js

@@ -68,7 +68,7 @@ export function registerReadTools(server, config) {
     });
     server.registerTool("lambdadb_query_collection", {
         title: "Query Collection",
-        description: "Search documents with optional managed reranking and keyword facet counts across all matches. Omit query for match-all; size: 0 requires facets and forbids reranking. Reranking requires a scoring query and forbids sort; it does not enable vector/hybrid facets. Applied envelope score is an evaluation score, retrievalScore preserves search score, and rerank metadata reports status. Features require a supporting server; facets require newly built keyword indexes.",
+        description: "Search documents with optional Bayesian hybrid search, managed reranking and keyword facet counts across all matches. Omit query for match-all; size: 0 requires facets and forbids reranking. Reranking requires a scoring query and forbids sort; it does not enable vector/hybrid facets. Applied envelope score is an evaluation score, retrievalScore preserves search score, and rerank metadata reports status. Features require a supporting server; facets require newly built keyword indexes.",
         annotations: {
             readOnlyHint: true,
             openWorldHint: false
@@ -77,7 +77,9 @@ export function registerReadTools(server, config) {
             collectionName: nameSchema,
             size: z.number().int().min(0).max(100).optional()
                 .describe("Documents to return (1–100), or 0 with nonempty facets."),
-            query: z.record(z.string(), z.any()).optional().describe("Omit for match-all."),
+            // Preserve SDK/server validation and error classification for free-form queries.
+            candidateSize: z.number().int().optional().describe("Bayesian without rerank requires 1 <= size <= candidateSize <= 100 (size defaults to 10 on the server). With rerank, omit this field and use rerank.candidateSize, whose default is unchanged. Unsupported for other queries; server validates these combinations."),
+            query: z.record(z.string(), z.any()).optional().describe("Free-form query; omit for match-all. Top-level bayesian is an array of exactly two subqueries, with no explicit boosts on either subquery or its Boolean descendants. Nested rank fusion and fusion weights are unsupported. Server validates the query contract."),
             facets: facetsSchema.optional(),
             rerank: rerankSchema,
             ref: readRefSchema.optional(),
@@ -105,7 +107,7 @@ export function registerReadTools(server, config) {
                     }
                 }]
         })
-    }, async ({ collectionName, size, query, facets, rerank, ref, consistentRead, includeVectors, sort, fields, partitionFilter }) => {
+    }, async ({ collectionName, size, candidateSize, query, facets, rerank, ref, consistentRead, includeVectors, sort, fields, partitionFilter }) => {
         try {
             const client = createLambdaDBClient(config);
             const input = {
@@ -113,6 +115,7 @@ export function registerReadTools(server, config) {
                 facets,
                 rerank,
                 size,
+                candidateSize,
                 ...readOptions(ref, consistentRead),
                 includeVectors,
                 sort,

package/dist/tools/write.js

@@ -6,13 +6,13 @@ import { jsonResult, nameSchema, partitionFilterSchema } from "./shared.js";
 export function registerWriteTools(server, config) {
     server.registerTool("lambdadb_create_collection", {
         title: "Create Collection",
-        description: `Create a new collection in the configured project. Fixed lowercase text analyzer presets: ${Object.values(Analyzer).join(", ")}. Omitted analyzers uses standard; custom pipelines/options are unsupported. The keyword text analyzer is distinct from the keyword field type. Keyword indexes built on a supporting server support facets.`,
+        description: `Create a new collection in the configured project. Fixed lowercase text analyzer presets: ${Object.values(Analyzer).join(", ")}. Omitted analyzers uses standard; custom pipelines/options are unsupported. The keyword text analyzer is distinct from the keyword field type. Keyword indexes built on a supporting server support facets. Native vector fields accept embedding without managedEmbedding; explicit managedEmbedding: true remains supported for older servers.`,
         annotations: {
             openWorldHint: false
         },
         inputSchema: z.strictObject({
             collectionName: nameSchema,
-            indexConfigs: z.record(z.string(), z.any()).refine((value) => Object.keys(value).length > 0, "indexConfigs must contain at least one field."),
+            indexConfigs: z.record(z.string(), z.any()).refine((value) => Object.keys(value).length > 0, "indexConfigs must contain at least one field.").describe("Field configurations validated by the SDK/server. Native vectors: {type: 'vector', embedding: {provider, model, sourceField, dimensions?, similarity?}}; declare sourceField as text. Native dimensions/similarity belong inside embedding, never at the field top level. Do not combine embedding with managedEmbedding: false. Legacy true is preserved; no provider/model or native defaults are inferred. Caller-provided vectors retain top-level dimensions/similarity."),
             description: z.string().max(255).optional(),
             tags: z.record(z.string().regex(/^[A-Za-z0-9_.-]{1,63}$/), z.string().min(1).max(127).regex(/^[^:#,]+$/))
                 .refine((value) => Object.keys(value).length <= 5, "At most five tags are allowed.")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@functional-systems/lambdadb-mcp",
-  "version": "0.1.3-dev.10",
+  "version": "0.1.3-dev.11",
   "private": false,
   "description": "MCP server for LambdaDB data plane",
   "type": "module",
@@ -11,6 +11,7 @@
     "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.json && node -e \"require('node:fs').chmodSync('dist/index.js', 0o755)\"",
     "check": "npm run check:version && npm run typecheck && npm test",
     "test": "npm run build && node --test test/*.test.mjs",
+    "test:live:bayesian": "npm run build && bash ./scripts/with-env.sh --test test/integration/bayesian-live.test.mjs",
     "test:live:rerank": "npm run build && bash ./scripts/with-env.sh --test test/integration/rerank-live.test.mjs",
     "test:live": "npm run build && bash ./scripts/with-env.sh --test test/integration/live.test.mjs",
     "dev": "tsx watch src/index.ts",
@@ -23,7 +24,7 @@
     "test:package": "node scripts/test-package.mjs"
   },
   "dependencies": {
-    "@functional-systems/lambdadb": "0.7.0",
+    "@functional-systems/lambdadb": "0.8.0",
     "@modelcontextprotocol/sdk": "1.29.0",
     "zod": "^4.1.12"
   },
@@ -61,5 +62,5 @@
     "access": "public",
     "registry": "https://registry.npmjs.org"
   },
-  "gitHead": "df4be52ea47726f4d3d82a99b3ee2a755139c1f9"
+  "gitHead": "bd1ae5547f868991a22c92b5a07849edfcf696fb"
 }