UNPKG

@neureus/sdk

Version:

Neureus Platform SDK - AI-native, edge-first application platform

github.com/Neureus/Neureus

Neureus/Neureus

1 lines • 16.3 kB
1
{"version":3,"sources":["../src/vector.ts"],"names":["ky"],"mappings":"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","file":"vector.cjs","sourcesContent":["/**\n * Neureus Vector Database SDK Client\n *\n * Provides a simple interface to interact with the Neureus Vector Database,\n * supporting vector similarity search, hybrid search, index management,\n * and batch operations optimized for edge deployment.\n *\n * @example\n * ```typescript\n * import { VectorClient } from '@neureus/sdk/vector';\n *\n * const vectors = new VectorClient({\n * apiKey: 'nru_...',\n * baseUrl: 'https://api.neureus.ai'\n * });\n *\n * // Create an index\n * await vectors.indices.create({\n * name: 'documents',\n * dimension: 1536,\n * metric: 'cosine'\n * });\n *\n * // Upsert vectors\n * await vectors.upsert({\n * vectors: [\n * {\n * id: 'doc1',\n * vector: [...], // 1536-dimensional embedding\n * metadata: { title: 'Introduction', page: 1 }\n * }\n * ]\n * });\n *\n * // Search for similar vectors\n * const results = await vectors.search({\n * vector: [...], // query embedding\n * topK: 5,\n * minSimilarity: 0.7\n * });\n * ```\n */\n\nimport ky, { type KyInstance } from 'ky';\nimport type {\n VectorEntry,\n VectorSearch,\n VectorSearchResponse,\n VectorIndexConfig,\n VectorIndexStats,\n HybridSearch,\n} from '@neureus/vector-db';\n\n// Re-export types from vector-db for convenience\nexport type {\n VectorEntry,\n VectorSearch,\n VectorSearchResponse,\n VectorSearchResult,\n VectorIndexConfig,\n VectorIndexStats,\n HybridSearch,\n SimilarityMetric,\n IndexType,\n VectorId,\n Vector,\n VectorDBError,\n VectorNotFoundError,\n IndexNotFoundError,\n DimensionMismatchError,\n} from '@neureus/vector-db';\n\n/**\n * Configuration options for VectorClient\n */\nexport interface VectorClientConfig {\n /**\n * Neureus API key (required)\n * Get your API key from https://app.neureus.ai/settings/api-keys\n */\n apiKey: string;\n\n /**\n * Base URL for the Neureus API\n * @default 'https://api.neureus.ai'\n */\n baseUrl?: string;\n\n /**\n * Request timeout in milliseconds\n * @default 30000 (30 seconds)\n */\n timeout?: number;\n\n /**\n * Number of retry attempts for failed requests\n * @default 3\n */\n retries?: number;\n\n /**\n * Default namespace for operations (optional)\n */\n namespace?: string;\n\n /**\n * Default index name for operations (optional)\n * @default 'default'\n */\n indexName?: string;\n}\n\n/**\n * Options for vector upsert operations\n */\nexport interface UpsertOptions {\n /**\n * The vector(s) to upsert\n */\n vectors: VectorEntry[];\n\n /**\n * Namespace to store vectors in (optional)\n */\n namespace?: string;\n\n /**\n * Index name (optional, defaults to 'default')\n */\n indexName?: string;\n}\n\n/**\n * Options for vector search operations\n */\nexport interface SearchOptions extends Omit<VectorSearch, 'vector'> {\n /**\n * Query vector\n */\n vector: number[];\n\n /**\n * Index name to search in (optional)\n */\n indexName?: string;\n}\n\n/**\n * Options for hybrid search operations\n */\nexport interface HybridSearchOptions extends Omit<HybridSearch, 'vector' | 'query'> {\n /**\n * Query vector (optional, one of vector or query required)\n */\n vector?: number[];\n\n /**\n * Text query (optional, one of vector or query required)\n */\n query?: string;\n\n /**\n * Index name to search in (optional)\n */\n indexName?: string;\n}\n\n/**\n * Main Vector client class\n */\nexport class VectorClient {\n private http: KyInstance;\n private config: Required<Omit<VectorClientConfig, 'namespace'>> & Pick<VectorClientConfig, 'namespace'>;\n\n constructor(config: VectorClientConfig) {\n this.config = {\n apiKey: config.apiKey,\n baseUrl: config.baseUrl || 'https://api.neureus.ai',\n timeout: config.timeout || 30000,\n retries: config.retries || 3,\n indexName: config.indexName || 'default',\n ...(config.namespace !== undefined && { namespace: config.namespace }),\n };\n\n this.http = ky.create({\n prefixUrl: this.config.baseUrl,\n timeout: this.config.timeout,\n retry: {\n limit: this.config.retries,\n methods: ['get', 'post', 'delete'],\n statusCodes: [408, 413, 429, 500, 502, 503, 504],\n },\n hooks: {\n beforeRequest: [\n (request) => {\n request.headers.set('Authorization', `Bearer ${this.config.apiKey}`);\n request.headers.set('Content-Type', 'application/json');\n request.headers.set('User-Agent', 'Neureus-SDK/0.2.0');\n },\n ],\n },\n });\n }\n\n /**\n * Index management API\n */\n public indices = {\n /**\n * Create a new vector index\n *\n * @example\n * ```typescript\n * await vectors.indices.create({\n * name: 'documents',\n * dimension: 1536, // OpenAI ada-002 dimensions\n * metric: 'cosine',\n * indexType: 'hnsw'\n * });\n * ```\n */\n create: async (config: VectorIndexConfig): Promise<{ success: boolean; indexName: string; message: string }> => {\n return this.http.post('vector/indices', {\n json: config,\n }).json();\n },\n\n /**\n * List all indices\n *\n * @example\n * ```typescript\n * const indices = await vectors.indices.list();\n * console.log(indices); // [{ name: 'documents', dimension: 1536, ... }]\n * ```\n */\n list: async (): Promise<{ indices: string[]; count: number }> => {\n return this.http.get('vector/indices').json();\n },\n\n /**\n * Get index statistics\n *\n * @example\n * ```typescript\n * const stats = await vectors.indices.stats('documents');\n * console.log(stats.vectorCount, stats.memoryUsage);\n * ```\n */\n stats: async (indexName: string): Promise<VectorIndexStats> => {\n return this.http.get(`vector/indices/${indexName}/stats`).json();\n },\n\n /**\n * Drop (delete) an index\n *\n * @example\n * ```typescript\n * await vectors.indices.drop('old-index');\n * ```\n */\n drop: async (indexName: string): Promise<{ success: boolean; message: string }> => {\n return this.http.delete(`vector/indices/${indexName}`).json();\n },\n };\n\n /**\n * Upsert (insert or update) a single vector\n *\n * @example\n * ```typescript\n * const id = await vectors.upsert({\n * vectors: [{\n * id: 'doc1',\n * vector: [0.1, 0.2, ...], // embedding vector\n * metadata: { title: 'Document 1', page: 1 }\n * }]\n * });\n * ```\n */\n async upsert(options: UpsertOptions): Promise<{ success: boolean; ids: string[]; count: number; message: string }> {\n const { vectors, namespace, indexName } = options;\n\n // Use batch endpoint if multiple vectors\n if (vectors.length > 1) {\n return this.http.post('vector/vectors/batch', {\n json: {\n batch: {\n vectors,\n namespace: namespace || this.config.namespace,\n },\n indexName: indexName || this.config.indexName,\n },\n }).json();\n }\n\n // Single vector upsert\n const result = await this.http.post('vector/vectors', {\n json: {\n vector: vectors[0],\n namespace: namespace || this.config.namespace,\n indexName: indexName || this.config.indexName,\n },\n }).json<{ success: boolean; id: string; message: string }>();\n\n return {\n success: result.success,\n ids: [result.id],\n count: 1,\n message: result.message,\n };\n }\n\n /**\n * Get a vector by ID\n *\n * @example\n * ```typescript\n * const vector = await vectors.get('doc1');\n * console.log(vector.metadata, vector.vector);\n * ```\n */\n async get(id: string, namespace?: string): Promise<VectorEntry> {\n const params = new URLSearchParams();\n if (namespace || this.config.namespace) {\n params.set('namespace', namespace || this.config.namespace!);\n }\n\n return this.http.get(`vector/vectors/${id}`, { searchParams: params }).json();\n }\n\n /**\n * Delete a vector by ID\n *\n * @example\n * ```typescript\n * await vectors.delete('doc1');\n * ```\n */\n async delete(id: string, namespace?: string, indexName?: string): Promise<{ success: boolean; message: string }> {\n const params = new URLSearchParams();\n if (namespace || this.config.namespace) {\n params.set('namespace', namespace || this.config.namespace!);\n }\n params.set('indexName', indexName || this.config.indexName);\n\n return this.http.delete(`vector/vectors/${id}`, { searchParams: params }).json();\n }\n\n /**\n * Search for similar vectors\n *\n * @example\n * ```typescript\n * const results = await vectors.search({\n * vector: [0.1, 0.2, ...], // query embedding\n * topK: 5,\n * minSimilarity: 0.7,\n * filter: { page: { $gt: 10 } }\n * });\n *\n * for (const result of results.matches) {\n * console.log(result.id, result.score, result.metadata);\n * }\n * ```\n */\n async search(options: SearchOptions): Promise<VectorSearchResponse> {\n const { indexName, ...searchQuery } = options;\n\n return this.http.post('vector/search', {\n json: {\n query: {\n ...searchQuery,\n namespace: searchQuery.namespace || this.config.namespace,\n },\n indexName: indexName || this.config.indexName,\n },\n }).json();\n }\n\n /**\n * Hybrid search (vector + keyword)\n *\n * Combines vector similarity search with keyword/text search\n * for better retrieval accuracy.\n *\n * @example\n * ```typescript\n * const results = await vectors.hybridSearch({\n * vector: [0.1, 0.2, ...],\n * query: 'machine learning',\n * topK: 10,\n * alpha: 0.7 // 70% vector, 30% keyword\n * });\n * ```\n */\n async hybridSearch(options: HybridSearchOptions): Promise<VectorSearchResponse> {\n const { indexName, ...searchQuery } = options;\n\n return this.http.post('vector/search/hybrid', {\n json: {\n query: {\n ...searchQuery,\n namespace: searchQuery.namespace || this.config.namespace,\n },\n indexName: indexName || this.config.indexName,\n },\n }).json();\n }\n\n /**\n * Clear all vectors in a namespace\n *\n * @example\n * ```typescript\n * await vectors.clear('temporary-docs');\n * ```\n */\n async clear(namespace: string, indexName?: string): Promise<{ success: boolean; deletedCount: number; message: string }> {\n const params = new URLSearchParams();\n params.set('indexName', indexName || this.config.indexName);\n\n return this.http.delete(`vector/namespaces/${namespace}`, { searchParams: params }).json();\n }\n}\n\n/**\n * Create a Vector client instance\n *\n * @example\n * ```typescript\n * import { createVectorClient } from '@neureus/sdk/vector';\n *\n * const vectors = createVectorClient({\n * apiKey: process.env.NEUREUS_API_KEY,\n * indexName: 'my-docs'\n * });\n * ```\n */\nexport function createVectorClient(config: VectorClientConfig): VectorClient {\n return new VectorClient(config);\n}\n"]}