@wiscale/velesdb-sdk 1.5.1 → 1.6.0

package/dist/index.d.mts

@@ -23,6 +23,13 @@ interface VelesDBConfig {
 }
 /** Collection type */
 type CollectionType = 'vector' | 'metadata_only';
+/** HNSW index parameters for collection creation */
+interface HnswParams {
+    /** Number of bi-directional links per node (M parameter) */
+    m?: number;
+    /** Size of dynamic candidate list during construction */
+    efConstruction?: number;
+}
 /** Collection configuration */
 interface CollectionConfig {
     /** Vector dimension (e.g., 768 for BERT, 1536 for GPT). Required for vector collections. */
@@ -39,6 +46,8 @@ interface CollectionConfig {
     collectionType?: CollectionType;
     /** Optional collection description */
     description?: string;
+    /** Optional HNSW parameters for index tuning */
+    hnsw?: HnswParams;
 }
 /** Collection metadata */
 interface Collection {
@@ -208,6 +217,74 @@ interface DegreeResponse {
     /** Number of outgoing edges */
     outDegree: number;
 }
+/** Schema mode for graph collections */
+type GraphSchemaMode = 'schemaless' | 'strict';
+/** Graph collection configuration */
+interface GraphCollectionConfig {
+    /** Optional embedding dimension for node vectors */
+    dimension?: number;
+    /** Distance metric for embeddings (default: 'cosine') */
+    metric?: DistanceMetric;
+    /** Schema mode (default: 'schemaless') */
+    schemaMode?: GraphSchemaMode;
+}
+/** Semantic memory entry */
+interface SemanticEntry {
+    /** Unique fact ID */
+    id: number;
+    /** Fact text content */
+    text: string;
+    /** Embedding vector */
+    embedding: number[];
+    /** Optional metadata */
+    metadata?: Record<string, unknown>;
+}
+/** Episodic memory event */
+interface EpisodicEvent {
+    /** Event type identifier */
+    eventType: string;
+    /** Event data */
+    data: Record<string, unknown>;
+    /** Embedding vector */
+    embedding: number[];
+    /** Optional metadata */
+    metadata?: Record<string, unknown>;
+}
+/** Procedural memory pattern */
+interface ProceduralPattern {
+    /** Procedure name */
+    name: string;
+    /** Ordered steps */
+    steps: string[];
+    /** Optional metadata */
+    metadata?: Record<string, unknown>;
+}
+/** Agent memory configuration */
+interface AgentMemoryConfig {
+    /** Embedding dimension (default: 384) */
+    dimension?: number;
+}
+/** Collection statistics response */
+interface CollectionStatsResponse {
+    totalPoints: number;
+    totalSizeBytes: number;
+    rowCount: number;
+    deletedCount: number;
+    avgRowSizeBytes: number;
+    payloadSizeBytes: number;
+    lastAnalyzedEpochMs: number;
+}
+/** Collection configuration response */
+interface CollectionConfigResponse {
+    name: string;
+    dimension: number;
+    metric: string;
+    storageMode: string;
+    pointCount: number;
+    metadataOnly: boolean;
+    graphSchema?: Record<string, unknown>;
+    embeddingDimension?: number;
+}
 /** VelesQL query options */
 interface QueryOptions {
     /** Timeout in milliseconds (default: 30000) */
@@ -215,21 +292,15 @@ interface QueryOptions {
     /** Enable streaming response */
     stream?: boolean;
 }
-/** Query result from multi-model VelesQL query */
-interface QueryResult {
-    /** Node/point ID */
-    nodeId: bigint | number;
-    /** Vector similarity score (if applicable) */
-    vectorScore: number | null;
-    /** Graph relevance score (if applicable) */
-    graphScore: number | null;
-    /** Combined fused score */
-    fusedScore: number;
-    /** Variable bindings from MATCH clause */
-    bindings: Record<string, unknown>;
-    /** Column data from JOIN (if applicable) */
-    columnData: Record<string, unknown> | null;
-}
+/**
+ * Query result row from VelesQL query.
+ *
+ * Shape depends on the SELECT clause:
+ * - `SELECT *` → `{id, field1, field2, ...}` (no vector)
+ * - `SELECT col1, col2` → `{col1, col2}`
+ * - `SELECT similarity() AS score, title` → `{score, title}`
+ */
+type QueryResult = Record<string, unknown>;
 /** Query execution statistics */
 interface QueryStats {
     /** Execution time in milliseconds */
@@ -407,6 +478,31 @@ interface IVelesDBBackend {
     trainPq(collection: string, options?: PqTrainOptions): Promise<string>;
     /** Stream-insert documents with backpressure support */
     streamInsert(collection: string, docs: VectorDocument[]): Promise<void>;
+    /** Create a graph collection */
+    createGraphCollection(name: string, config?: GraphCollectionConfig): Promise<void>;
+    /** Get collection statistics */
+    getCollectionStats(collection: string): Promise<CollectionStatsResponse | null>;
+    /** Analyze a collection */
+    analyzeCollection(collection: string): Promise<CollectionStatsResponse>;
+    /** Get collection configuration */
+    getCollectionConfig(collection: string): Promise<CollectionConfigResponse>;
+    /** Search returning only IDs and scores */
+    searchIds(collection: string, query: number[] | Float32Array, options?: SearchOptions): Promise<Array<{
+        id: number;
+        score: number;
+    }>>;
+    /** Store a semantic fact */
+    storeSemanticFact(collection: string, entry: SemanticEntry): Promise<void>;
+    /** Search semantic memory */
+    searchSemanticMemory(collection: string, embedding: number[], k?: number): Promise<SearchResult[]>;
+    /** Record an episodic event */
+    recordEpisodicEvent(collection: string, event: EpisodicEvent): Promise<void>;
+    /** Recall episodic events */
+    recallEpisodicEvents(collection: string, embedding: number[], k?: number): Promise<SearchResult[]>;
+    /** Store a procedural pattern */
+    storeProceduralPattern(collection: string, pattern: ProceduralPattern): Promise<void>;
+    /** Match procedural patterns */
+    matchProceduralPatterns(collection: string, embedding: number[], k?: number): Promise<SearchResult[]>;
 }
 /** Error types */
 declare class VelesDBError extends Error {
@@ -428,6 +524,36 @@ declare class BackpressureError extends VelesDBError {
     constructor(message?: string);
 }
 
+/**
+ * Agent Memory facade for VelesDB.
+ *
+ * Provides semantic, episodic, and procedural memory abstractions
+ * on top of the VelesDB backend interface.
+ */
+
+/**
+ * Agent Memory client for semantic, episodic, and procedural memory
+ */
+declare class AgentMemoryClient {
+    private readonly backend;
+    private readonly config?;
+    constructor(backend: IVelesDBBackend, config?: AgentMemoryConfig | undefined);
+    /** Configured embedding dimension (default: 384) */
+    get dimension(): number;
+    /** Store a semantic fact */
+    storeFact(collection: string, entry: SemanticEntry): Promise<void>;
+    /** Search semantic memory */
+    searchFacts(collection: string, embedding: number[], k?: number): Promise<SearchResult[]>;
+    /** Record an episodic event */
+    recordEvent(collection: string, event: EpisodicEvent): Promise<void>;
+    /** Recall episodic events */
+    recallEvents(collection: string, embedding: number[], k?: number): Promise<SearchResult[]>;
+    /** Store a procedural pattern */
+    learnProcedure(collection: string, pattern: ProceduralPattern): Promise<void>;
+    /** Match procedural patterns */
+    recallProcedures(collection: string, embedding: number[], k?: number): Promise<SearchResult[]>;
+}
+
 /**
  * VelesDB Client - Unified interface for all backends
  */
@@ -609,7 +735,7 @@ declare class VelesDB {
      * `, { q: queryVector });
      *
      * for (const r of response.results) {
-     *   console.log(`Node ${r.nodeId}: ${r.fusedScore}`);
+     *   console.log(`ID ${r.id}, title: ${r.title}`);
      * }
      * ```
      */
@@ -794,6 +920,53 @@ declare class VelesDB {
      * ```
      */
     getNodeDegree(collection: string, nodeId: number): Promise<DegreeResponse>;
+    /**
+     * Create a graph collection
+     *
+     * @param name - Collection name
+     * @param config - Optional graph collection configuration
+     */
+    createGraphCollection(name: string, config?: GraphCollectionConfig): Promise<void>;
+    /**
+     * Get collection statistics (requires prior analyze)
+     *
+     * @param collection - Collection name
+     * @returns Statistics or null if not yet analyzed
+     */
+    getCollectionStats(collection: string): Promise<CollectionStatsResponse | null>;
+    /**
+     * Analyze a collection to compute statistics
+     *
+     * @param collection - Collection name
+     * @returns Computed statistics
+     */
+    analyzeCollection(collection: string): Promise<CollectionStatsResponse>;
+    /**
+     * Get collection configuration
+     *
+     * @param collection - Collection name
+     * @returns Collection configuration details
+     */
+    getCollectionConfig(collection: string): Promise<CollectionConfigResponse>;
+    /**
+     * Search returning only IDs and scores (lightweight)
+     *
+     * @param collection - Collection name
+     * @param query - Query vector
+     * @param options - Search options
+     * @returns Array of id/score pairs
+     */
+    searchIds(collection: string, query: number[] | Float32Array, options?: SearchOptions): Promise<Array<{
+        id: number;
+        score: number;
+    }>>;
+    /**
+     * Create an agent memory interface
+     *
+     * @param config - Optional agent memory configuration
+     * @returns AgentMemoryClient instance
+     */
+    agentMemory(config?: AgentMemoryConfig): AgentMemoryClient;
 }
 
 /**
@@ -860,12 +1033,27 @@ declare class WasmBackend implements IVelesDBBackend {
     getNodeDegree(_collection: string, _nodeId: number): Promise<DegreeResponse>;
     trainPq(_collection: string, _options?: PqTrainOptions): Promise<string>;
     streamInsert(_collection: string, _docs: VectorDocument[]): Promise<void>;
+    createGraphCollection(_name: string, _config?: GraphCollectionConfig): Promise<void>;
+    getCollectionStats(_collection: string): Promise<CollectionStatsResponse | null>;
+    analyzeCollection(_collection: string): Promise<CollectionStatsResponse>;
+    getCollectionConfig(_collection: string): Promise<CollectionConfigResponse>;
+    searchIds(_collection: string, _query: number[] | Float32Array, _options?: SearchOptions): Promise<Array<{
+        id: number;
+        score: number;
+    }>>;
+    storeSemanticFact(_collection: string, _entry: SemanticEntry): Promise<void>;
+    searchSemanticMemory(_collection: string, _embedding: number[], _k?: number): Promise<SearchResult[]>;
+    recordEpisodicEvent(_collection: string, _event: EpisodicEvent): Promise<void>;
+    recallEpisodicEvents(_collection: string, _embedding: number[], _k?: number): Promise<SearchResult[]>;
+    storeProceduralPattern(_collection: string, _pattern: ProceduralPattern): Promise<void>;
+    matchProceduralPatterns(_collection: string, _embedding: number[], _k?: number): Promise<SearchResult[]>;
 }
 
 /**
  * REST Backend for VelesDB
  *
- * Connects to VelesDB server via REST API
+ * Connects to VelesDB server via REST API.
+ * This is the composition root that delegates to focused backend modules.
  */
 
 /**
@@ -884,55 +1072,67 @@ declare class RestBackend implements IVelesDBBackend {
     private ensureInitialized;
     private mapStatusToErrorCode;
     private extractErrorPayload;
-    /**
-     * Parse node ID safely to handle u64 values above Number.MAX_SAFE_INTEGER.
-     * Returns bigint for large values, number for safe values.
-     */
     private parseNodeId;
-    private parseRestPointId;
-    private isLikelyAggregationQuery;
     private request;
+    private asCrudTransport;
+    private asSearchTransport;
+    private asAgentMemoryTransport;
+    private asQueryTransport;
+    private asStreamingTransport;
     createCollection(name: string, config: CollectionConfig): Promise<void>;
     deleteCollection(name: string): Promise<void>;
     getCollection(name: string): Promise<Collection | null>;
     listCollections(): Promise<Collection[]>;
     insert(collection: string, doc: VectorDocument): Promise<void>;
     insertBatch(collection: string, docs: VectorDocument[]): Promise<void>;
-    private sparseVectorToRestFormat;
-    search(collection: string, query: number[] | Float32Array, options?: SearchOptions): Promise<SearchResult[]>;
+    delete(collection: string, id: string | number): Promise<boolean>;
+    get(collection: string, id: string | number): Promise<VectorDocument | null>;
+    isEmpty(collection: string): Promise<boolean>;
+    flush(collection: string): Promise<void>;
+    close(): Promise<void>;
+    search(c: string, q: number[] | Float32Array, o?: SearchOptions): Promise<SearchResult[]>;
     searchBatch(collection: string, searches: Array<{
         vector: number[] | Float32Array;
         k?: number;
         filter?: Record<string, unknown>;
     }>): Promise<SearchResult[][]>;
-    delete(collection: string, id: string | number): Promise<boolean>;
-    get(collection: string, id: string | number): Promise<VectorDocument | null>;
-    textSearch(collection: string, query: string, options?: {
+    textSearch(c: string, q: string, o?: {
         k?: number;
         filter?: Record<string, unknown>;
     }): Promise<SearchResult[]>;
-    hybridSearch(collection: string, vector: number[] | Float32Array, textQuery: string, options?: {
+    hybridSearch(c: string, v: number[] | Float32Array, t: string, o?: {
         k?: number;
         vectorWeight?: number;
         filter?: Record<string, unknown>;
     }): Promise<SearchResult[]>;
-    query(collection: string, queryString: string, params?: Record<string, unknown>, options?: QueryOptions): Promise<QueryApiResponse>;
-    queryExplain(queryString: string, params?: Record<string, unknown>): Promise<ExplainResponse>;
+    multiQuerySearch(c: string, v: Array<number[] | Float32Array>, o?: MultiQuerySearchOptions): Promise<SearchResult[]>;
+    searchIds(c: string, q: number[] | Float32Array, o?: SearchOptions): Promise<Array<{
+        id: number;
+        score: number;
+    }>>;
+    query(c: string, q: string, p?: Record<string, unknown>, o?: QueryOptions): Promise<QueryApiResponse>;
+    queryExplain(q: string, p?: Record<string, unknown>): Promise<ExplainResponse>;
     collectionSanity(collection: string): Promise<CollectionSanityResponse>;
-    multiQuerySearch(collection: string, vectors: Array<number[] | Float32Array>, options?: MultiQuerySearchOptions): Promise<SearchResult[]>;
-    isEmpty(collection: string): Promise<boolean>;
-    flush(collection: string): Promise<void>;
-    trainPq(collection: string, options?: PqTrainOptions): Promise<string>;
-    streamInsert(collection: string, docs: VectorDocument[]): Promise<void>;
-    close(): Promise<void>;
+    addEdge(collection: string, edge: AddEdgeRequest): Promise<void>;
+    getEdges(collection: string, options?: GetEdgesOptions): Promise<GraphEdge[]>;
+    traverseGraph(collection: string, req: TraverseRequest): Promise<TraverseResponse>;
+    getNodeDegree(collection: string, nodeId: number): Promise<DegreeResponse>;
+    createGraphCollection(name: string, config?: GraphCollectionConfig): Promise<void>;
     createIndex(collection: string, options: CreateIndexOptions): Promise<void>;
     listIndexes(collection: string): Promise<IndexInfo[]>;
     hasIndex(collection: string, label: string, property: string): Promise<boolean>;
     dropIndex(collection: string, label: string, property: string): Promise<boolean>;
-    addEdge(collection: string, edge: AddEdgeRequest): Promise<void>;
-    getEdges(collection: string, options?: GetEdgesOptions): Promise<GraphEdge[]>;
-    traverseGraph(collection: string, request: TraverseRequest): Promise<TraverseResponse>;
-    getNodeDegree(collection: string, nodeId: number): Promise<DegreeResponse>;
+    getCollectionStats(collection: string): Promise<CollectionStatsResponse | null>;
+    analyzeCollection(collection: string): Promise<CollectionStatsResponse>;
+    getCollectionConfig(collection: string): Promise<CollectionConfigResponse>;
+    trainPq(collection: string, options?: PqTrainOptions): Promise<string>;
+    streamInsert(collection: string, docs: VectorDocument[]): Promise<void>;
+    storeSemanticFact(collection: string, entry: SemanticEntry): Promise<void>;
+    searchSemanticMemory(collection: string, embedding: number[], k?: number): Promise<SearchResult[]>;
+    recordEpisodicEvent(collection: string, event: EpisodicEvent): Promise<void>;
+    recallEpisodicEvents(collection: string, embedding: number[], k?: number): Promise<SearchResult[]>;
+    storeProceduralPattern(collection: string, pattern: ProceduralPattern): Promise<void>;
+    matchProceduralPatterns(collection: string, embedding: number[], k?: number): Promise<SearchResult[]>;
 }
 
 /**
@@ -942,7 +1142,7 @@ declare class RestBackend implements IVelesDBBackend {
  *
  * @example
  * ```typescript
- * import { velesql } from '@velesdb/sdk';
+ * import { velesql } from '@wiscale/velesdb-sdk';
  *
  * const query = velesql()
  *   .match('d', 'Document')
@@ -1125,4 +1325,4 @@ declare class VelesQLBuilder {
  */
 declare function velesql(): VelesQLBuilder;
 
-export { type AddEdgeRequest, type AggregationQueryResponse, type BackendType, BackpressureError, type Collection, type CollectionConfig, type CollectionSanityChecks, type CollectionSanityDiagnostics, type CollectionSanityResponse, type CollectionType, ConnectionError, type CreateIndexOptions, type DegreeResponse, type DistanceMetric, type EdgesResponse, type ExplainCost, type ExplainFeatures, type ExplainPlanStep, type ExplainResponse, type FusionOptions, type FusionStrategy$1 as FusionStrategy, type GetEdgesOptions, type GraphEdge, type IVelesDBBackend, type IndexInfo, type IndexType, type MultiQuerySearchOptions, type NearVectorOptions, NotFoundError, type PqTrainOptions, type QueryApiResponse, type QueryOptions, type QueryResponse, type QueryResult, type QueryStats, type RelDirection, type RelOptions, RestBackend, type RestPointId, type SearchOptions, type SearchResult, type SparseVector, type StorageMode, type TraversalResultItem, type TraversalStats, type TraverseRequest, type TraverseResponse, ValidationError, type VectorDocument, VelesDB, type VelesDBConfig, VelesDBError, VelesQLBuilder, WasmBackend, velesql };
+export { type AddEdgeRequest, AgentMemoryClient, type AgentMemoryConfig, type AggregationQueryResponse, type BackendType, BackpressureError, type Collection, type CollectionConfig, type CollectionConfigResponse, type CollectionSanityChecks, type CollectionSanityDiagnostics, type CollectionSanityResponse, type CollectionStatsResponse, type CollectionType, ConnectionError, type CreateIndexOptions, type DegreeResponse, type DistanceMetric, type EdgesResponse, type EpisodicEvent, type ExplainCost, type ExplainFeatures, type ExplainPlanStep, type ExplainResponse, type FusionOptions, type FusionStrategy$1 as FusionStrategy, type GetEdgesOptions, type GraphCollectionConfig, type GraphEdge, type GraphSchemaMode, type HnswParams, type IVelesDBBackend, type IndexInfo, type IndexType, type MultiQuerySearchOptions, type NearVectorOptions, NotFoundError, type PqTrainOptions, type ProceduralPattern, type QueryApiResponse, type QueryOptions, type QueryResponse, type QueryResult, type QueryStats, type RelDirection, type RelOptions, RestBackend, type RestPointId, type SearchOptions, type SearchResult, type SemanticEntry, type SparseVector, type StorageMode, type TraversalResultItem, type TraversalStats, type TraverseRequest, type TraverseResponse, ValidationError, type VectorDocument, VelesDB, type VelesDBConfig, VelesDBError, VelesQLBuilder, WasmBackend, velesql };