feat: v8.0.0 — add search modes (semantic/lexical/hybrid) and min_similarity

Author: kennedyowusu

CHANGELOG.md

@@ -7,6 +7,41 @@ adheres to [Semantic Versioning][semver].
 [kac]: https://keepachangelog.com/en/1.1.0/
 [semver]: https://semver.org/
 
+## 8.0.0
+
+### Breaking changes
+
+- None. `mode` and `minSimilarity` are both optional; existing
+  `searchSemantic` callers continue to work unchanged. Major bump
+  reflects the conceptual expansion of the search contract (three
+  retrieval modes instead of one), not API-breaking removals.
+
+### Added
+
+- `KoolbaseDatabase.searchSemantic` accepts a new `mode` parameter of
+  type `SearchMode`. Three retrieval strategies are supported:
+  - `'semantic'` (default) — pure vector search via HNSW on cosine
+    distance. Best for fuzzy / conceptual queries.
+  - `'lexical'` — pure BM25 over the field's source text via Postgres
+    `ts_rank_cd`. Best for exact terms, codes, names, acronyms.
+  - `'hybrid'` — vector + lexical fused with reciprocal rank fusion
+    (k=60). Generally the strongest default for production search.
+- `KoolbaseDatabase.searchSemantic` accepts a new `minSimilarity`
+  parameter (0..100, optional). Server-side filter that drops results
+  below the given similarity percentage before they cross the wire.
+  Saves bandwidth on weak matches. Only valid for semantic and hybrid
+  modes; the server rejects it on lexical mode (BM25 ranks aren't
+  comparable to cosine similarity).
+- New `SearchMode` type exported from `@techfinityedge/koolbase-react-native`.
+
+### Server requirements
+
+- Requires Koolbase API release with hybrid search shipped (June 8 2026
+  or later).
+- Lexical and hybrid modes require the vector field to have a
+  `source_field` configured. The lexical sidecar table populates
+  automatically on record write via the same hook that drives auto-embed.
+
 ## 7.0.0
 
 ### Breaking changes

README.md

@@ -379,37 +379,90 @@ When the device is offline, these writes are queued and synced automatically whe
 
 ---
 
-### Semantic search
+### Semantic, lexical, and hybrid search
 
-Find records by meaning, not just field equality. Two paths: let Koolbase
-embed text for you on the server (recommended — no client-side model
-needed), or pass a precomputed vector.
+Find records by meaning, exact terms, or both. Koolbase ships three
+retrieval modes from a single API — pick the one that matches your
+query characteristics, or use `'hybrid'` as a strong production default.
 
 Declare a vector field on the collection from the dashboard or CLI first
 (picking a dimension; v1 supports 384, 768, 1024, and 1536).
 
