@nebula-ai/sdk 0.0.24 → 0.0.29

package/README.md

@@ -29,26 +29,26 @@ const client = new NebulaClient({
 });
 
 // Create a cluster
-const cluster = await client.createCluster(
-  'My Project', 
-  'A collection of project memories'
-);
+const cluster = await client.createCluster({
+  name: 'My Project',
+  description: 'A collection of project memories'
+});
 
 // 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' }
 });
 
 // Search for memories with advanced options
-const results = await client.search(
-  'project information',
-  [cluster.id],
-  5,
-  RetrievalType.ADVANCED,
-  { 'metadata.category': 'project' }
-);
+const results = await client.search({
+  query: 'project information',
+  collection_ids: [cluster.id],
+  limit: 5,
+  retrieval_type: RetrievalType.ADVANCED,
+  filters: { 'metadata.category': 'project' }
+});
 
 console.log('Found memories:', results);
 ```
@@ -72,29 +72,42 @@ new NebulaClient(config: NebulaClientConfig)
 
 ```typescript
 // Create a new cluster
-await client.createCluster(name: string, description?: string, metadata?: Record<string, any>)
+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)
 
 // List all clusters
-await client.listClusters(limit?: number, offset?: number)
+await client.listClusters(options?: { limit?: number, offset?: number })
 
 // Update a cluster
-await client.updateCluster(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(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,24 +130,52 @@ await client.storeMemories(memories: Memory[])
 await client.getMemory(memoryId: string)
 
 // List memories from clusters
-await client.listMemories(clusterIds: 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 a memory
-await client.delete(memoryId: string)
+// Delete one or more memories
+// Single deletion:
+await client.delete('memory-id') // Returns: boolean
+
+// Batch deletion:
+await client.delete(['id1', 'id2', 'id3']) // Returns: detailed results object
 ```
 
 #### Search
 
 ```typescript
 // Search within clusters
-await client.search(
+await client.search(options: {
   query: string,
-  clusters: string | string[],
-  limitOrOptions?: number | { limit?: number },
-  retrievalType?: RetrievalType | string,
+  collection_ids: string | string[],
+  limit?: number,
+  retrieval_type?: RetrievalType | string,
   filters?: Record<string, any>,
   searchSettings?: Record<string, any>
-)
+})
 ```
 
 #### Health Check
@@ -150,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)
@@ -166,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;
 }
@@ -220,13 +261,13 @@ enum RetrievalType {
 The search method supports advanced configuration:
 
 ```typescript
-const results = await client.search(
-  'query',
-  [clusterId],
-  10,
-  RetrievalType.ADVANCED,
-  { 'metadata.category': 'science' },
-  {
+const results = await client.search({
+  query: 'query',
+  collection_ids: [collectionId],
+  limit: 10,
+  retrieval_type: RetrievalType.ADVANCED,
+  filters: { 'metadata.category': 'science' },
+  searchSettings: {
     graph_settings: {
       enabled: true,
       bfs_enabled: true,
@@ -234,7 +275,7 @@ const results = await client.search(
     },
     num_sub_queries: 3
   }
-);
+});
 ```
 
 ### Error Handling
@@ -252,7 +293,7 @@ import {
 } from '@nebula-ai/sdk';
 
 try {
-  await client.search('query', [clusterId]);
+  await client.search({ query: 'query', collection_ids: [collectionId] });
 } catch (error) {
   if (error instanceof NebulaAuthenticationException) {
     console.log('Invalid API key');
@@ -277,20 +318,20 @@ const client = new NebulaClient({ apiKey: 'your-key' });
 
 async function manageMemories() {
   // Create a cluster
-  const cluster = await client.createCluster(
-    'Knowledge Base',
-    'My personal knowledge repository'
-  );
+  const cluster = await client.createCluster({
+    name: 'Knowledge Base',
+    description: 'My personal knowledge repository'
+  });
 
   // 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' }
     }
@@ -301,8 +342,24 @@ async function manageMemories() {
   console.log('Stored memories:', memoryIds);
 
   // Search for memories
-  const results = await client.search('JavaScript', [cluster.id]);
+  const results = await client.search({ query: 'JavaScript', collection_ids: [cluster.id] });
   console.log('Search results:', results);
+
+  // Delete a single memory
+  const deleted = await client.delete(memoryIds[0]);
+  console.log('Deleted single memory:', deleted); // true
+
+  // Delete multiple memories at once
+  const batchResult = await client.delete([memoryIds[1], memoryIds[2]]);
+  console.log('Batch deletion results:', batchResult);
+  // {
+  //   message: "Deleted 2 of 2 documents",
+  //   results: {
+  //     successful: ["id1", "id2"],
+  //     failed: [],
+  //     summary: { total: 2, succeeded: 2, failed: 0 }
+  //   }
+  // }
 }
 ```
 
@@ -314,18 +371,21 @@ import { NebulaClient } from '@nebula-ai/sdk';
 const client = new NebulaClient({ apiKey: 'your-key' });
 
 async function trackConversation() {
-  const cluster = await client.createCluster('Conversations', 'AI chat history');
+  const cluster = await client.createCluster({
+    name: 'Conversations',
+    description: 'AI chat history'
+  });
 
   // 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' }
@@ -350,7 +410,7 @@ const client = new NebulaClient({ apiKey: 'your-key' });
 
 async function manageConversations() {
   // List all conversations
-  const conversations = await client.listConversations(10, 0);
+  const conversations = await client.listConversations({ limit: 10, offset: 0 });
   console.log('All conversations:', conversations);
 
   // Get messages from a specific conversation
@@ -375,30 +435,32 @@ import { NebulaClient, RetrievalType } from '@nebula-ai/sdk';
 const client = new NebulaClient({ apiKey: 'your-key' });
 
 async function advancedSearch() {
-  const cluster = await client.createCluster('Knowledge Graph', 'Entity relationships');
+  const cluster = await client.createCluster({
+    name: 'Knowledge Graph',
+    description: 'Entity relationships'
+  });
 
   // 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' }
   });
 
   // Search with graph settings
-  const results = await client.search(
-    'Einstein relativity',
-    [cluster.id],
-    10,
-    RetrievalType.ADVANCED,
-    undefined,
-    {
+  const results = await client.search({
+    query: 'Einstein relativity',
+    collection_ids: [cluster.id],
+    limit: 10,
+    retrieval_type: RetrievalType.ADVANCED,
+    searchSettings: {
       graph_settings: {
         enabled: true,
         bfs_enabled: true,
         bfs_max_depth: 2
       }
     }
-  );
+  });
 
   // Handle both chunk and graph results
   results.forEach(result => {