@nebula-ai/sdk 1.2.0 → 1.2.2

package/README.md

@@ -38,7 +38,6 @@ const memoryId = await client.storeMemory({
 const results = await client.search({
   query: 'machine learning healthcare',
   collection_ids: [collection.id],
-  limit: 5
 });
 
 results.forEach(result => {
@@ -120,7 +119,6 @@ const memory = await client.getMemory('memory-id');
 const results = await client.search({
   query: 'your search query',
   collection_ids: [collection.id],
-  limit: 10
 });
 ```
 

package/dist/index.d.mts

@@ -50,6 +50,7 @@ interface Memory$1 {
     memory_id?: string;
     metadata: Record<string, unknown>;
     authority?: number;
+    snapshot?: Record<string, unknown>;
     chunks?: Chunk[];
     collection_ids?: string[];
     created_at?: string;
@@ -106,7 +107,6 @@ interface GraphCommunityResult {
     metadata: Record<string, unknown>;
 }
 interface SearchOptions {
-    limit: number;
     filters?: Record<string, unknown>;
 }
 interface ActivatedEntity {
@@ -218,6 +218,38 @@ declare class NebulaCollectionNotFoundException extends NebulaException {
 declare class NebulaNotFoundException extends NebulaException {
     constructor(resourceId: string, resourceType?: string);
 }
+/** Portable graph state envelope returned by export and consumed by compute/query. */
+interface SnapshotEnvelope {
+    collection_id: string;
+    graph: GraphPayload;
+    root_hash: string;
+    [key: string]: unknown;
+}
+interface GraphPayload {
+    entities: Record<string, unknown>[];
+    relationships: Record<string, unknown>[];
+    entity_embeddings?: EmbeddingBlock;
+    relationship_desc_embeddings?: EmbeddingBlock;
+    relationship_rel_embeddings?: EmbeddingBlock;
+    [key: string]: unknown;
+}
+interface EmbeddingBlock {
+    dimension: number;
+    matrix_b64: string;
+    present_mask: boolean[];
+}
+/** Full-value diff produced by compute. */
+interface PatchEnvelope {
+    collection_id: string;
+    previous_root_hash: string;
+    next_root_hash: string;
+    put_entities: Record<string, unknown>[];
+    delete_entities: string[];
+    put_relationships: Record<string, unknown>[];
+    delete_relationships: string[];
+    events: Record<string, unknown>[];
+    [key: string]: unknown;
+}
 
 /**
  * Official Nebula JavaScript/TypeScript SDK
@@ -283,7 +315,7 @@ declare class Nebula {
      * - If role is present, creates a conversation
      * - Otherwise, creates a document
      */
-    storeMemory(memory: Memory$1 | Record<string, unknown>, name?: string): Promise<string>;
+    storeMemory(memory: Memory$1 | Record<string, unknown>, name?: string): Promise<string | Record<string, unknown>>;
     /**
      * Internal method to append content to an existing memory
      *
@@ -487,6 +519,7 @@ declare class Nebula {
         effort?: 'auto' | 'low' | 'medium' | 'high';
         filters?: Record<string, unknown>;
         searchSettings?: Record<string, unknown>;
+        snapshot?: Record<string, unknown>;
     }): Promise<MemoryResponse>;
     /** List available connector providers */
     listProviders(): Promise<string[]>;
@@ -532,6 +565,15 @@ declare class Nebula {
         bucket: string;
         expires_in: number;
     }>;
+    /**
+     * Export a collection's full graph state as a portable snapshot.
+     */
+    exportSnapshot(collectionId: string): Promise<SnapshotEnvelope>;
+    /**
+     * Import a snapshot into an ephemeral server-side collection.
+     * @returns The ephemeral collection ID.
+     */
+    importSnapshot(snapshot: SnapshotEnvelope | Record<string, unknown>): Promise<string>;
 }
 
 /**
@@ -554,4 +596,4 @@ type MemoryFactory = {
 declare const Memory: MemoryFactory;
 type Memory = Memory$1;
 
-export { type ActivatedEntity, type ActivatedEpisode, type ActivatedFacet, type ActivatedProcedure, type ActivatedSemantic, type Chunk, type Collection, type FileContentPart, type GraphCommunityResult, type GraphEntityResult, type GraphRelationshipResult, GraphSearchResultType, type GroundedSource, Memory, type MemoryResponse, type MultimodalContentPart, Nebula, NebulaAuthenticationException, type NebulaClientConfig, NebulaClientException, NebulaCollectionNotFoundException, NebulaContent, NebulaException, NebulaNotFoundException, NebulaRateLimitException, NebulaValidationException, type S3FileReferencePart, type SearchOptions, type SearchResult, type StructuredChunk, type TextContentPart, Nebula as default };
+export { type ActivatedEntity, type ActivatedEpisode, type ActivatedFacet, type ActivatedProcedure, type ActivatedSemantic, type Chunk, type Collection, type EmbeddingBlock, type FileContentPart, type GraphCommunityResult, type GraphEntityResult, type GraphPayload, type GraphRelationshipResult, GraphSearchResultType, type GroundedSource, Memory, type MemoryResponse, type MultimodalContentPart, Nebula, NebulaAuthenticationException, type NebulaClientConfig, NebulaClientException, NebulaCollectionNotFoundException, NebulaContent, NebulaException, NebulaNotFoundException, NebulaRateLimitException, NebulaValidationException, type PatchEnvelope, type S3FileReferencePart, type SearchOptions, type SearchResult, type SnapshotEnvelope, type StructuredChunk, type TextContentPart, Nebula as default };

package/dist/index.d.ts

@@ -50,6 +50,7 @@ interface Memory$1 {
     memory_id?: string;
     metadata: Record<string, unknown>;
     authority?: number;
+    snapshot?: Record<string, unknown>;
     chunks?: Chunk[];
     collection_ids?: string[];
     created_at?: string;
@@ -106,7 +107,6 @@ interface GraphCommunityResult {
     metadata: Record<string, unknown>;
 }
 interface SearchOptions {
-    limit: number;
     filters?: Record<string, unknown>;
 }
 interface ActivatedEntity {
@@ -218,6 +218,38 @@ declare class NebulaCollectionNotFoundException extends NebulaException {
 declare class NebulaNotFoundException extends NebulaException {
     constructor(resourceId: string, resourceType?: string);
 }
+/** Portable graph state envelope returned by export and consumed by compute/query. */
+interface SnapshotEnvelope {
+    collection_id: string;
+    graph: GraphPayload;
+    root_hash: string;
+    [key: string]: unknown;
+}
+interface GraphPayload {
+    entities: Record<string, unknown>[];
+    relationships: Record<string, unknown>[];
+    entity_embeddings?: EmbeddingBlock;
+    relationship_desc_embeddings?: EmbeddingBlock;
+    relationship_rel_embeddings?: EmbeddingBlock;
+    [key: string]: unknown;
+}
+interface EmbeddingBlock {
+    dimension: number;
+    matrix_b64: string;
+    present_mask: boolean[];
+}
+/** Full-value diff produced by compute. */
+interface PatchEnvelope {
+    collection_id: string;
+    previous_root_hash: string;
+    next_root_hash: string;
+    put_entities: Record<string, unknown>[];
+    delete_entities: string[];
+    put_relationships: Record<string, unknown>[];
+    delete_relationships: string[];
+    events: Record<string, unknown>[];
+    [key: string]: unknown;
+}
 
 /**
  * Official Nebula JavaScript/TypeScript SDK
@@ -283,7 +315,7 @@ declare class Nebula {
      * - If role is present, creates a conversation
      * - Otherwise, creates a document
      */
-    storeMemory(memory: Memory$1 | Record<string, unknown>, name?: string): Promise<string>;
+    storeMemory(memory: Memory$1 | Record<string, unknown>, name?: string): Promise<string | Record<string, unknown>>;
     /**
      * Internal method to append content to an existing memory
      *
@@ -487,6 +519,7 @@ declare class Nebula {
         effort?: 'auto' | 'low' | 'medium' | 'high';
         filters?: Record<string, unknown>;
         searchSettings?: Record<string, unknown>;
+        snapshot?: Record<string, unknown>;
     }): Promise<MemoryResponse>;
     /** List available connector providers */
     listProviders(): Promise<string[]>;
@@ -532,6 +565,15 @@ declare class Nebula {
         bucket: string;
         expires_in: number;
     }>;
+    /**
+     * Export a collection's full graph state as a portable snapshot.
+     */
+    exportSnapshot(collectionId: string): Promise<SnapshotEnvelope>;
+    /**
+     * Import a snapshot into an ephemeral server-side collection.
+     * @returns The ephemeral collection ID.
+     */
+    importSnapshot(snapshot: SnapshotEnvelope | Record<string, unknown>): Promise<string>;
 }
 
 /**
@@ -554,4 +596,4 @@ type MemoryFactory = {
 declare const Memory: MemoryFactory;
 type Memory = Memory$1;
 
-export { type ActivatedEntity, type ActivatedEpisode, type ActivatedFacet, type ActivatedProcedure, type ActivatedSemantic, type Chunk, type Collection, type FileContentPart, type GraphCommunityResult, type GraphEntityResult, type GraphRelationshipResult, GraphSearchResultType, type GroundedSource, Memory, type MemoryResponse, type MultimodalContentPart, Nebula, NebulaAuthenticationException, type NebulaClientConfig, NebulaClientException, NebulaCollectionNotFoundException, NebulaContent, NebulaException, NebulaNotFoundException, NebulaRateLimitException, NebulaValidationException, type S3FileReferencePart, type SearchOptions, type SearchResult, type StructuredChunk, type TextContentPart, Nebula as default };
+export { type ActivatedEntity, type ActivatedEpisode, type ActivatedFacet, type ActivatedProcedure, type ActivatedSemantic, type Chunk, type Collection, type EmbeddingBlock, type FileContentPart, type GraphCommunityResult, type GraphEntityResult, type GraphPayload, type GraphRelationshipResult, GraphSearchResultType, type GroundedSource, Memory, type MemoryResponse, type MultimodalContentPart, Nebula, NebulaAuthenticationException, type NebulaClientConfig, NebulaClientException, NebulaCollectionNotFoundException, NebulaContent, NebulaException, NebulaNotFoundException, NebulaRateLimitException, NebulaValidationException, type PatchEnvelope, type S3FileReferencePart, type SearchOptions, type SearchResult, type SnapshotEnvelope, type StructuredChunk, type TextContentPart, Nebula as default };

package/dist/index.js

@@ -343,7 +343,7 @@ var _Nebula = class _Nebula {
    */
   async storeMemory(memory, name) {
     let mem;
-    if ("collection_id" in memory) {
+    if ("collection_id" in memory || "snapshot" in memory) {
       mem = memory;
     } else {
       const memRecord2 = memory;
@@ -352,9 +352,23 @@ var _Nebula = class _Nebula {
         content: memRecord2.content || "",
         role: memRecord2.role,
         memory_id: memRecord2.memory_id || memRecord2.memoryId || void 0,
-        metadata: memRecord2.metadata || {}
+        metadata: memRecord2.metadata || {},
+        snapshot: memRecord2.snapshot
       };
     }
+    if (mem.snapshot) {
+      const contentText = await this._serializeContentAsText(mem.content);
+      const payload2 = {
+        snapshot: mem.snapshot,
+        raw_text: contentText
+      };
+      const response2 = await this._makeRequest("POST", "/v1/memories", payload2);
+      const snapshot = response2?.results?.snapshot;
+      if (snapshot) {
+        return snapshot;
+      }
+      return response2?.results ?? {};
+    }
     if (mem.memory_id) {
       return await this._appendToMemory(mem.memory_id, mem);
     }
@@ -823,6 +837,27 @@ var _Nebula = class _Nebula {
    * https://docs.trynebula.ai/guides/metadata-filtering
    */
   async search(options) {
+    if (options.snapshot) {
+      const snapshotData = {
+        snapshot: options.snapshot,
+        query: options.query
+      };
+      if (options.effort) {
+        snapshotData.effort = options.effort;
+      }
+      const response2 = await this._makeRequest("POST", "/v1/memories/search", snapshotData);
+      const memoryResponseData2 = response2.results;
+      return {
+        query: memoryResponseData2.query || options.query,
+        semantics: memoryResponseData2.semantics || memoryResponseData2.knowledge || [],
+        procedures: memoryResponseData2.procedures || [],
+        episodes: memoryResponseData2.episodes || [],
+        sources: memoryResponseData2.sources || [],
+        total_traversal_time_ms: memoryResponseData2.total_traversal_time_ms,
+        token_count: memoryResponseData2.token_count,
+        entities: memoryResponseData2.entities || []
+      };
+    }
     const data = {
       query: options.query
     };
@@ -843,7 +878,12 @@ var _Nebula = class _Nebula {
       data.search_settings = options.searchSettings;
     }
     const collectionIds = data.collection_ids;
-    const extraHeaders = collectionIds && collectionIds.length === 1 ? { "X-Nebula-Collection-Id": collectionIds[0] } : void 0;
+    let extraHeaders;
+    if (collectionIds && collectionIds.length === 1) {
+      extraHeaders = { "X-Nebula-Collection-Id": collectionIds[0] };
+    } else if (collectionIds && collectionIds.length > 1) {
+      extraHeaders = { "X-Nebula-Collection-Id": [...collectionIds].sort().join(",") };
+    }
     const response = await this._makeRequest("POST", "/v1/memories/search", data, void 0, extraHeaders);
     const memoryResponseData = response.results;
     const memoryResponse = {
@@ -1178,6 +1218,29 @@ var _Nebula = class _Nebula {
     }
     return response;
   }
+  // ------------------------------------------------------------------
+  // Device Memory
+  // ------------------------------------------------------------------
+  /**
+   * Export a collection's full graph state as a portable snapshot.
+   */
+  async exportSnapshot(collectionId) {
+    const response = await this._makeRequest("POST", "/v1/device-memory/snapshot/export", {
+      collection_id: collectionId
+    });
+    return response.results ?? response;
+  }
+  /**
+   * Import a snapshot into an ephemeral server-side collection.
+   * @returns The ephemeral collection ID.
+   */
+  async importSnapshot(snapshot) {
+    const response = await this._makeRequest("POST", "/v1/device-memory/snapshot/import", {
+      snapshot
+    });
+    const result = response.results ?? response;
+    return result.ephemeral_collection_id ?? "";
+  }
 };
 // Files larger than 5MB are automatically uploaded to S3
 _Nebula.MAX_INLINE_SIZE = 5 * 1024 * 1024;