@neureus/sdk
Version:
Neureus Platform SDK - AI-native, edge-first application platform
300 lines (296 loc) • 7.67 kB
TypeScript
import { VectorIndexConfig, VectorIndexStats, VectorEntry, VectorSearch, VectorSearchResponse, HybridSearch } from '@neureus/vector-db';
export { DimensionMismatchError, HybridSearch, IndexNotFoundError, IndexType, SimilarityMetric, Vector, VectorDBError, VectorEntry, VectorId, VectorIndexConfig, VectorIndexStats, VectorNotFoundError, VectorSearch, VectorSearchResponse, VectorSearchResult } from '@neureus/vector-db';
/**
* Neureus Vector Database SDK Client
*
* Provides a simple interface to interact with the Neureus Vector Database,
* supporting vector similarity search, hybrid search, index management,
* and batch operations optimized for edge deployment.
*
* @example
* ```typescript
* import { VectorClient } from '@neureus/sdk/vector';
*
* const vectors = new VectorClient({
* apiKey: 'nru_...',
* baseUrl: 'https://api.neureus.ai'
* });
*
* // Create an index
* await vectors.indices.create({
* name: 'documents',
* dimension: 1536,
* metric: 'cosine'
* });
*
* // Upsert vectors
* await vectors.upsert({
* vectors: [
* {
* id: 'doc1',
* vector: [...], // 1536-dimensional embedding
* metadata: { title: 'Introduction', page: 1 }
* }
* ]
* });
*
* // Search for similar vectors
* const results = await vectors.search({
* vector: [...], // query embedding
* topK: 5,
* minSimilarity: 0.7
* });
* ```
*/
/**
* Configuration options for VectorClient
*/
interface VectorClientConfig {
/**
* Neureus API key (required)
* Get your API key from https://app.neureus.ai/settings/api-keys
*/
apiKey: string;
/**
* Base URL for the Neureus API
* @default 'https://api.neureus.ai'
*/
baseUrl?: string;
/**
* Request timeout in milliseconds
* @default 30000 (30 seconds)
*/
timeout?: number;
/**
* Number of retry attempts for failed requests
* @default 3
*/
retries?: number;
/**
* Default namespace for operations (optional)
*/
namespace?: string;
/**
* Default index name for operations (optional)
* @default 'default'
*/
indexName?: string;
}
/**
* Options for vector upsert operations
*/
interface UpsertOptions {
/**
* The vector(s) to upsert
*/
vectors: VectorEntry[];
/**
* Namespace to store vectors in (optional)
*/
namespace?: string;
/**
* Index name (optional, defaults to 'default')
*/
indexName?: string;
}
/**
* Options for vector search operations
*/
interface SearchOptions extends Omit<VectorSearch, 'vector'> {
/**
* Query vector
*/
vector: number[];
/**
* Index name to search in (optional)
*/
indexName?: string;
}
/**
* Options for hybrid search operations
*/
interface HybridSearchOptions extends Omit<HybridSearch, 'vector' | 'query'> {
/**
* Query vector (optional, one of vector or query required)
*/
vector?: number[];
/**
* Text query (optional, one of vector or query required)
*/
query?: string;
/**
* Index name to search in (optional)
*/
indexName?: string;
}
/**
* Main Vector client class
*/
declare class VectorClient {
private http;
private config;
constructor(config: VectorClientConfig);
/**
* Index management API
*/
indices: {
/**
* Create a new vector index
*
* @example
* ```typescript
* await vectors.indices.create({
* name: 'documents',
* dimension: 1536, // OpenAI ada-002 dimensions
* metric: 'cosine',
* indexType: 'hnsw'
* });
* ```
*/
create: (config: VectorIndexConfig) => Promise<{
success: boolean;
indexName: string;
message: string;
}>;
/**
* List all indices
*
* @example
* ```typescript
* const indices = await vectors.indices.list();
* console.log(indices); // [{ name: 'documents', dimension: 1536, ... }]
* ```
*/
list: () => Promise<{
indices: string[];
count: number;
}>;
/**
* Get index statistics
*
* @example
* ```typescript
* const stats = await vectors.indices.stats('documents');
* console.log(stats.vectorCount, stats.memoryUsage);
* ```
*/
stats: (indexName: string) => Promise<VectorIndexStats>;
/**
* Drop (delete) an index
*
* @example
* ```typescript
* await vectors.indices.drop('old-index');
* ```
*/
drop: (indexName: string) => Promise<{
success: boolean;
message: string;
}>;
};
/**
* Upsert (insert or update) a single vector
*
* @example
* ```typescript
* const id = await vectors.upsert({
* vectors: [{
* id: 'doc1',
* vector: [0.1, 0.2, ...], // embedding vector
* metadata: { title: 'Document 1', page: 1 }
* }]
* });
* ```
*/
upsert(options: UpsertOptions): Promise<{
success: boolean;
ids: string[];
count: number;
message: string;
}>;
/**
* Get a vector by ID
*
* @example
* ```typescript
* const vector = await vectors.get('doc1');
* console.log(vector.metadata, vector.vector);
* ```
*/
get(id: string, namespace?: string): Promise<VectorEntry>;
/**
* Delete a vector by ID
*
* @example
* ```typescript
* await vectors.delete('doc1');
* ```
*/
delete(id: string, namespace?: string, indexName?: string): Promise<{
success: boolean;
message: string;
}>;
/**
* Search for similar vectors
*
* @example
* ```typescript
* const results = await vectors.search({
* vector: [0.1, 0.2, ...], // query embedding
* topK: 5,
* minSimilarity: 0.7,
* filter: { page: { $gt: 10 } }
* });
*
* for (const result of results.matches) {
* console.log(result.id, result.score, result.metadata);
* }
* ```
*/
search(options: SearchOptions): Promise<VectorSearchResponse>;
/**
* Hybrid search (vector + keyword)
*
* Combines vector similarity search with keyword/text search
* for better retrieval accuracy.
*
* @example
* ```typescript
* const results = await vectors.hybridSearch({
* vector: [0.1, 0.2, ...],
* query: 'machine learning',
* topK: 10,
* alpha: 0.7 // 70% vector, 30% keyword
* });
* ```
*/
hybridSearch(options: HybridSearchOptions): Promise<VectorSearchResponse>;
/**
* Clear all vectors in a namespace
*
* @example
* ```typescript
* await vectors.clear('temporary-docs');
* ```
*/
clear(namespace: string, indexName?: string): Promise<{
success: boolean;
deletedCount: number;
message: string;
}>;
}
/**
* Create a Vector client instance
*
* @example
* ```typescript
* import { createVectorClient } from '@neureus/sdk/vector';
*
* const vectors = createVectorClient({
* apiKey: process.env.NEUREUS_API_KEY,
* indexName: 'my-docs'
* });
* ```
*/
declare function createVectorClient(config: VectorClientConfig): VectorClient;
export { type HybridSearchOptions, type SearchOptions, type UpsertOptions, VectorClient, type VectorClientConfig, createVectorClient };