@wiscale/velesdb-sdk 1.15.0 → 1.18.0

package/dist/index.js

@@ -105,6 +105,7 @@ __export(index_exports, {
   IoError: () => IoError,
   NodeNotFoundError: () => NodeNotFoundError,
   NotFoundError: () => NotFoundError,
+  OpenAIEmbedder: () => OpenAIEmbedder,
   OverflowError: () => OverflowError,
   PointNotFoundError: () => PointNotFoundError,
   QueryError: () => QueryError,
@@ -725,49 +726,49 @@ var VELES_ERROR_CODES = [
   "VELES-035",
   "VELES-036"
 ];
-var CODE_TO_CLASS = {
-  "VELES-001": CollectionExistsError,
-  "VELES-002": CollectionNotFoundError,
-  "VELES-003": PointNotFoundError,
-  "VELES-004": DimensionMismatchError,
-  "VELES-005": InvalidVectorError,
-  "VELES-006": StorageError,
-  "VELES-007": IndexError,
-  "VELES-008": IndexCorruptedError,
-  "VELES-009": ConfigError,
-  "VELES-010": QueryError,
-  "VELES-011": IoError,
-  "VELES-012": SerializationError,
-  "VELES-013": InternalError,
-  "VELES-014": VectorNotAllowedError,
-  "VELES-015": SearchNotSupportedError,
-  "VELES-016": VectorRequiredError,
-  "VELES-017": SchemaValidationError,
-  "VELES-018": GraphNotSupportedError,
-  "VELES-019": EdgeExistsError,
-  "VELES-020": EdgeNotFoundError,
-  "VELES-021": InvalidEdgeLabelError,
-  "VELES-022": NodeNotFoundError,
-  "VELES-023": OverflowError,
-  "VELES-024": ColumnStoreError,
-  "VELES-025": GpuError,
-  "VELES-026": EpochMismatchError,
-  "VELES-027": GuardRailError,
-  "VELES-028": InvalidQuantizerConfigError,
-  "VELES-029": TrainingFailedError,
-  "VELES-030": SparseIndexError,
-  "VELES-031": DatabaseLockedError,
-  "VELES-032": InvalidDimensionError,
-  "VELES-033": AllocationFailedError,
-  "VELES-034": InvalidCollectionNameError,
-  "VELES-035": SnapshotBuildFailedError,
-  "VELES-036": IncompatibleSchemaVersionError
-};
+var CODE_TO_CLASS = /* @__PURE__ */ new Map([
+  ["VELES-001", CollectionExistsError],
+  ["VELES-002", CollectionNotFoundError],
+  ["VELES-003", PointNotFoundError],
+  ["VELES-004", DimensionMismatchError],
+  ["VELES-005", InvalidVectorError],
+  ["VELES-006", StorageError],
+  ["VELES-007", IndexError],
+  ["VELES-008", IndexCorruptedError],
+  ["VELES-009", ConfigError],
+  ["VELES-010", QueryError],
+  ["VELES-011", IoError],
+  ["VELES-012", SerializationError],
+  ["VELES-013", InternalError],
+  ["VELES-014", VectorNotAllowedError],
+  ["VELES-015", SearchNotSupportedError],
+  ["VELES-016", VectorRequiredError],
+  ["VELES-017", SchemaValidationError],
+  ["VELES-018", GraphNotSupportedError],
+  ["VELES-019", EdgeExistsError],
+  ["VELES-020", EdgeNotFoundError],
+  ["VELES-021", InvalidEdgeLabelError],
+  ["VELES-022", NodeNotFoundError],
+  ["VELES-023", OverflowError],
+  ["VELES-024", ColumnStoreError],
+  ["VELES-025", GpuError],
+  ["VELES-026", EpochMismatchError],
+  ["VELES-027", GuardRailError],
+  ["VELES-028", InvalidQuantizerConfigError],
+  ["VELES-029", TrainingFailedError],
+  ["VELES-030", SparseIndexError],
+  ["VELES-031", DatabaseLockedError],
+  ["VELES-032", InvalidDimensionError],
+  ["VELES-033", AllocationFailedError],
+  ["VELES-034", InvalidCollectionNameError],
+  ["VELES-035", SnapshotBuildFailedError],
+  ["VELES-036", IncompatibleSchemaVersionError]
+]);
 function parseVelesError(code, message) {
   if (code === null || code === void 0) {
     return new VelesError(message, "VELES-UNKNOWN");
   }
-  const Cls = CODE_TO_CLASS[code];
+  const Cls = CODE_TO_CLASS.get(code);
   if (Cls !== void 0) {
     return new Cls(message);
   }
@@ -1814,16 +1815,13 @@ async function getEdgeCount(transport, collection) {
   return response.data?.count ?? 0;
 }
 async function listNodes(transport, collection) {
-  const response = await transport.requestJson(
-    "GET",
-    `${collectionPath(collection)}/graph/nodes`
-  );
+  const response = await transport.requestJson("GET", `${collectionPath(collection)}/graph/nodes`);
   throwOnError(response, `Collection '${collection}'`);
   const data = response.data;
   return { nodeIds: data.node_ids, count: data.count };
 }
-function idToNumber(id) {
-  return typeof id === "string" ? Number(id) : id;
+function idToGraphId(id) {
+  return id;
 }
 async function getNodeEdges(transport, collection, nodeId, options) {
   const params = new URLSearchParams();
@@ -1834,9 +1832,9 @@ async function getNodeEdges(transport, collection, nodeId, options) {
   const response = await transport.requestJson("GET", url);
   throwOnError(response, `Collection '${collection}'`);
   return (response.data?.edges ?? []).map((e) => ({
-    id: idToNumber(e.id),
-    source: idToNumber(e.source),
-    target: idToNumber(e.target),
+    id: e.id,
+    source: e.source,
+    target: e.target,
     label: e.label,
     properties: e.properties
   }));
@@ -1846,7 +1844,7 @@ async function getNodePayload(transport, collection, nodeId) {
   throwOnError(response, `Collection '${collection}'`);
   const data = response.data;
   return {
-    nodeId: idToNumber(data.node_id),
+    nodeId: idToGraphId(data.node_id),
     payload: data.payload
   };
 }
@@ -1870,7 +1868,7 @@ async function graphSearch(transport, collection, request2) {
   throwOnError(response, `Collection '${collection}'`);
   const items = (response.data?.results ?? []).map(
     (r) => ({
-      id: idToNumber(r.id),
+      id: idToGraphId(r.id),
       score: r.score,
       payload: r.payload
     })
@@ -1904,9 +1902,11 @@ async function storeSemanticFact(transport, collection, entry) {
         id: entry.id,
         vector: entry.embedding,
         payload: {
+          // Caller metadata is spread first so the reserved keys below
+          // (`_memory_type`, `text`) always win and cannot be clobbered.
+          ...entry.metadata,
           _memory_type: "semantic",
-          text: entry.text,
-          ...entry.metadata
+          text: entry.text
         }
       }]
     }
@@ -1926,16 +1926,20 @@ async function recordEpisodicEvent(transport, collection, event) {
         id,
         vector: event.embedding,
         payload: {
+          // Caller-supplied data/metadata is spread first so the reserved
+          // keys below (`_memory_type`, `event_type`, `timestamp`) always
+          // win and cannot be clobbered.
+          ...event.data,
+          ...event.metadata,
           _memory_type: "episodic",
           event_type: event.eventType,
-          timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-          ...event.data,
-          ...event.metadata
+          timestamp: (/* @__PURE__ */ new Date()).toISOString()
         }
       }]
     }
   );
   throwOnError(response);
+  return id;
 }
 async function recallEpisodicEvents(transport, collection, embedding, k = 5) {
   return transport.searchVectors(collection, embedding, k, { _memory_type: "episodic" });
@@ -1948,16 +1952,21 @@ async function storeProceduralPattern(transport, collection, pattern) {
     {
       points: [{
         id,
+        vector: pattern.embedding,
         payload: {
+          // Caller metadata is spread first so the reserved keys below
+          // (`_memory_type`, `name`, `steps`) always win and cannot be
+          // clobbered.
+          ...pattern.metadata,
           _memory_type: "procedural",
           name: pattern.name,
-          steps: pattern.steps,
-          ...pattern.metadata
+          steps: pattern.steps
         }
       }]
     }
   );
   throwOnError(response);
+  return id;
 }
 async function matchProceduralPatterns(transport, collection, embedding, k = 5) {
   return transport.searchVectors(collection, embedding, k, { _memory_type: "procedural" });
@@ -2111,15 +2120,29 @@ async function addEdge(transport, collection, edge) {
   throwOnError(response, `Collection '${collection}'`);
 }
 function toGraphEdge(e) {
-  const toNum = (v) => typeof v === "string" ? Number(v) : v;
   return {
-    id: toNum(e.id),
-    source: toNum(e.source),
-    target: toNum(e.target),
+    id: e.id,
+    source: e.source,
+    target: e.target,
     label: e.label,
     properties: e.properties
   };
 }
+function toTraverseResponse(data) {
+  return {
+    results: data.results.map((r) => ({
+      targetId: r.target_id,
+      depth: r.depth,
+      path: r.path
+    })),
+    nextCursor: data.next_cursor ?? void 0,
+    hasMore: data.has_more,
+    stats: {
+      visited: data.stats.visited,
+      depthReached: data.stats.depth_reached
+    }
+  };
+}
 async function getEdges(transport, collection, options) {
   const queryParams = options?.label ? `?label=${encodeURIComponent(options.label)}` : "";
   const response = await transport.requestJson(
@@ -2143,20 +2166,7 @@ async function traverseGraph(transport, collection, request2) {
     }
   );
   throwOnError(response, `Collection '${collection}'`);
-  const data = response.data;
-  return {
-    results: data.results.map((r) => ({
-      targetId: r.target_id,
-      depth: r.depth,
-      path: r.path
-    })),
-    nextCursor: data.next_cursor ?? void 0,
-    hasMore: data.has_more,
-    stats: {
-      visited: data.stats.visited,
-      depthReached: data.stats.depth_reached
-    }
-  };
+  return toTraverseResponse(response.data);
 }
 async function getNodeDegree(transport, collection, nodeId) {
   const response = await transport.requestJson(
@@ -2191,20 +2201,7 @@ async function traverseParallel(transport, collection, request2) {
     }
   );
   throwOnError(response, `Collection '${collection}'`);
-  const data = response.data;
-  return {
-    results: data.results.map((r) => ({
-      targetId: r.target_id,
-      depth: r.depth,
-      path: r.path
-    })),
-    nextCursor: data.next_cursor ?? void 0,
-    hasMore: data.has_more,
-    stats: {
-      visited: data.stats.visited,
-      depthReached: data.stats.depth_reached
-    }
-  };
+  return toTraverseResponse(response.data);
 }
 
 // src/backends/query-backend.ts
@@ -2889,7 +2886,16 @@ var AgentMemoryClient = class {
     this.backend = backend;
     this.config = config;
   }
-  /** Configured embedding dimension (default: 384) */
+  /**
+   * Advisory embedding dimension passed at construction (default: 384).
+   *
+   * This value is **not** enforced and does not create or size any
+   * collection — the dimension that actually governs storage and search
+   * is the one fixed when the collection was created
+   * (`db.createCollection(name, { dimension, metric: 'cosine' })`).
+   * Embeddings you pass to `storeFact` / `recordEvent` / `learnProcedure`
+   * must match that collection dimension.
+   */
   get dimension() {
     return this.config?.dimension ?? 384;
   }
@@ -2901,7 +2907,7 @@ var AgentMemoryClient = class {
   async searchFacts(collection, embedding, k = 5) {
     return this.backend.searchSemanticMemory(collection, embedding, k);
   }
-  /** Record an episodic event */
+  /** Record an episodic event. Returns the generated point ID. */
   async recordEvent(collection, event) {
     return this.backend.recordEpisodicEvent(collection, event);
   }
@@ -2909,7 +2915,7 @@ var AgentMemoryClient = class {
   async recallEvents(collection, embedding, k = 5) {
     return this.backend.recallEpisodicEvents(collection, embedding, k);
   }
-  /** Store a procedural pattern */
+  /** Store a procedural pattern. Returns the generated point ID. */
   async learnProcedure(collection, pattern) {
     return this.backend.storeProceduralPattern(collection, pattern);
   }
@@ -2917,6 +2923,10 @@ var AgentMemoryClient = class {
   async recallProcedures(collection, embedding, k = 5) {
     return this.backend.matchProceduralPatterns(collection, embedding, k);
   }
+  /** Delete a memory entry (fact, event, or procedure) by its point ID. */
+  async deleteMemory(collection, id) {
+    return this.backend.delete(collection, id);
+  }
 };
 
 // src/client/validation.ts
@@ -2939,7 +2949,8 @@ function validateDocsBatch(docs, validateDoc) {
   }
 }
 function validateDocument(doc, config) {
-  if (doc.id === void 0 || doc.id === null) {
+  const id = doc.id;
+  if (id === void 0 || id === null) {
     throw new ValidationError("Document ID is required");
   }
   requireVector(doc.vector, "Vector");
@@ -2994,11 +3005,15 @@ function trainPq2(backend, collection, options) {
   return backend.trainPq(collection, options);
 }
 function streamInsert2(backend, config, collection, docs) {
-  validateDocsBatch(docs, (doc) => validateDocument(doc, config));
+  validateDocsBatch(docs, (doc) => {
+    validateDocument(doc, config);
+  });
   return backend.streamInsert(collection, docs);
 }
 function streamUpsertPoints2(backend, config, collection, docs) {
-  validateDocsBatch(docs, (doc) => validateDocument(doc, config));
+  validateDocsBatch(docs, (doc) => {
+    validateDocument(doc, config);
+  });
   return backend.streamUpsertPoints(collection, docs);
 }
 function scroll2(backend, collection, request2) {
@@ -3051,12 +3066,15 @@ function aggregate2(backend, queryString, params, options) {
 }
 
 // src/client/graph-methods.ts
+function isGraphNodeId(value) {
+  return typeof value === "number" || typeof value === "string";
+}
 function addEdge2(backend, collection, edge) {
   if (!edge.label || typeof edge.label !== "string") {
     throw new ValidationError("Edge label is required and must be a string");
   }
-  if (typeof edge.source !== "number" || typeof edge.target !== "number") {
-    throw new ValidationError("Edge source and target must be numbers");
+  if (!isGraphNodeId(edge.source) || !isGraphNodeId(edge.target)) {
+    throw new ValidationError("Edge source and target must be numbers or strings");
   }
   return backend.addEdge(collection, edge);
 }
@@ -3064,8 +3082,8 @@ function getEdges2(backend, collection, options) {
   return backend.getEdges(collection, options);
 }
 function traverseGraph2(backend, collection, request2) {
-  if (typeof request2.source !== "number") {
-    throw new ValidationError("Source node ID must be a number");
+  if (!isGraphNodeId(request2.source)) {
+    throw new ValidationError("Source node ID must be a number or string");
   }
   if (request2.strategy && !["bfs", "dfs"].includes(request2.strategy)) {
     throw new ValidationError("Strategy must be 'bfs' or 'dfs'");
@@ -3076,6 +3094,9 @@ function traverseParallel2(backend, collection, request2) {
   if (!Array.isArray(request2.sources) || request2.sources.length === 0) {
     throw new ValidationError("At least one source node ID is required");
   }
+  if (!request2.sources.every(isGraphNodeId)) {
+    throw new ValidationError("Source node IDs must be numbers or strings");
+  }
   return backend.traverseParallel(collection, request2);
 }
 function getNodeDegree2(backend, collection, nodeId) {
@@ -3131,13 +3152,14 @@ var VelesDB = class {
     this.backend = this.createBackend(config);
   }
   validateConfig(config) {
-    if (!config.backend) {
+    const backend = config.backend;
+    if (!backend) {
       throw new ValidationError("Backend type is required");
     }
-    if (config.backend !== "wasm" && config.backend !== "rest") {
-      throw new ValidationError(`Invalid backend type: ${config.backend}. Use 'wasm' or 'rest'`);
+    if (backend !== "wasm" && backend !== "rest") {
+      throw new ValidationError(`Invalid backend type: ${backend}. Use 'wasm' or 'rest'`);
     }
-    if (config.backend === "rest" && !config.url) {
+    if (backend === "rest" && !config.url) {
       throw new ValidationError("URL is required for REST backend");
     }
   }
@@ -3145,10 +3167,14 @@ var VelesDB = class {
     switch (config.backend) {
       case "wasm":
         return new WasmBackend();
-      case "rest":
+      case "rest": {
+        if (!config.url) {
+          throw new ValidationError("URL is required for REST backend");
+        }
         return new RestBackend(config.url, config.apiKey, config.timeout);
+      }
       default:
-        throw new ValidationError(`Unknown backend: ${config.backend}`);
+        throw new ValidationError(`Unknown backend: ${String(config.backend)}`);
     }
   }
   /** Initialize the client. Must be called before any other operations. */
@@ -3207,7 +3233,9 @@ var VelesDB = class {
   }
   async upsertBatch(collection, docs) {
     this.ensureInitialized();
-    validateDocsBatch(docs, (doc) => validateDocument(doc, this.config));
+    validateDocsBatch(docs, (doc) => {
+      validateDocument(doc, this.config);
+    });
     await this.backend.upsertBatch(collection, docs);
   }
   async delete(collection, id) {
@@ -3723,13 +3751,14 @@ var VelesQLBuilder = class _VelesQLBuilder {
     return `*${min}..${max}`;
   }
   buildWhereClause() {
-    if (this.state.whereClauses.length === 0) return "";
-    const first = this.state.whereClauses[0];
-    if (!first) return "";
-    let result = first;
-    for (let i = 1; i < this.state.whereClauses.length; i++) {
-      const operator = this.state.whereOperators[i - 1] ?? "AND";
-      const clause = this.state.whereClauses[i];
+    let result = "";
+    for (const [idx, clause] of this.state.whereClauses.entries()) {
+      if (idx === 0) {
+        if (!clause) return "";
+        result = clause;
+        continue;
+      }
+      const operator = this.state.whereOperators[idx - 1] ?? "AND";
       if (clause) {
         result += ` ${operator} ${clause}`;
       }
@@ -3743,13 +3772,14 @@ function velesql() {
 
 // src/filter.ts
 function isTypedFilter(input) {
-  if (typeof input !== "object" || input === null) {
+  const value = input;
+  if (typeof value !== "object" || value === null) {
     return false;
   }
-  if (!("condition" in input)) {
+  if (!("condition" in value)) {
     return false;
   }
-  const cond = input.condition;
+  const cond = value.condition;
   return typeof cond === "object" && cond !== null;
 }
 function normalizeFilter(input) {
@@ -3884,6 +3914,47 @@ var f = {
     return { condition: { type: "not", condition: filter.condition } };
   }
 };
+
+// src/embed.ts
+var OpenAIEmbedder = class {
+  constructor(options) {
+    this.model = options.model ?? "text-embedding-3-small";
+    this.apiKey = options.apiKey;
+    this.baseUrl = options.baseUrl?.replace(/\/$/, "") ?? "https://api.openai.com/v1";
+    this.requestedDimensions = options.dimensions;
+    this.dimension = options.dimensions ?? 0;
+  }
+  async embed(texts) {
+    if (texts.length === 0) return [];
+    const body = { model: this.model, input: texts };
+    if (this.requestedDimensions !== void 0) {
+      body["dimensions"] = this.requestedDimensions;
+    }
+    const response = await fetch(`${this.baseUrl}/embeddings`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.apiKey}`
+      },
+      body: JSON.stringify(body)
+    });
+    if (!response.ok) {
+      const text = await response.text().catch(() => "");
+      throw new Error(
+        `OpenAI embeddings request failed: ${response.status} ${response.statusText} \u2014 ${text.slice(0, 500)}`
+      );
+    }
+    const json = await response.json();
+    const vectors = json.data.map((item) => item.embedding);
+    if (this.dimension === 0) {
+      for (const vec of vectors) {
+        this.dimension = vec.length;
+        break;
+      }
+    }
+    return vectors;
+  }
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AgentMemoryClient,
@@ -3914,6 +3985,7 @@ var f = {
   IoError,
   NodeNotFoundError,
   NotFoundError,
+  OpenAIEmbedder,
   OverflowError,
   PointNotFoundError,
   QueryError,