-**Server-side embedding (recommended).** Configure an AI provider on the
-project once (Gemini's free tier works; OpenAI also supported), tag the
-vector field with the provider/model/source_field, and Koolbase
-auto-embeds records as they're inserted or updated:
+#### The three search modes
 
 ```typescript
-// One-time setup via dashboard. Then just write records normally:
-await Koolbase.db.insert({
+// Semantic (default) — pure vector search via HNSW + cosine. Best for
+// fuzzy or conceptual queries where exact words don't have to match.
+const result = await Koolbase.db.searchSemantic({
   collection: 'articles',
-  data: {
-    title: 'How to ship faster',
-    content: 'Cut scope ruthlessly. Ship the smallest useful slice...',
-  },
+  field: 'content_embedding',
+  queryText: 'how do I move quicker?',
+  limit: 10,
 });
 
-// Query by text — server embeds inline using the configured provider:
+// Lexical — pure BM25 over the field's source text (Postgres
+// ts_rank_cd). Best for exact terms, product codes, names, acronyms.
+const result = await Koolbase.db.searchSemantic({
+  collection: 'articles',
+  field: 'content_embedding',
+  queryText: 'CVE-2024-1234',
+  mode: 'lexical',
+  limit: 10,
+});
+
+// Hybrid — vector + lexical fused with reciprocal rank fusion (k=60).
+// Generally the strongest default; both rankers vote and the fused
+// score promotes records that score well on either signal.
+const result = await Koolbase.db.searchSemantic({
+  collection: 'articles',
+  field: 'content_embedding',
+  queryText: 'production deploy pipeline',
+  mode: 'hybrid',
+  limit: 10,
+});
+```
+
+#### Filtering weak matches
+
+For `'semantic'` and `'hybrid'` modes, pass `minSimilarity` (0..100) to
+drop results below a similarity threshold server-side — saves bandwidth
+on weak matches:
+
+```typescript
 const result = await Koolbase.db.searchSemantic({
   collection: 'articles',
   field: 'content_embedding',
   queryText: 'how do I move quicker?',
+  mode: 'hybrid',
+  minSimilarity: 70, // only matches at least 70% similar
   limit: 10,
 });
+```
+
+`minSimilarity` is rejected by the server when used with `'lexical'` —
+BM25 rank scores aren't comparable to cosine similarity, and silently
+ignoring the parameter would produce confusing behavior.
+
+#### Server-side embedding (recommended)
+
+Configure an AI provider on the project once (Gemini's free tier works;
+OpenAI also supported), tag the vector field with the
+provider/model/source_field, and Koolbase auto-embeds records as
+they're inserted or updated. Lexical indexing happens automatically on
+the same write, so all three search modes work without extra setup:
+
+```typescript
+// One-time setup via dashboard. Then just write records normally —
+// vectors AND lexical rows land within ~1s.
+await Koolbase.db.insert({
+  collection: 'articles',
+  data: {
+    title: 'How to ship faster',
+    content: 'Cut scope ruthlessly. Ship the smallest useful slice...',
+  },
+});
+
+// Iterate over hits the same way regardless of mode:
 for (const hit of result.hits) {
   console.log(`${hit.record.data.title}  ${hit.distance.toFixed(3)}`);
 }
@@ -430,8 +483,11 @@ await Koolbase.db.embedText({
 });
 ```
 
-**Client-side embedding (advanced).** If you'd rather control the
-embedding model yourself, pass a vector instead of text:
+#### Client-side embedding (advanced)
+
+If you'd rather control the embedding model yourself, pass a vector
+instead of text. Note that lexical and hybrid modes require text, since
+BM25 has no notion of "vector queries":
 
 ```typescript
 // Set a vector you've encoded yourself
@@ -445,7 +501,7 @@ await Koolbase.db.setVector(
 const v = await Koolbase.db.getVector(articleId, 'embedding');
 console.log(`${v.vector.length}-dim, updated ${v.updatedAt}`);
 
-// Search with a precomputed vector
+// Search with a precomputed vector — semantic mode only.
 const result = await Koolbase.db.searchSemantic({
   collection: 'articles',
   field: 'embedding',
@@ -458,25 +514,32 @@ const result = await Koolbase.db.searchSemantic({
 await Koolbase.db.deleteVector(articleId, 'embedding');
 ```
 
-A few behaviors worth knowing:
+#### Behaviors worth knowing
 
 - **Pass exactly one of `queryVector` or `queryText`.** Supplying both
   or neither throws an `Error`.
+- **`queryVector` is for semantic mode only.** Lexical and hybrid need
+  raw text — the server uses it for BM25 ranking (and embeds it inline
+  for the vector half of hybrid).
 - **Vector length must match the declared dimension.** Mismatches throw
   `KoolbaseVectorDimensionMismatchError`.
+- **`minSimilarity` must be 0..100.** Values outside that range throw
+  an `Error` client-side before the request is sent.
 - **Online-only.** Vector operations are not cached locally or queued
-  offline — HNSW similarity search has no useful offline semantics.
+  offline — HNSW similarity and BM25 ranking have no useful offline
+  semantics.
 - **Read rule applies post-search.** `owner`/`scoped`/`conditional`
-  records are filtered to the caller after the HNSW lookup, so strict
-  rules may return fewer than `limit` results.
+  records are filtered to the caller after retrieval, so strict rules
+  may return fewer than `limit` results.
 - **`embedText` is async.** Returns when the job is queued (~100ms).
   The vector lands within 1 second once the worker picks it up.
 - **Higher dimensions coming.** `text-embedding-3-large` (3072 dim)
-  supported once pgvector is upgraded. Use `dimensions=1536` Matryoshka
-  truncation in the meantime.
+  supported once pgvector is upgraded. Use `dimensions=1536`
+  Matryoshka truncation in the meantime.
 
 See [Semantic search docs](https://docs.koolbase.com/database/vectors)
-for setup, provider configuration, and embedding model recommendations.
+for setup, provider configuration, embedding model recommendations,
+and when to pick each mode.
 
 ---
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@techfinityedge/koolbase-react-native",
-  "version": "7.0.0",
+  "version": "8.0.0",
   "description": "React Native SDK for Koolbase — auth, database, storage, realtime, feature flags, and functions in one package.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

src/database.ts

@@ -8,6 +8,7 @@ import {
   BatchResult,
   KoolbaseVector,
   SemanticSearchResult,
+  SearchMode,
 } from './types';
 import {
   getCached,
@@ -547,11 +548,8 @@ export class KoolbaseDatabase {
     await this.request<{ queued: boolean }>('POST', '/v1/sdk/db/embed-text', body);
   }
 
-
   /**
-   * Semantic search over a vector field. Supply EITHER `queryVector`
-   * (precomputed) OR `queryText` (the server embeds it inline using the
-   * vector field's configured provider).
+   * Search for records based on their semantic similarity to a query.
    *
    * @example
    * // Server-side embedding — most common:
@@ -569,6 +567,25 @@ export class KoolbaseDatabase {
    *   queryVector: precomputed,
    *   limit: 10,
    * });
+   *
+   * // Hybrid search (vector + BM25, RRF-fused):
+   * const result = await Koolbase.db.searchSemantic({
+   *   collection: 'articles',
+   *   field: 'content_embedding',
+   *   queryText: 'how do I configure CI/CD?',
+   *   mode: 'hybrid',
+   *   minSimilarity: 70,
+   * });
+   *
+   * `mode` selects the retrieval strategy:
+   * - `'semantic'` (default) — pure vector search via HNSW
+   * - `'lexical'` — pure BM25 over the field's source text
+   * - `'hybrid'` — vector + lexical, RRF-fused (k=60)
+   *
+   * `minSimilarity` (0..100, optional) filters out results below the
+   * given similarity percentage server-side. Saves bandwidth on weak
+   * matches. Only valid for semantic and hybrid; rejected by the
+   * server on lexical mode.
    */
   async searchSemantic(opts: {
     collection: string;
@@ -577,6 +594,8 @@ export class KoolbaseDatabase {
     queryText?: string;
     limit?: number;
     where?: Record<string, unknown>;
+    mode?: SearchMode;
+    minSimilarity?: number;
   }): Promise<SemanticSearchResult> {
     const hasVector = Array.isArray(opts.queryVector) && opts.queryVector.length > 0;
     const hasText = typeof opts.queryText === 'string' && opts.queryText.trim().length > 0;
@@ -586,17 +605,32 @@ export class KoolbaseDatabase {
     if (hasVector && hasText) {
       throw new Error('searchSemantic: provide only one of queryVector or queryText.');
     }
-
+    if (
+      opts.minSimilarity !== undefined &&
+      (opts.minSimilarity < 0 || opts.minSimilarity > 100)
+    ) {
+      throw new Error(
+        `searchSemantic: minSimilarity must be between 0 and 100, got ${opts.minSimilarity}.`,
+      );
+    }
     const body: Record<string, unknown> = {
       collection: opts.collection,
       field: opts.field,
       limit: opts.limit ?? 20,
+      // Always send mode so the server uses the SDK's intent rather
+      // than its own default. Omitting for 'semantic' would also work
+      // (server defaults to semantic) but explicit is safer if the
+      // server's default ever shifts.
+      mode: opts.mode ?? 'semantic',
     };
     if (hasVector) body.query_vector = opts.queryVector;
     if (hasText) body.query_text = opts.queryText;
     if (opts.where && Object.keys(opts.where).length > 0) {
       body.where = opts.where;
     }
+    if (opts.minSimilarity !== undefined) {
+      body.min_similarity = opts.minSimilarity;
+    }
     const raw = await this.request<{
       results: Array<{ record: Record<string, unknown>; distance: number }>;
       total: number;

src/types.ts

@@ -190,6 +190,19 @@ export interface KoolbaseVector {
   updatedAt: string;
 }
 
+/**
+ * Retrieval strategy for `KoolbaseDatabase.searchSemantic()`.
+ *
+ * - `'semantic'` (default) — pure vector search via HNSW on cosine
+ *   distance. Best for fuzzy / conceptual queries where exact term
+ *   match isn't required.
+ * - `'lexical'` — pure BM25 over the field's source text (Postgres
+ *   `ts_rank_cd`). Best for exact terms, codes, names, acronyms.
+ * - `'hybrid'` — vector + lexical fused with reciprocal rank fusion
+ *   (k=60). Generally the strongest default for production search.
+ */
+export type SearchMode = 'semantic' | 'lexical' | 'hybrid';
+
 /**
  * One ranked hit from `KoolbaseDatabase.searchSemantic()`. `record` is
  * the full record (same wire shape as a record returned by query/get).