montycat 1.1.6 → 1.1.8

package/README.md

@@ -14,8 +14,8 @@ The official Node.js & TypeScript SDK for [Montycat](https://montygovernance.com
 ```typescript
 // Search your data by MEANING — no external APIs, no separate vector database.
 // (already ON by default in the montycat-semantic server edition)
-const hits = await Sales.semanticSearchGetValues({ query: 'something to listen to music without wires', limitOutput: { start: 0, stop: 5 } });
-// → [{ key, score, value: { name: 'Wireless Headphones' } }, ...]  (matched by meaning, not keywords)
+const hits = await Sales.semanticSearchGetValues({ query: 'Show all Bluetooth devices', limitOutput: { start: 0, stop: 5 } });
+// → [{ __key__: 123..., __score__: 0.78, __value__: { name: 'Wireless Headphones' }}]
 ```
 
 > ### 🧩 All-in-one. AI-native. **Zero external dependencies.**
@@ -93,7 +93,7 @@ docker run -d --name montycat \
   -p 21210:21210 -p 21211:21211 \
   -e MONTYCAT_SUPEROWNER="admin" \
   -e MONTYCAT_PASSWORD="change-me" \
-  -v montycat_data:/app/.montycat \
+  -v montycat_data:/var/lib/.montycat \
   montygovernance/montycat:semantic
 ```
 
@@ -328,13 +328,13 @@ in the background as data is written (the embedding model is downloaded on deman
 ```typescript
 // Semantic search is ON by default in the montycat-semantic edition — just search.
 // Rank stored items by meaning — two flavors:
-//   getValues → each hit is { key, score, value }
-//   getKeys   → each hit is { key, score } (lighter; fetch a page later with getBulk)
-const hits = await Sales.semanticSearchGetValues({ query: 'something to listen to music without wires', limitOutput: { start: 0, stop: 5 } });
-const keys = await Sales.semanticSearchGetKeys({ query: 'something to listen to music without wires', limitOutput: { start: 0, stop: 5 } });
+//   getValues → each hit is { __key__, __score__, __value__ }
+//   getKeys   → each hit is { __key__, __score__ } (lighter; fetch a page later with getBulk)
+const hits = await Sales.semanticSearchGetValues({ query: 'Show all Bluetooth devices', limitOutput: { start: 0, stop: 5 } });
+const keys = await Sales.semanticSearchGetKeys({ query: 'Show all Bluetooth devices', limitOutput: { start: 0, stop: 5 } });
 
 // Optionally drop weak matches by cosine similarity (range [-1, 1]).
-const strong = await Sales.semanticSearchGetKeys({ query: 'something to listen to music without wires', limitOutput: { start: 0, stop: 5 }, minScore: 0.35 });
+const strong = await Sales.semanticSearchGetKeys({ query: 'Show all Bluetooth devices', limitOutput: { start: 0, stop: 5 }, minScore: 0.35 });
 
 // Control the DB-wide switch (optional — it's already on):
 // switch the embedding model: 'minilm' | 'bge-small' (default) | 'bge-base' | 'e5-small'
@@ -345,6 +345,29 @@ await engine.enableSemanticSearch({ model: 'bge-base' });
 await engine.disableSemanticSearch();
 ```
 
+### Hybrid semantic search
+
+Use semantic ranking with a structured metadata constraint. The filter is a
+hard AND pre-filter using the same criteria shape as `lookupKeysWhere`; it does
+not boost cosine scores.
+
+```typescript
+const matchingKeys = await Sales.semanticSearchGetKeysWhere({
+  query: 'astronomy and outer space',
+  filters: { category: 'space' },
+  limitOutput: { start: 0, stop: 5 },
+  minScore: 0.35,
+});
+
+const matchingValues = await Sales.semanticSearchGetValuesWhere({
+  query: 'astronomy and outer space',
+  filters: { category: 'space' },
+  limitOutput: { start: 0, stop: 5 },
+});
+// key hits:   { __key__, __score__ }
+// value hits: { __key__, __score__, __value__ }
+```
+
 ## 🔗 Links
 
 - 🌐 **Website & Docs** — https://montygovernance.com
@@ -357,4 +380,4 @@ await engine.disableSemanticSearch();
 - **Is Montycat a vector database or a NoSQL database?** Both — one engine. Store records and query them by *meaning* (vector / semantic search) or by key/schema, without running two systems.
 - **Do I need OpenAI or an embedding API?** No. Embeddings run on-device in the `montycat-semantic` server. No API keys, no per-query bill, no data egress.
 - **Is it a Pinecone / Weaviate / Chroma / Qdrant alternative?** Yes — self-hosted and open-source, with a NoSQL store built in.
-- **TypeScript support?** First-class — the package ships its own type definitions. Works with Node.js, Deno, Bun, Express, Fastify, and Next.js.
+- **TypeScript support?** First-class — the package ships its own type definitions. Works with Node.js, Deno, Bun, Express, Fastify, and Next.js.

package/dist/classes/generic.d.ts

@@ -173,7 +173,7 @@ declare class GenericKV {
      *                      (the default) lets the server apply its default top-k (10).
      * @param minScore - Drop hits whose cosine similarity (in [-1, 1]) is below
      *                   this value. Default null (no score filter).
-     * @return A promise resolving with ranked hits, each `{key, score}`.
+     * @return A promise resolving with ranked hits, each `{__key__, __score__}`.
      */
     static semanticSearchGetKeys({ query, limitOutput, minScore }: {
         query: string;
@@ -183,6 +183,36 @@ declare class GenericKV {
         };
         minScore?: number | null;
     }): Promise<any>;
+    /**
+     * Hybrid semantic search returning ranked keys only, restricted by a
+     * metadata filter.
+     *
+     * Same ranking as `semanticSearchGetKeys`, but only items matching
+     * `filters` are considered — a hard AND constraint through the same
+     * criteria stack as `lookupKeysWhere` (indexed fields, Timestamp,
+     * Pointer). Scores stay pure cosine; the filter never boosts, it only
+     * restricts. A filter matching nothing resolves with `[]`.
+     *
+     * A separate method (not a parameter on `semanticSearchGetKeys`) so
+     * existing integrations keep their exact signature.
+     *
+     * @param query - The natural-language query text to embed and search for.
+     * @param filters - Metadata criteria, same shape as `lookupKeysWhere`.
+     * @param limitOutput - Start/stop over the ranked hits; `{start: 0, stop: 0}`
+     *                      (the default) lets the server apply its default top-k (10).
+     * @param minScore - Drop hits whose cosine similarity (in [-1, 1]) is below
+     *                   this value. Default null (no score filter).
+     * @return A promise resolving with ranked hits, each `{__key__, __score__}`.
+     */
+    static semanticSearchGetKeysWhere({ query, filters, limitOutput, minScore }: {
+        query: string;
+        filters: object;
+        limitOutput?: {
+            start: number;
+            stop: number;
+        };
+        minScore?: number | null;
+    }): Promise<any>;
     /**
      * Semantic (vector similarity) search returning ranked hits with their values.
      *
@@ -204,7 +234,9 @@ declare class GenericKV {
      *                       returned value.
      * @param pointersMetadata - Whether to include pointer metadata in each
      *                           returned value.
-     * @return A promise resolving with ranked hits, each `{key, score, value}`.
+     * @return A promise resolving with ranked hits, each
+     *         `{__key__, __score__, __value__}` — the same dunder envelope
+     *         `lookupValuesWhere` returns with `keyIncluded: true`, plus the score.
      */
     static semanticSearchGetValues({ query, limitOutput, minScore, withPointers, pointersMetadata }: {
         query: string;
@@ -216,6 +248,44 @@ declare class GenericKV {
         withPointers?: boolean;
         pointersMetadata?: boolean;
     }): Promise<any>;
+    /**
+     * Hybrid semantic search returning ranked hits with their values,
+     * restricted by a metadata filter.
+     *
+     * Same ranking as `semanticSearchGetValues`, but only items matching
+     * `filters` are considered — a hard AND constraint through the same
+     * criteria stack as `lookupKeysWhere` (indexed fields, Timestamp,
+     * Pointer). Scores stay pure cosine; the filter never boosts, it only
+     * restricts. A filter matching nothing resolves with `[]`.
+     *
+     * A separate method (not a parameter on `semanticSearchGetValues`) so
+     * existing integrations keep their exact signature.
+     *
+     * @param query - The natural-language query text to embed and search for.
+     * @param filters - Metadata criteria, same shape as `lookupKeysWhere`.
+     * @param limitOutput - Start/stop over the ranked hits; `{start: 0, stop: 0}`
+     *                      (the default) lets the server apply its default top-k (10).
+     * @param minScore - Drop hits whose cosine similarity (in [-1, 1]) is below
+     *                   this value. Default null (no score filter).
+     * @param withPointers - Whether to include pointers (foreign values) in each
+     *                       returned value.
+     * @param pointersMetadata - Whether to include pointer metadata in each
+     *                           returned value.
+     * @return A promise resolving with ranked hits, each
+     *         `{__key__, __score__, __value__}` — the same dunder envelope
+     *         `lookupValuesWhere` returns with `keyIncluded: true`, plus the score.
+     */
+    static semanticSearchGetValuesWhere({ query, filters, limitOutput, minScore, withPointers, pointersMetadata }: {
+        query: string;
+        filters: object;
+        limitOutput?: {
+            start: number;
+            stop: number;
+        };
+        minScore?: number | null;
+        withPointers?: boolean;
+        pointersMetadata?: boolean;
+    }): Promise<any>;
     /**
      * Gets the length of the keyspace.
      * @returns A promise that resolves with the length of the keyspace.

package/dist/classes/generic.js

@@ -221,7 +221,7 @@ class GenericKV {
      * public methods differ only in which value-inclusion flags they pass,
      * so the wire call lives here once.
      */
-    static async semanticSearchCore(query, limitOutput, minScore, withPointers, keyIncluded, pointersMetadata) {
+    static async semanticSearchCore(query, limitOutput, minScore, filters, withPointers, keyIncluded, pointersMetadata) {
         if (!query || !query.trim()) {
             throw new Error("No query text provided for semantic search.");
         }
@@ -230,6 +230,7 @@ class GenericKV {
             semanticQuery: query,
             limitOutput,
             minScore,
+            semanticFilter: filters,
             withPointers,
             keyIncluded,
             pointersMetadata,
@@ -254,10 +255,37 @@ class GenericKV {
      *                      (the default) lets the server apply its default top-k (10).
      * @param minScore - Drop hits whose cosine similarity (in [-1, 1]) is below
      *                   this value. Default null (no score filter).
-     * @return A promise resolving with ranked hits, each `{key, score}`.
+     * @return A promise resolving with ranked hits, each `{__key__, __score__}`.
      */
     static async semanticSearchGetKeys({ query, limitOutput = { start: 0, stop: 0 }, minScore = null }) {
-        return this.semanticSearchCore(query, limitOutput, minScore, false, false, false);
+        return this.semanticSearchCore(query, limitOutput, minScore, null, false, false, false);
+    }
+    /**
+     * Hybrid semantic search returning ranked keys only, restricted by a
+     * metadata filter.
+     *
+     * Same ranking as `semanticSearchGetKeys`, but only items matching
+     * `filters` are considered — a hard AND constraint through the same
+     * criteria stack as `lookupKeysWhere` (indexed fields, Timestamp,
+     * Pointer). Scores stay pure cosine; the filter never boosts, it only
+     * restricts. A filter matching nothing resolves with `[]`.
+     *
+     * A separate method (not a parameter on `semanticSearchGetKeys`) so
+     * existing integrations keep their exact signature.
+     *
+     * @param query - The natural-language query text to embed and search for.
+     * @param filters - Metadata criteria, same shape as `lookupKeysWhere`.
+     * @param limitOutput - Start/stop over the ranked hits; `{start: 0, stop: 0}`
+     *                      (the default) lets the server apply its default top-k (10).
+     * @param minScore - Drop hits whose cosine similarity (in [-1, 1]) is below
+     *                   this value. Default null (no score filter).
+     * @return A promise resolving with ranked hits, each `{__key__, __score__}`.
+     */
+    static async semanticSearchGetKeysWhere({ query, filters, limitOutput = { start: 0, stop: 0 }, minScore = null }) {
+        if (!filters || Object.keys(filters).length === 0) {
+            throw new Error("No filters provided for hybrid semantic search.");
+        }
+        return this.semanticSearchCore(query, limitOutput, minScore, filters, false, false, false);
     }
     /**
      * Semantic (vector similarity) search returning ranked hits with their values.
@@ -280,10 +308,45 @@ class GenericKV {
      *                       returned value.
      * @param pointersMetadata - Whether to include pointer metadata in each
      *                           returned value.
-     * @return A promise resolving with ranked hits, each `{key, score, value}`.
+     * @return A promise resolving with ranked hits, each
+     *         `{__key__, __score__, __value__}` — the same dunder envelope
+     *         `lookupValuesWhere` returns with `keyIncluded: true`, plus the score.
      */
     static async semanticSearchGetValues({ query, limitOutput = { start: 0, stop: 0 }, minScore = null, withPointers = false, pointersMetadata = false }) {
-        return this.semanticSearchCore(query, limitOutput, minScore, withPointers, true, pointersMetadata);
+        return this.semanticSearchCore(query, limitOutput, minScore, null, withPointers, true, pointersMetadata);
+    }
+    /**
+     * Hybrid semantic search returning ranked hits with their values,
+     * restricted by a metadata filter.
+     *
+     * Same ranking as `semanticSearchGetValues`, but only items matching
+     * `filters` are considered — a hard AND constraint through the same
+     * criteria stack as `lookupKeysWhere` (indexed fields, Timestamp,
+     * Pointer). Scores stay pure cosine; the filter never boosts, it only
+     * restricts. A filter matching nothing resolves with `[]`.
+     *
+     * A separate method (not a parameter on `semanticSearchGetValues`) so
+     * existing integrations keep their exact signature.
+     *
+     * @param query - The natural-language query text to embed and search for.
+     * @param filters - Metadata criteria, same shape as `lookupKeysWhere`.
+     * @param limitOutput - Start/stop over the ranked hits; `{start: 0, stop: 0}`
+     *                      (the default) lets the server apply its default top-k (10).
+     * @param minScore - Drop hits whose cosine similarity (in [-1, 1]) is below
+     *                   this value. Default null (no score filter).
+     * @param withPointers - Whether to include pointers (foreign values) in each
+     *                       returned value.
+     * @param pointersMetadata - Whether to include pointer metadata in each
+     *                           returned value.
+     * @return A promise resolving with ranked hits, each
+     *         `{__key__, __score__, __value__}` — the same dunder envelope
+     *         `lookupValuesWhere` returns with `keyIncluded: true`, plus the score.
+     */
+    static async semanticSearchGetValuesWhere({ query, filters, limitOutput = { start: 0, stop: 0 }, minScore = null, withPointers = false, pointersMetadata = false }) {
+        if (!filters || Object.keys(filters).length === 0) {
+            throw new Error("No filters provided for hybrid semantic search.");
+        }
+        return this.semanticSearchCore(query, limitOutput, minScore, filters, withPointers, true, pointersMetadata);
     }
     /**
      * Gets the length of the keyspace.

package/dist/functions/storeGenericFunctions.js

@@ -58,7 +58,7 @@ function processBulkKeysValues(bulkKeysValues) {
  * @returns A JSON string representing the binary query.
  * */
 function convertToBinaryQuery(cls, options = {}) {
-    const { key = null, value = {}, expireSec = 0, bulkValues = [], bulkKeys = [], bulkKeysValues = {}, searchCriteria = {}, limitOutput = { start: 0, stop: 0 }, withPointers = false, schema = null, keyIncluded = false, pointersMetadata = false, volumes = [], latestVolume = false, semanticQuery = null, minScore = null, waitForIndex = null, } = options;
+    const { key = null, value = {}, expireSec = 0, bulkValues = [], bulkKeys = [], bulkKeysValues = {}, searchCriteria = {}, limitOutput = { start: 0, stop: 0 }, withPointers = false, schema = null, keyIncluded = false, pointersMetadata = false, volumes = [], latestVolume = false, semanticQuery = null, minScore = null, semanticFilter = null, waitForIndex = null, } = options;
     const { processedValue, foundSchema } = processValue(value);
     const { processedBulkValues, uniqueSchema } = processBulkValues(bulkValues);
     const bulkKeysValuesProcessed = processBulkKeysValues(bulkKeysValues);
@@ -94,6 +94,12 @@ function convertToBinaryQuery(cls, options = {}) {
     if (minScore !== null) {
         queryDict.min_score = minScore;
     }
+    // Hybrid metadata pre-filter for `semantic_search` (hard AND constraint,
+    // same criteria shape as lookupKeysWhere — Timestamp/Pointer supported).
+    // Omit when null so the wire is unchanged for existing commands.
+    if (semanticFilter !== null) {
+        queryDict.semantic_filter = JSON.stringify(processSearchCriteria(semanticFilter));
+    }
     // Per-request wait_for_index override for persistent writes; omit when null
     // so the server falls back to its DB-wide default (existing wire unchanged).
     if (waitForIndex !== null) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "montycat",
-  "version": "1.1.6",
+  "version": "1.1.8",
   "description": "Self-hosted vector database + NoSQL with built-in AI semantic search — the Node.js & TypeScript client for Montycat. A Rust-powered, AI-native Pinecone / Weaviate / Chroma alternative for RAG, AI agents & LLM memory.",
   "type": "module",
   "main": "dist/index.js",