@nebula-ai/sdk 0.0.31 → 0.0.34

package/README.md

@@ -1,295 +1,168 @@
 # @nebula-ai/sdk
 
-Official JavaScript/TypeScript SDK for Nebula - Memory, Search, and AI-powered conversations.
-
-[![npm version](https://badge.fury.io/js/%40nebula-ai%2Fsdk.svg)](https://badge.fury.io/js/%40nebula-ai%2Fsdk)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
+Persistent memory layer for AI applications. Store, search, and retrieve information with semantic understanding.
 
 ## Installation
 
 ```bash
 npm install @nebula-ai/sdk
-# or
-yarn add @nebula-ai/sdk
-# or
-pnpm add @nebula-ai/sdk
 ```
 
 ## Quick Start
 
 ```typescript
-import { NebulaClient, RetrievalType } from '@nebula-ai/sdk';
+import { NebulaClient } from '@nebula-ai/sdk';
 
-// Initialize the SDK
+// Initialize client
 const client = new NebulaClient({
-  apiKey: 'your-nebula-api-key',
-  baseUrl: 'https://api.nebulacloud.app', // optional, defaults to this
-  timeout: 30000 // optional, defaults to 30 seconds
+  apiKey: 'your-api-key'
 });
 
-// Create a cluster
-const cluster = await client.createCluster({
-  name: 'My Project',
-  description: 'A collection of project memories'
+// Create a collection
+const collection = await client.createCluster({
+  name: 'my_notes'
 });
 
-// Store a memory using the unified Memory model
+// Store a memory
 const memoryId = await client.storeMemory({
-  collection_id: cluster.id,
-  content: 'This is an important piece of information about my project.',
-  metadata: { category: 'project', priority: 'high' }
+  collection_id: collection.id,
+  content: 'Machine learning is transforming healthcare',
+  metadata: { topic: 'AI', importance: 'high' }
 });
 
-// Search for memories with advanced options
+// Search memories
 const results = await client.search({
-  query: 'project information',
-  collection_ids: [cluster.id],
-  limit: 5,
-  retrieval_type: RetrievalType.ADVANCED,
-  filters: { 'metadata.category': 'project' }
+  query: 'machine learning healthcare',
+  collection_ids: [collection.id],
+  limit: 5
 });
 
-console.log('Found memories:', results);
-```
-
-## API Reference
-
-### Constructor
-
-```typescript
-new NebulaClient(config: NebulaClientConfig)
+results.forEach(result => {
+  console.log(`Score: ${result.score?.toFixed(2)}`);
+  console.log(`Content: ${result.content}`);
+});
 ```
 
-**Config Options:**
-- `apiKey` (required): Your Nebula API key
-- `baseUrl` (optional): Custom API base URL, defaults to `https://api.nebulacloud.app`
-- `timeout` (optional): Request timeout in milliseconds, defaults to 30000
-
-### Core Methods
+## Core Operations
 
-#### Clusters
+### Collections
 
 ```typescript
-// Create a new cluster
-await client.createCluster(options: { name: string, description?: string, metadata?: Record<string, any> })
-
-// Get a cluster by ID
-await client.getCluster(collectionId: string)
+// Create
+const collection = await client.createCluster({
+  name: 'my_collection',
+  description: 'Optional description'
+});
 
-// Get a cluster by name
-await client.getClusterByName(name: string)
+// List
+const collections = await client.listClusters();
 
-// List all clusters
-await client.listClusters(options?: { limit?: number, offset?: number })
+// Get by ID or name
+const collection = await client.getCluster(collectionId);
+const collection = await client.getClusterByName('my_collection');
 
-// Update a cluster
-await client.updateCluster(options: { collectionId: string, name?: string, description?: string, metadata?: Record<string, any> })
+// Update
+await client.updateCluster({
+  collectionId,
+  name: 'new_name'
+});
 
-// Delete a cluster
-await client.deleteCluster(collectionId: string)
+// Delete
+await client.deleteCluster(collectionId);
 ```
 
-#### Conversations
+### Store Memories
 
 ```typescript
-// List conversations for the authenticated user
-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 }
-  }
+// Single memory
+const memoryId = await client.storeMemory({
+  collection_id: collection.id,
+  content: 'Your content here',
+  metadata: { category: 'example' }
 });
 
-// Get conversation messages
-await client.getConversationMessages(conversationId: string): Promise<MemoryResponse[]>
-await client.getConversationMessages(conversationIds: string[]): Promise<Record<string, MemoryResponse[]>>
-
-// Delete a conversation and all its messages
-await client.deleteConversation(conversationId: string)
+// Batch storage
+const memoryIds = await client.storeMemories([
+  { collection_id: collection.id, content: 'First memory' },
+  { collection_id: collection.id, content: 'Second memory' }
+]);
 ```
 
-#### Memories
+### Retrieve Memories
 
 ```typescript
-// Store a single memory
-await client.storeMemory(memory: Memory | Record<string, any>)
-
-// Store multiple memories
-await client.storeMemories(memories: Memory[])
-
-// Get a specific memory
-await client.getMemory(memoryId: string)
-
-// List memories from clusters
-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
+// List memories
 const memories = await client.listMemories({
-  collection_ids: ['cluster-id'],
-  metadata_filters: {
-    'metadata.content_type': { $ne: 'conversation' }
-  }
+  collection_ids: [collection.id],
+  limit: 10
 });
 
-// Example: Complex filter with multiple conditions
-const playgroundMemories = await client.listMemories({
-  collection_ids: ['cluster-id'],
+// Filter with metadata
+const memories = await client.listMemories({
+  collection_ids: [collection.id],
   metadata_filters: {
-    $and: [
-      { 'metadata.playground': { $eq: true } },
-      { 'metadata.session_id': { $exists: true } }
-    ]
+    'metadata.category': { $eq: 'example' }
   }
 });
 
-// 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(options: {
-  query: string,
-  collection_ids: string | string[],
-  limit?: number,
-  retrieval_type?: RetrievalType | string,
-  filters?: Record<string, any>,
-  searchSettings?: Record<string, any>
-})
-```
-
-#### Health Check
-
-```typescript
-// Check API health
-await client.healthCheck()
-```
-
-### Data Models
-
-#### Memory (for writing)
-
-```typescript
-interface Memory {
-  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)
-  metadata?: Record<string, any>; // Optional: additional metadata
-}
+// Get specific memory
+const memory = await client.getMemory('memory-id');
 ```
 
-#### MemoryResponse (for reading)
+### Search
 
 ```typescript
-interface MemoryResponse {
-  id: string;
-  content?: string;
-  chunks?: string[];
-  metadata: Record<string, any>;
-  collection_ids: string[];
-  created_at?: string;
-  updated_at?: string;
-}
+// Semantic search
+const results = await client.search({
+  query: 'your search query',
+  collection_ids: [collection.id],
+  limit: 10
+});
 ```
 
-#### SearchResult
+### Delete
 
 ```typescript
-interface SearchResult {
-  id: string;
-  score: number;
-  metadata: Record<string, any>;
-  source?: string;
-
-  // Chunk fields
-  content?: string;
-
-  // Graph fields
-  graph_result_type?: GraphSearchResultType;
-  graph_entity?: GraphEntityResult;
-  graph_relationship?: GraphRelationshipResult;
-  graph_community?: GraphCommunityResult;
-  chunk_ids?: string[];
-}
-```
-
-#### AgentResponse
+// Single deletion
+const deleted = await client.delete('memory-id'); // Returns boolean
 
-```typescript
-interface AgentResponse {
-  content: string;
-  agent_id: string;
-  conversation_id?: string;
-  metadata: Record<string, any>;
-  citations: Record<string, any>[];
-}
+// Batch deletion
+const result = await client.delete(['id1', 'id2', 'id3']); // Returns detailed results
 ```
 
-#### RetrievalType
+## Conversations
 
 ```typescript
-enum RetrievalType {
-  BASIC = "basic",
-  ADVANCED = "advanced",
-  CUSTOM = "custom"
-}
-```
-
-### Search Options
+// Store conversation messages
+const conversationId = await client.storeMemory({
+  collection_id: collection.id,
+  content: 'What is machine learning?',
+  role: 'user'
+});
 
-The search method supports advanced configuration:
+await client.storeMemory({
+  collection_id: collection.id,
+  content: 'Machine learning is a subset of AI...',
+  role: 'assistant',
+  parent_id: conversationId
+});
 
-```typescript
-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,
-      bfs_max_depth: 2
-    },
-    num_sub_queries: 3
-  }
+// List conversations
+const conversations = await client.listConversations({
+  collection_ids: [collection.id]
 });
-```
 
-### Error Handling
+// Get messages
+const messages = await client.getConversationMessages(conversationId);
+```
 
-The SDK provides custom error classes matching the Python SDK:
+## Error Handling
 
 ```typescript
-import { 
-  NebulaException, 
-  NebulaClientException, 
+import {
   NebulaAuthenticationException,
   NebulaRateLimitException,
-  NebulaValidationException,
-  NebulaClusterNotFoundException
+  NebulaValidationException
 } from '@nebula-ai/sdk';
 
 try {
@@ -299,254 +172,15 @@ try {
     console.log('Invalid API key');
   } else if (error instanceof NebulaRateLimitException) {
     console.log('Rate limit exceeded');
-  } else if (error instanceof NebulaValidationException) {
-    console.log('Validation error:', error.details);
-  } else if (error instanceof NebulaException) {
-    console.log('API error:', error.statusCode, error.details);
   }
 }
 ```
 
-## Examples
+## Documentation
 
-### Basic Memory Management
-
-```typescript
-import { NebulaClient } from '@nebula-ai/sdk';
-
-const client = new NebulaClient({ apiKey: 'your-key' });
-
-async function manageMemories() {
-  // Create a cluster
-  const cluster = await client.createCluster({
-    name: 'Knowledge Base',
-    description: 'My personal knowledge repository'
-  });
-
-  // Store memories using the unified model
-  const memories = [
-    {
-      collection_id: cluster.id,
-      content: 'JavaScript is a programming language',
-      metadata: { category: 'programming', difficulty: 'beginner' }
-    },
-    {
-      collection_id: cluster.id,
-      content: 'TypeScript adds static typing to JavaScript',
-      metadata: { category: 'programming', difficulty: 'beginner' }
-    }
-  ];
-
-  // Store all memories at once
-  const memoryIds = await client.storeMemories(memories);
-  console.log('Stored memories:', memoryIds);
-
-  // Search for memories
-  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 }
-  //   }
-  // }
-}
-```
-
-### Conversation Tracking
-
-```typescript
-import { NebulaClient } from '@nebula-ai/sdk';
-
-const client = new NebulaClient({ apiKey: 'your-key' });
-
-async function trackConversation() {
-  const cluster = await client.createCluster({
-    name: 'Conversations',
-    description: 'AI chat history'
-  });
-
-  // Store conversation turns
-  const conversationMemories = [
-    {
-      collection_id: cluster.id,
-      content: 'What is machine learning?',
-      role: 'user',
-      metadata: { topic: 'AI' }
-    },
-    {
-      collection_id: cluster.id,
-      content: 'Machine learning is a subset of AI...',
-      role: 'assistant',
-      metadata: { topic: 'AI' }
-    }
-  ];
-
-  // Store conversation (returns conversation IDs)
-  const conversationIds = await client.storeMemories(conversationMemories);
-  console.log('Conversation IDs:', conversationIds);
-
-  // Retrieve conversation messages directly from conversations API
-  const messages = await client.getConversationMessages(conversationIds[0]);
-  console.log('Conversation messages:', messages);
-}
-
-### Managing Conversations
-
-```typescript
-import { NebulaClient } from '@nebula-ai/sdk';
-
-const client = new NebulaClient({ apiKey: 'your-key' });
-
-async function manageConversations() {
-  // List all conversations
-  const conversations = await client.listConversations({ limit: 10, offset: 0 });
-  console.log('All conversations:', conversations);
-
-  // Get messages from a specific conversation
-  const messages = await client.getConversationMessages('conversation-id');
-  console.log('Conversation messages:', messages);
-
-  // Get messages from multiple conversations at once
-  const multipleMessages = await client.getConversationMessages(['conv1', 'conv2']);
-  console.log('Multiple conversations:', multipleMessages);
-
-  // Delete a conversation
-  await client.deleteConversation('conversation-id');
-  console.log('Conversation deleted');
-}
-```
-
-### Advanced Search with Graph Results
-
-```typescript
-import { NebulaClient, RetrievalType } from '@nebula-ai/sdk';
-
-const client = new NebulaClient({ apiKey: 'your-key' });
-
-async function advancedSearch() {
-  const cluster = await client.createCluster({
-    name: 'Knowledge Graph',
-    description: 'Entity relationships'
-  });
-
-  // Store knowledge graph data
-  await client.storeMemory({
-    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({
-    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 => {
-    if (result.content) {
-      console.log('Chunk result:', result.content);
-    }
-    if (result.graph_entity) {
-      console.log('Entity:', result.graph_entity.name);
-    }
-    if (result.graph_relationship) {
-      console.log('Relationship:', result.graph_relationship.subject, 
-                  result.graph_relationship.predicate, 
-                  result.graph_relationship.object);
-    }
-  });
-}
-```
-
-## Browser vs Node.js
-
-### Browser Usage
-
-```typescript
-import { NebulaClient } from '@nebula-ai/sdk';
-
-const client = new NebulaClient({
-  apiKey: 'your-api-key'
-  // Note: CORS handling is now built into the SDK
-});
-```
-
-### Node.js Usage
-
-```typescript
-import { NebulaClient } from '@nebula-ai/sdk';
-
-const client = new NebulaClient({
-  apiKey: 'your-api-key'
-  // No additional configuration needed
-});
-```
-
-## Development
-
-### Building
-
-```bash
-npm run build
-```
-
-### Testing
-
-```bash
-npm test
-```
-
-### Type Checking
-
-```bash
-npm run type-check
-```
-
-## Contributing
-
-1. Fork the repository
-2. Create a feature branch
-3. Make your changes
-4. Add tests
-5. Submit a pull request
-
-## License
-
-MIT License - see [LICENSE](LICENSE) file for details.
+- [Full Documentation](https://docs.trynebula.ai)
+- [API Reference](https://docs.trynebula.ai/clients/nodejs)
 
 ## Support
 
-- 📧 Email: support@trynebula.ai
-- 🐛 Issues: [GitHub Issues](https://github.com/nebula-cloud/nebula-sdk-js/issues)
-- 📚 Documentation: [Nebula Docs](https://docs.trynebula.ai)
-
-## Changelog
-
-### v0.0.19
-- Complete rewrite to match Python SDK client.py exactly
-- Unified Memory model for text and conversations
-- Advanced search with graph results support
-- Proper error handling matching Python SDK
-- Full TypeScript support with comprehensive interfaces
-- Browser and Node.js compatibility
+Email [support@trynebula.ai](mailto:support@trynebula.ai)

package/dist/index.d.mts

@@ -9,6 +9,14 @@ interface Chunk {
     metadata: Record<string, any>;
     role?: string;
 }
+/**
+ * Structured chunk format returned by backend for conversation messages.
+ * Contains message text and role metadata inline.
+ */
+interface StructuredChunk {
+    text: string;
+    role: 'user' | 'assistant' | 'system';
+}
 interface MemoryResponse {
     id: string;
     content?: string;
@@ -193,11 +201,20 @@ declare class NebulaClient {
         collection_ids?: string[];
         metadata_filters?: Record<string, any>;
     }): Promise<any[]>;
-    /** Get conversation messages directly from the conversations API */
+    /**
+     * Get conversation messages from the engrams API.
+     *
+     * This method retrieves conversation engrams and parses their chunks into structured messages.
+     * Expects conversation engrams to contain structured chunks with role metadata:
+     * `{text: string, role: 'user'|'assistant'|'system'}`.
+     * Converts chunks to `MemoryResponse` objects with proper role metadata.
+     *
+     * @param conversationId - Single conversation ID (returns array of messages)
+     * @param conversationIds - Multiple conversation IDs (returns map of conversation_id -> messages)
+     * @returns Messages for the requested conversation(s)
+     */
     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 collection */
     updateCollection(options: {
         collectionId: string;
@@ -440,4 +457,4 @@ declare class NebulaClient {
     private _formDataFromObject;
 }
 
-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 };
+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, type StructuredChunk };