Merge pull request #5 from FoxNoseTech/feat/add-vector-fields-support

feat: vector search support for Flux API (v0.3.0)

Author: loookashow

README.md

@@ -100,6 +100,64 @@ console.log(schema.searchable_fields);
 client.close();
 ```
 
+### Vector Search
+
+The Flux client provides typed convenience methods for all vector search modes:
+
+```typescript
+import { FluxClient, SearchMode, buildSearchBody } from '@foxnose/sdk';
+
+// Semantic search (auto-generated embeddings)
+const results = await client.vectorSearch('articles', {
+  query: 'machine learning in healthcare',
+  top_k: 10,
+  similarity_threshold: 0.7,
+});
+
+// Custom embedding search
+const results = await client.vectorFieldSearch('articles', {
+  field: 'content_embedding',
+  query_vector: [0.012, -0.034, 0.056 /* ... */],
+  top_k: 20,
+});
+
+// Hybrid text + vector search
+const results = await client.hybridSearch('articles', {
+  query: 'ML applications',
+  find_text: { query: 'machine learning' },
+  vector_weight: 0.7,
+  text_weight: 0.3,
+});
+
+// Boosted search (keywords boosted by vector similarity)
+const results = await client.boostedSearch('articles', {
+  find_text: { query: 'python tutorial' },
+  query: 'beginner programming guide',
+  boost_factor: 1.5,
+});
+
+// Extra parameters (where, sort) are forwarded to the API
+const results = await client.vectorSearch('articles', {
+  query: 'climate change',
+  limit: 5,
+  sort: '-published_at',
+  where: { category: 'science' },
+});
+```
+
+You can also use `buildSearchBody()` for full control with the raw `search()` method:
+
+```typescript
+const body = buildSearchBody({
+  search_mode: SearchMode.HYBRID,
+  find_text: { query: 'python' },
+  vector_search: { query: 'programming tutorials', top_k: 10 },
+  hybrid_config: { vector_weight: 0.6, text_weight: 0.4 },
+  limit: 20,
+});
+const results = await client.search('articles', body);
+```
+
 ### API Folder Route Descriptions
 
 You can configure per-route descriptions when connecting a folder to an API.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foxnose/sdk",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "description": "Official FoxNose SDK for TypeScript and JavaScript",
   "license": "Apache-2.0",
   "type": "module",

src/config.ts

@@ -19,7 +19,7 @@ export const DEFAULT_RETRY_CONFIG: Readonly<RetryConfig> = {
   methods: ['GET', 'HEAD', 'OPTIONS', 'PUT', 'DELETE'],
 };
 
-export const SDK_VERSION = '0.2.1';
+export const SDK_VERSION = '0.3.0';
 
 export const DEFAULT_USER_AGENT = `foxnose-sdk-js/${SDK_VERSION}`;
 

src/flux/client.ts

@@ -2,6 +2,14 @@ import type { AuthStrategy } from '../auth/types.js';
 import type { RetryConfig } from '../config.js';
 import { createConfig } from '../config.js';
 import { HttpTransport } from '../http.js';
+import type {
+  HybridConfig,
+  SearchRequest,
+  VectorBoostConfig,
+  VectorFieldSearch,
+  VectorSearch,
+} from './models.js';
+import { SearchMode, buildSearchBody, mergeExtra } from './models.js';
 
 function cleanPrefix(prefix: string): string {
   const value = prefix.replace(/^\/+|\/+$/g, '');
@@ -24,6 +32,65 @@ export interface FluxClientOptions {
   defaultHeaders?: Record<string, string>;
 }
 
+export interface VectorSearchOptions {
+  query: string;
+  fields?: string[];
+  top_k?: number;
+  similarity_threshold?: number;
+  limit?: number;
+  offset?: number;
+  [extra: string]: any;
+}
+
+export interface VectorFieldSearchOptions {
+  field: string;
+  query_vector: number[];
+  top_k?: number;
+  similarity_threshold?: number;
+  limit?: number;
+  offset?: number;
+  [extra: string]: any;
+}
+
+export interface HybridSearchOptions {
+  query: string;
+  find_text: Record<string, any>;
+  fields?: string[];
+  top_k?: number;
+  similarity_threshold?: number;
+  vector_weight?: number;
+  text_weight?: number;
+  rerank_results?: boolean;
+  limit?: number;
+  offset?: number;
+  [extra: string]: any;
+}
+
+export interface BoostedSearchOptions {
+  find_text: Record<string, any>;
+  query?: string;
+  field?: string;
+  query_vector?: number[];
+  top_k?: number;
+  similarity_threshold?: number;
+  boost_factor?: number;
+  boost_similarity_threshold?: number;
+  max_boost_results?: number;
+  limit?: number;
+  offset?: number;
+  [extra: string]: any;
+}
+
+function stripUndefined(obj: Record<string, any>): Record<string, any> {
+  const result: Record<string, any> = {};
+  for (const [key, value] of Object.entries(obj)) {
+    if (value !== undefined) {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+
 /**
  * Client for FoxNose Flux delivery APIs.
  *
@@ -72,6 +139,138 @@ export class FluxClient {
     return this.transport.request('POST', path, { jsonBody: body });
   }
 
+  /** Semantic search using auto-generated embeddings. */
+  async vectorSearch<T = any>(folderPath: string, options: VectorSearchOptions): Promise<T> {
+    const { query, fields, top_k = 10, similarity_threshold, limit, offset, ...rest } = options;
+    const extra = stripUndefined(rest);
+    const vs: VectorSearch = { query, fields, top_k, similarity_threshold };
+    const req: SearchRequest = {
+      search_mode: SearchMode.VECTOR,
+      vector_search: vs,
+      limit,
+      offset,
+    };
+    const body = mergeExtra(buildSearchBody(req), extra);
+    return this.search(folderPath, body);
+  }
+
+  /** Search using custom pre-computed embeddings. */
+  async vectorFieldSearch<T = any>(
+    folderPath: string,
+    options: VectorFieldSearchOptions,
+  ): Promise<T> {
+    const {
+      field,
+      query_vector,
+      top_k = 10,
+      similarity_threshold,
+      limit,
+      offset,
+      ...rest
+    } = options;
+    const extra = stripUndefined(rest);
+    const vfs: VectorFieldSearch = { field, query_vector, top_k, similarity_threshold };
+    const req: SearchRequest = {
+      search_mode: SearchMode.VECTOR,
+      vector_field_search: vfs,
+      limit,
+      offset,
+    };
+    const body = mergeExtra(buildSearchBody(req), extra);
+    return this.search(folderPath, body);
+  }
+
+  /** Blended text + vector search with configurable weights. */
+  async hybridSearch<T = any>(folderPath: string, options: HybridSearchOptions): Promise<T> {
+    const {
+      query,
+      find_text,
+      fields,
+      top_k = 10,
+      similarity_threshold,
+      vector_weight = 0.6,
+      text_weight = 0.4,
+      rerank_results = true,
+      limit,
+      offset,
+      ...rest
+    } = options;
+    const extra = stripUndefined(rest);
+    const vs: VectorSearch = { query, fields, top_k, similarity_threshold };
+    const hybrid: HybridConfig = { vector_weight, text_weight, rerank_results };
+    const req: SearchRequest = {
+      search_mode: SearchMode.HYBRID,
+      find_text,
+      vector_search: vs,
+      hybrid_config: hybrid,
+      limit,
+      offset,
+    };
+    const body = mergeExtra(buildSearchBody(req), extra);
+    return this.search(folderPath, body);
+  }
+
+  /** Text search with results boosted by vector similarity. */
+  async boostedSearch<T = any>(folderPath: string, options: BoostedSearchOptions): Promise<T> {
+    const {
+      find_text,
+      query,
+      field,
+      query_vector,
+      top_k = 10,
+      similarity_threshold,
+      boost_factor = 1.5,
+      boost_similarity_threshold,
+      max_boost_results = 20,
+      limit,
+      offset,
+      ...rest
+    } = options;
+    const extra = stripUndefined(rest);
+
+    const hasAuto = query != null;
+    const hasCustom = field != null || query_vector != null;
+
+    if (hasAuto && hasCustom) {
+      throw new Error(
+        "Provide either 'query' for auto-generated embeddings " +
+          "or 'field' + 'query_vector' for custom embeddings, not both",
+      );
+    }
+
+    let vs: VectorSearch | undefined;
+    let vfs: VectorFieldSearch | undefined;
+
+    if (hasAuto) {
+      vs = { query: query!, top_k, similarity_threshold };
+    } else if (field != null && query_vector != null) {
+      vfs = { field, query_vector, top_k, similarity_threshold };
+    } else {
+      throw new Error(
+        "Provide either 'query' for auto-generated embeddings " +
+          "or 'field' + 'query_vector' for custom embeddings",
+      );
+    }
+
+    const boostConfig: VectorBoostConfig = {
+      boost_factor,
+      similarity_threshold: boost_similarity_threshold,
+      max_boost_results,
+    };
+
+    const req: SearchRequest = {
+      search_mode: SearchMode.VECTOR_BOOSTED,
+      find_text,
+      vector_search: vs,
+      vector_field_search: vfs,
+      vector_boost_config: boostConfig,
+      limit,
+      offset,
+    };
+    const body = mergeExtra(buildSearchBody(req), extra);
+    return this.search(folderPath, body);
+  }
+
   async getRouter<T = any>(): Promise<T> {
     const path = `/${this.apiPrefix}/_router`;
     return this.transport.request('GET', path);

src/flux/index.ts

@@ -1,2 +1,16 @@
 export { FluxClient } from './client.js';
-export type { FluxClientOptions } from './client.js';
+export type {
+  FluxClientOptions,
+  VectorSearchOptions,
+  VectorFieldSearchOptions,
+  HybridSearchOptions,
+  BoostedSearchOptions,
+} from './client.js';
+export { SearchMode, buildSearchBody, mergeExtra } from './models.js';
+export type {
+  VectorSearch,
+  VectorFieldSearch,
+  VectorBoostConfig,
+  HybridConfig,
+  SearchRequest,
+} from './models.js';