@nebula-ai/sdk 0.0.27 → 0.0.31

package/README.md

@@ -36,7 +36,7 @@ const cluster = await client.createCluster({
 
 // Store a memory using the unified Memory model
 const memoryId = await client.storeMemory({
-  cluster_id: cluster.id,
+  collection_id: cluster.id,
   content: 'This is an important piece of information about my project.',
   metadata: { category: 'project', priority: 'high' }
 });
@@ -44,7 +44,7 @@ const memoryId = await client.storeMemory({
 // Search for memories with advanced options
 const results = await client.search({
   query: 'project information',
-  cluster_ids: [cluster.id],
+  collection_ids: [cluster.id],
   limit: 5,
   retrieval_type: RetrievalType.ADVANCED,
   filters: { 'metadata.category': 'project' }
@@ -75,7 +75,7 @@ new NebulaClient(config: NebulaClientConfig)
 await client.createCluster(options: { name: string, description?: string, metadata?: Record<string, any> })
 
 // Get a cluster by ID
-await client.getCluster(clusterId: string)
+await client.getCluster(collectionId: string)
 
 // Get a cluster by name
 await client.getClusterByName(name: string)
@@ -84,17 +84,30 @@ await client.getClusterByName(name: string)
 await client.listClusters(options?: { limit?: number, offset?: number })
 
 // Update a cluster
-await client.updateCluster(options: { clusterId: string, name?: string, description?: string, metadata?: Record<string, any> })
+await client.updateCluster(options: { collectionId: string, name?: string, description?: string, metadata?: Record<string, any> })
 
 // Delete a cluster
-await client.deleteCluster(clusterId: string)
+await client.deleteCluster(collectionId: string)
 ```
 
 #### Conversations
 
 ```typescript
 // List conversations for the authenticated user
-await client.listConversations(options?: { limit?: number, offset?: number, cluster_ids?: string[] })
+await client.listConversations(options?: {
+  limit?: number,
+  offset?: number,
+  collection_ids?: string[],
+  metadata_filters?: Record<string, any>  // MongoDB-like operators: $eq, $ne, $in, $nin, $exists, $and, $or
+})
+
+// Example: Filter playground conversations
+const playgroundConversations = await client.listConversations({
+  collection_ids: ['cluster-id'],
+  metadata_filters: {
+    'metadata.playground': { $eq: true }
+  }
+});
 
 // Get conversation messages
 await client.getConversationMessages(conversationId: string): Promise<MemoryResponse[]>
@@ -117,7 +130,31 @@ await client.storeMemories(memories: Memory[])
 await client.getMemory(memoryId: string)
 
 // List memories from clusters
-await client.listMemories(options: { cluster_ids: string | string[], limit?: number, offset?: number })
+await client.listMemories(options: {
+  collection_ids: string | string[],
+  limit?: number,
+  offset?: number,
+  metadata_filters?: Record<string, any>  // MongoDB-like operators: $eq, $ne, $in, $nin, $exists, $and, $or
+})
+
+// Example: List memories excluding conversations
+const memories = await client.listMemories({
+  collection_ids: ['cluster-id'],
+  metadata_filters: {
+    'metadata.content_type': { $ne: 'conversation' }
+  }
+});
+
+// Example: Complex filter with multiple conditions
+const playgroundMemories = await client.listMemories({
+  collection_ids: ['cluster-id'],
+  metadata_filters: {
+    $and: [
+      { 'metadata.playground': { $eq: true } },
+      { 'metadata.session_id': { $exists: true } }
+    ]
+  }
+});
 
 // Delete one or more memories
 // Single deletion:
@@ -133,7 +170,7 @@ await client.delete(['id1', 'id2', 'id3']) // Returns: detailed results object
 // Search within clusters
 await client.search(options: {
   query: string,
-  cluster_ids: string | string[],
+  collection_ids: string | string[],
   limit?: number,
   retrieval_type?: RetrievalType | string,
   filters?: Record<string, any>,
@@ -154,7 +191,7 @@ await client.healthCheck()
 
 ```typescript
 interface Memory {
-  cluster_id: string;        // Required: cluster to store in
+  collection_id: string;        // Required: cluster to store in
   content: string;           // Required: text content
   role?: string;             // Optional: 'user', 'assistant', or custom (for conversations)
   parent_id?: string;        // Optional: conversation ID (for conversations)
@@ -170,7 +207,7 @@ interface MemoryResponse {
   content?: string;
   chunks?: string[];
   metadata: Record<string, any>;
-  cluster_ids: string[];
+  collection_ids: string[];
   created_at?: string;
   updated_at?: string;
 }
@@ -226,7 +263,7 @@ The search method supports advanced configuration:
 ```typescript
 const results = await client.search({
   query: 'query',
-  cluster_ids: [clusterId],
+  collection_ids: [collectionId],
   limit: 10,
   retrieval_type: RetrievalType.ADVANCED,
   filters: { 'metadata.category': 'science' },
@@ -256,7 +293,7 @@ import {
 } from '@nebula-ai/sdk';
 
 try {
-  await client.search({ query: 'query', cluster_ids: [clusterId] });
+  await client.search({ query: 'query', collection_ids: [collectionId] });
 } catch (error) {
   if (error instanceof NebulaAuthenticationException) {
     console.log('Invalid API key');
@@ -289,12 +326,12 @@ async function manageMemories() {
   // Store memories using the unified model
   const memories = [
     {
-      cluster_id: cluster.id,
+      collection_id: cluster.id,
       content: 'JavaScript is a programming language',
       metadata: { category: 'programming', difficulty: 'beginner' }
     },
     {
-      cluster_id: cluster.id,
+      collection_id: cluster.id,
       content: 'TypeScript adds static typing to JavaScript',
       metadata: { category: 'programming', difficulty: 'beginner' }
     }
@@ -305,7 +342,7 @@ async function manageMemories() {
   console.log('Stored memories:', memoryIds);
 
   // Search for memories
-  const results = await client.search({ query: 'JavaScript', cluster_ids: [cluster.id] });
+  const results = await client.search({ query: 'JavaScript', collection_ids: [cluster.id] });
   console.log('Search results:', results);
 
   // Delete a single memory
@@ -342,13 +379,13 @@ async function trackConversation() {
   // Store conversation turns
   const conversationMemories = [
     {
-      cluster_id: cluster.id,
+      collection_id: cluster.id,
       content: 'What is machine learning?',
       role: 'user',
       metadata: { topic: 'AI' }
     },
     {
-      cluster_id: cluster.id,
+      collection_id: cluster.id,
       content: 'Machine learning is a subset of AI...',
       role: 'assistant',
       metadata: { topic: 'AI' }
@@ -405,7 +442,7 @@ async function advancedSearch() {
 
   // Store knowledge graph data
   await client.storeMemory({
-    cluster_id: cluster.id,
+    collection_id: cluster.id,
     content: 'Einstein developed the theory of relativity',
     metadata: { entity: 'Einstein', concept: 'relativity', field: 'physics' }
   });
@@ -413,7 +450,7 @@ async function advancedSearch() {
   // Search with graph settings
   const results = await client.search({
     query: 'Einstein relativity',
-    cluster_ids: [cluster.id],
+    collection_ids: [cluster.id],
     limit: 10,
     retrieval_type: RetrievalType.ADVANCED,
     searchSettings: {

package/dist/index.d.mts

@@ -3,23 +3,35 @@ declare enum GraphSearchResultType {
     RELATIONSHIP = "relationship",
     COMMUNITY = "community"
 }
+interface Chunk {
+    id: string;
+    content: string;
+    metadata: Record<string, any>;
+    role?: string;
+}
 interface MemoryResponse {
     id: string;
     content?: string;
-    chunks?: string[];
+    chunks?: Chunk[];
     metadata: Record<string, any>;
-    cluster_ids: string[];
+    collection_ids: string[];
     created_at?: string;
     updated_at?: string;
 }
 interface Memory {
-    cluster_id: string;
-    content: string;
+    collection_id: string;
+    content: string | string[] | Array<{
+        content: string;
+        role: string;
+        metadata?: Record<string, any>;
+        authority?: number;
+    }>;
     role?: string;
-    parent_id?: string;
+    memory_id?: string;
     metadata: Record<string, any>;
+    authority?: number;
 }
-interface Cluster {
+interface Collection {
     id: string;
     name: string;
     description?: string;
@@ -37,7 +49,7 @@ interface SearchResult {
     timestamp?: string;
     display_name?: string;
     source_role?: string;
-    document_id?: string;
+    memory_id?: string;
     owner_id?: string;
     content?: string;
     graph_result_type?: GraphSearchResultType;
@@ -104,9 +116,12 @@ declare class NebulaValidationException extends NebulaException {
     details?: any | undefined;
     constructor(message?: string, details?: any | undefined);
 }
-declare class NebulaClusterNotFoundException extends NebulaException {
+declare class NebulaCollectionNotFoundException extends NebulaException {
     constructor(message?: string);
 }
+declare class NebulaNotFoundException extends NebulaException {
+    constructor(resourceId: string, resourceType?: string);
+}
 
 /**
  * Official Nebula JavaScript/TypeScript SDK
@@ -128,48 +143,89 @@ declare class NebulaClient {
     private _buildAuthHeaders;
     /** Make an HTTP request to the Nebula API */
     private _makeRequest;
-    /** Create a new cluster */
-    createCluster(options: {
+    /** Create a new collection */
+    createCollection(options: {
         name: string;
         description?: string;
         metadata?: Record<string, any>;
-    }): Promise<Cluster>;
-    /** Get a specific cluster by ID */
-    getCluster(clusterId: string): Promise<Cluster>;
-    /** Get a specific cluster by name */
-    getClusterByName(name: string): Promise<Cluster>;
-    /** Get all clusters */
-    listClusters(options?: {
+    }): Promise<Collection>;
+    /** Get a specific collection by ID */
+    getCollection(collectionId: string): Promise<Collection>;
+    /** Get a specific collection by name */
+    getCollectionByName(name: string): Promise<Collection>;
+    /** Get all collections */
+    listCollections(options?: {
         limit?: number;
         offset?: number;
-    }): Promise<Cluster[]>;
-    /** List conversations for the authenticated user */
+    }): Promise<Collection[]>;
+    /**
+     * List conversations for the authenticated user with optional metadata filtering
+     *
+     * @param options - Configuration for listing conversations
+     * @param options.limit - Maximum number of conversations to return (default: 100)
+     * @param options.offset - Number of conversations to skip for pagination (default: 0)
+     * @param options.collection_ids - Optional list of collection IDs to filter conversations by
+     * @param options.metadata_filters - Optional metadata filters using MongoDB-like operators.
+     *   Supported operators: $eq, $ne, $in, $nin, $exists, $and, $or
+     *
+     * @returns Promise resolving to array of conversation objects with fields: id, created_at, user_id, name, collection_ids
+     *
+     * @example
+     * // Get all playground conversations
+     * const conversations = await client.listConversations({
+     *   collection_ids: ['collection-id'],
+     *   metadata_filters: {
+     *     'metadata.playground': { $eq: true }
+     *   }
+     * });
+     *
+     * @example
+     * // Filter by session ID
+     * const conversations = await client.listConversations({
+     *   metadata_filters: {
+     *     'metadata.session_id': { $eq: 'session-123' }
+     *   }
+     * });
+     */
     listConversations(options?: {
         limit?: number;
         offset?: number;
-        cluster_ids?: string[];
+        collection_ids?: string[];
+        metadata_filters?: Record<string, any>;
     }): Promise<any[]>;
     /** Get conversation messages directly from the conversations API */
     getConversationMessages(conversationId: string): Promise<MemoryResponse[]>;
     getConversationMessages(conversationIds: string[]): Promise<Record<string, MemoryResponse[]>>;
     /** Helper method to transform conversation messages to MemoryResponse format */
     private _transformConversationMessages;
-    /** Update a cluster */
-    updateCluster(options: {
-        clusterId: string;
+    /** Update a collection */
+    updateCollection(options: {
+        collectionId: string;
         name?: string;
         description?: string;
         metadata?: Record<string, any>;
-    }): Promise<Cluster>;
-    /** Delete a cluster */
-    deleteCluster(clusterId: string): Promise<boolean>;
+    }): Promise<Collection>;
+    /** Delete a collection */
+    deleteCollection(collectionId: string): Promise<boolean>;
+    /**
+     * Legacy convenience: store raw text content into a collection as a document
+     */
+    store(content: string, collectionId: string, metadata?: Record<string, any>): Promise<MemoryResponse>;
     /**
-     * Legacy convenience: store raw text content into a cluster as a document
+     * Store a single memory using the unified engrams API.
+     *
+     * Automatically infers memory type:
+     * - If role is present, creates a conversation
+     * - Otherwise, creates a document
      */
-    store(content: string, clusterId: string, metadata?: Record<string, any>): Promise<MemoryResponse>;
-    /** Store a single memory */
-    storeMemory(memory: Memory | Record<string, any>): Promise<string>;
-    /** Store multiple memories */
+    storeMemory(memory: Memory | Record<string, any>, name?: string): Promise<string>;
+    /**
+     * Internal method to append content to an existing engram
+     *
+     * @throws NebulaNotFoundException if engram_id doesn't exist
+     */
+    private _appendToMemory;
+    /** Store multiple memories using the unified engrams API */
     storeMemories(memories: Memory[]): Promise<string[]>;
     /** Delete one or more memories */
     delete(memoryIds: string | string[]): Promise<boolean | {
@@ -187,22 +243,88 @@ declare class NebulaClient {
             };
         };
     }>;
+    /** Delete a specific chunk or message within a memory */
+    deleteChunk(chunkId: string): Promise<boolean>;
+    /** Update a specific chunk or message within a memory */
+    updateChunk(chunkId: string, content: string, metadata?: Record<string, any>): Promise<boolean>;
+    /**
+     * Update memory-level properties including name, metadata, and collection associations.
+     *
+     * This method allows updating properties of an entire memory (document or conversation)
+     * without modifying its content. For updating individual chunks or messages within a memory,
+     * use updateChunk(). For updating content, use storeMemory() to append.
+     *
+     * @param options - Update configuration
+     * @param options.memoryId - The ID of the memory to update
+     * @param options.name - New name for the memory (useful for conversations and documents)
+     * @param options.metadata - Metadata to set. By default, replaces existing metadata.
+     *                           Set mergeMetadata=true to merge with existing metadata instead.
+     * @param options.collectionIds - New collection associations. Must specify at least one valid collection.
+     * @param options.mergeMetadata - If true, merges provided metadata with existing metadata.
+     *                                If false (default), replaces existing metadata entirely.
+     *
+     * @returns Promise resolving to true if successful
+     *
+     * @throws NebulaNotFoundException if memory_id doesn't exist
+     * @throws NebulaValidationException if validation fails (e.g., no fields provided)
+     * @throws NebulaAuthenticationException if user doesn't have permission to update this memory
+     */
+    updateMemory(options: {
+        memoryId: string;
+        name?: string;
+        metadata?: Record<string, any>;
+        collectionIds?: string[];
+        mergeMetadata?: boolean;
+    }): Promise<boolean>;
     /** Delete a conversation and all its messages */
     deleteConversation(conversationId: string): Promise<boolean>;
-    /** Get all memories from specific clusters */
+    /**
+     * Get all memories from specific collections with optional metadata filtering
+     *
+     * @param options - Configuration for listing memories
+     * @param options.collection_ids - One or more collection IDs to retrieve memories from
+     * @param options.limit - Maximum number of memories to return (default: 100)
+     * @param options.offset - Number of memories to skip for pagination (default: 0)
+     * @param options.metadata_filters - Optional metadata filters using MongoDB-like operators.
+     *   Supported operators: $eq, $ne, $in, $nin, $exists, $and, $or
+     *
+     * @returns Promise resolving to array of MemoryResponse objects
+     *
+     * @example
+     * // Get all playground memories excluding conversations
+     * const memories = await client.listMemories({
+     *   collection_ids: ['collection-id'],
+     *   metadata_filters: {
+     *     'metadata.content_type': { $ne: 'conversation' }
+     *   }
+     * });
+     *
+     * @example
+     * // Complex filter with multiple conditions
+     * const memories = await client.listMemories({
+     *   collection_ids: ['collection-id'],
+     *   metadata_filters: {
+     *     $and: [
+     *       { 'metadata.playground': { $eq: true } },
+     *       { 'metadata.session_id': { $exists: true } }
+     *     ]
+     *   }
+     * });
+     */
     listMemories(options: {
-        cluster_ids: string | string[];
+        collection_ids: string | string[];
         limit?: number;
         offset?: number;
+        metadata_filters?: Record<string, any>;
     }): Promise<MemoryResponse[]>;
-    /** Get a specific memory by ID */
+    /** Get a specific memory by engram ID */
     getMemory(memoryId: string): Promise<MemoryResponse>;
     /**
-     * Search within specific clusters with optional metadata filtering.
+     * Search within specific collections with optional metadata filtering.
      *
      * @param options - Search configuration
      * @param options.query - Search query string
-     * @param options.cluster_ids - One or more cluster IDs to search within
+     * @param options.collection_ids - One or more collection IDs to search within
      * @param options.limit - Maximum number of results to return (default: 10)
      * @param options.retrieval_type - Retrieval strategy (default: ADVANCED)
      * @param options.filters - Optional filters to apply to the search. Supports comprehensive metadata filtering
@@ -215,7 +337,7 @@ declare class NebulaClient {
      * // Basic equality filter
      * await client.search({
      *   query: "machine learning",
-     *   cluster_ids: ["research-cluster"],
+     *   collection_ids: ["research-collection"],
      *   filters: {
      *     "metadata.category": { $eq: "research" },
      *     "metadata.verified": true  // Shorthand for $eq
@@ -226,7 +348,7 @@ declare class NebulaClient {
      * // Numeric comparisons
      * await client.search({
      *   query: "high priority",
-     *   cluster_ids: ["tasks"],
+     *   collection_ids: ["tasks"],
      *   filters: {
      *     "metadata.priority": { $gte: 8 },
      *     "metadata.score": { $lt: 100 }
@@ -237,7 +359,7 @@ declare class NebulaClient {
      * // String matching
      * await client.search({
      *   query: "employees",
-     *   cluster_ids: ["team"],
+     *   collection_ids: ["team"],
      *   filters: {
      *     "metadata.email": { $ilike: "%@company.com" }  // Case-insensitive
      *   }
@@ -247,7 +369,7 @@ declare class NebulaClient {
      * // Array operations
      * await client.search({
      *   query: "developers",
-     *   cluster_ids: ["team"],
+     *   collection_ids: ["team"],
      *   filters: {
      *     "metadata.skills": { $overlap: ["python", "typescript"] }  // Has any
      *   }
@@ -257,7 +379,7 @@ declare class NebulaClient {
      * // Nested paths
      * await client.search({
      *   query: "users",
-     *   cluster_ids: ["profiles"],
+     *   collection_ids: ["profiles"],
      *   filters: {
      *     "metadata.user.preferences.theme": { $eq: "dark" }
      *   }
@@ -267,7 +389,7 @@ declare class NebulaClient {
      * // Complex logical combinations
      * await client.search({
      *   query: "candidates",
-     *   cluster_ids: ["hiring"],
+     *   collection_ids: ["hiring"],
      *   filters: {
      *     $and: [
      *       { "metadata.verified": true },
@@ -295,7 +417,7 @@ declare class NebulaClient {
      */
     search(options: {
         query: string;
-        cluster_ids: string | string[];
+        collection_ids: string | string[];
         limit?: number;
         filters?: Record<string, any>;
         search_mode?: 'fast' | 'super';
@@ -304,13 +426,13 @@ declare class NebulaClient {
     /**
      * Legacy wrapper: store a two-message conversation turn as a document
      */
-    storeConversation(userMessage: string, assistantMessage: string, clusterId: string, sessionId: string): Promise<MemoryResponse>;
+    storeConversation(userMessage: string, assistantMessage: string, collectionId: string, sessionId: string): Promise<MemoryResponse>;
     /**
      * Legacy wrapper: search conversations optionally scoped by session
      */
-    searchConversations(query: string, clusterId: string, sessionId?: string, includeAllSessions?: boolean): Promise<SearchResult[]>;
+    searchConversations(query: string, collectionId: string, sessionId?: string, includeAllSessions?: boolean): Promise<SearchResult[]>;
     healthCheck(): Promise<Record<string, any>>;
-    private _clusterFromDict;
+    private _collectionFromDict;
     private _memoryResponseFromDict;
     private _searchResultFromDict;
     private _searchResultFromGraphDict;
@@ -318,4 +440,4 @@ declare class NebulaClient {
     private _formDataFromObject;
 }
 
-export { type AgentResponse, type Cluster, type GraphCommunityResult, type GraphEntityResult, type GraphRelationshipResult, GraphSearchResultType, type Memory, type MemoryResponse, NebulaAuthenticationException, NebulaClient, type NebulaClientConfig, NebulaClientException, NebulaClusterNotFoundException, NebulaException, NebulaRateLimitException, NebulaValidationException, type SearchOptions, type SearchResult };
+export { type AgentResponse, type Chunk, type Collection, type GraphCommunityResult, type GraphEntityResult, type GraphRelationshipResult, GraphSearchResultType, type Memory, type MemoryResponse, NebulaAuthenticationException, NebulaClient, type NebulaClientConfig, NebulaClientException, NebulaCollectionNotFoundException, NebulaException, NebulaNotFoundException, NebulaRateLimitException, NebulaValidationException, type SearchOptions, type SearchResult };