@nebula-ai/sdk 1.1.4 → 1.1.7

package/README.md

@@ -137,23 +137,27 @@ const result = await client.delete(['id1', 'id2', 'id3']); // Returns detailed r
 const conversationId = await client.storeMemory({
   collection_id: collection.id,
   content: 'What is machine learning?',
-  role: 'user'
+  role: 'user',
+  metadata: { content_type: 'conversation' }
 });
 
 await client.storeMemory({
   collection_id: collection.id,
   content: 'Machine learning is a subset of AI...',
   role: 'assistant',
-  parent_id: conversationId
+  parent_id: conversationId,
+  metadata: { content_type: 'conversation' }
 });
 
-// List conversations
-const conversations = await client.listConversations({
-  collection_ids: [collection.id]
+// List conversation memories
+const conversations = await client.listMemories({
+  collection_ids: [collection.id],
+  metadata_filters: { 'metadata.content_type': { $eq: 'conversation' } }
 });
 
-// Get messages
-const messages = await client.getConversationMessages(conversationId);
+// Get messages from a conversation memory
+const conversation = await client.getMemory(conversationId);
+const messages = conversation.chunks ?? [];
 ```
 
 ## Error Handling

package/dist/index.d.mts

@@ -100,6 +100,56 @@ interface SearchOptions {
     filters?: Record<string, any>;
     search_mode?: 'fast' | 'super';
 }
+interface RecallFocus {
+    schema_weight: number;
+    fact_weight: number;
+    episodic_weight: number;
+}
+interface ActivatedEntity {
+    entity_id: string;
+    entity_name: string;
+    entity_category?: string;
+    activation_score: number;
+    activation_reason?: string;
+    traversal_depth: number;
+    profile?: Record<string, any>;
+}
+interface ActivatedFact {
+    fact_id: string;
+    entity_id?: string;
+    entity_name?: string;
+    facet_name?: string;
+    subject: string;
+    predicate: string;
+    object_value: string;
+    activation_score: number;
+    extraction_confidence: number;
+    corroboration_count: number;
+    source_chunk_ids: string[];
+}
+interface GroundedUtterance {
+    chunk_id: string;
+    text: string;
+    activation_score: number;
+    speaker_name?: string;
+    source_role?: string;
+    timestamp?: string;
+    display_name?: string;
+    supporting_fact_ids: string[];
+    metadata?: Record<string, any>;
+}
+interface MemoryRecall {
+    query: string;
+    entities: ActivatedEntity[];
+    facts: ActivatedFact[];
+    utterances: GroundedUtterance[];
+    focus?: RecallFocus;
+    fact_to_chunks: Record<string, string[]>;
+    entity_to_facts: Record<string, string[]>;
+    retrieved_at: string;
+    total_traversal_time_ms?: number;
+    query_intent?: string;
+}
 interface NebulaClientConfig {
     apiKey: string;
     baseUrl?: string;
@@ -166,55 +216,6 @@ declare class Nebula {
         limit?: number;
         offset?: number;
     }): 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;
-        collection_ids?: string[];
-        metadata_filters?: Record<string, any>;
-    }): Promise<any[]>;
-    /**
-     * 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[]>>;
     /** Update a collection */
     updateCollection(options: {
         collectionId: string;
@@ -293,8 +294,6 @@ declare class Nebula {
         collectionIds?: string[];
         mergeMetadata?: boolean;
     }): Promise<boolean>;
-    /** Delete a conversation and all its messages */
-    deleteConversation(conversationId: string): Promise<boolean>;
     /**
      * Get all memories from specific collections with optional metadata filtering
      *
@@ -434,20 +433,11 @@ declare class Nebula {
      */
     search(options: {
         query: string;
-        collection_ids: string | string[];
+        collection_ids?: string | string[];
         limit?: number;
         filters?: Record<string, any>;
-        search_mode?: 'fast' | 'super';
         searchSettings?: Record<string, any>;
-    }): Promise<SearchResult[]>;
-    /**
-     * Legacy wrapper: store a two-message conversation turn as a document
-     */
-    storeConversation(userMessage: string, assistantMessage: string, collectionId: string, sessionId: string): Promise<MemoryResponse>;
-    /**
-     * Legacy wrapper: search conversations optionally scoped by session
-     */
-    searchConversations(query: string, collectionId: string, sessionId?: string, includeAllSessions?: boolean): Promise<SearchResult[]>;
+    }): Promise<MemoryRecall>;
     healthCheck(): Promise<Record<string, any>>;
     private _collectionFromDict;
     private _memoryResponseFromDict;
@@ -457,4 +447,4 @@ declare class Nebula {
     private _formDataFromObject;
 }
 
-export { type AgentResponse, type Chunk, type Collection, type GraphCommunityResult, type GraphEntityResult, type GraphRelationshipResult, GraphSearchResultType, type Memory, type MemoryResponse, Nebula, NebulaAuthenticationException, type NebulaClientConfig, NebulaClientException, NebulaCollectionNotFoundException, NebulaException, NebulaNotFoundException, NebulaRateLimitException, NebulaValidationException, type SearchOptions, type SearchResult, type StructuredChunk, Nebula as default };
+export { type ActivatedEntity, type ActivatedFact, type AgentResponse, type Chunk, type Collection, type GraphCommunityResult, type GraphEntityResult, type GraphRelationshipResult, GraphSearchResultType, type GroundedUtterance, type Memory, type MemoryRecall, type MemoryResponse, Nebula, NebulaAuthenticationException, type NebulaClientConfig, NebulaClientException, NebulaCollectionNotFoundException, NebulaException, NebulaNotFoundException, NebulaRateLimitException, NebulaValidationException, type RecallFocus, type SearchOptions, type SearchResult, type StructuredChunk, Nebula as default };

package/dist/index.d.ts

@@ -100,6 +100,56 @@ interface SearchOptions {
     filters?: Record<string, any>;
     search_mode?: 'fast' | 'super';
 }
+interface RecallFocus {
+    schema_weight: number;
+    fact_weight: number;
+    episodic_weight: number;
+}
+interface ActivatedEntity {
+    entity_id: string;
+    entity_name: string;
+    entity_category?: string;
+    activation_score: number;
+    activation_reason?: string;
+    traversal_depth: number;
+    profile?: Record<string, any>;
+}
+interface ActivatedFact {
+    fact_id: string;
+    entity_id?: string;
+    entity_name?: string;
+    facet_name?: string;
+    subject: string;
+    predicate: string;
+    object_value: string;
+    activation_score: number;
+    extraction_confidence: number;
+    corroboration_count: number;
+    source_chunk_ids: string[];
+}
+interface GroundedUtterance {
+    chunk_id: string;
+    text: string;
+    activation_score: number;
+    speaker_name?: string;
+    source_role?: string;
+    timestamp?: string;
+    display_name?: string;
+    supporting_fact_ids: string[];
+    metadata?: Record<string, any>;
+}
+interface MemoryRecall {
+    query: string;
+    entities: ActivatedEntity[];
+    facts: ActivatedFact[];
+    utterances: GroundedUtterance[];
+    focus?: RecallFocus;
+    fact_to_chunks: Record<string, string[]>;
+    entity_to_facts: Record<string, string[]>;
+    retrieved_at: string;
+    total_traversal_time_ms?: number;
+    query_intent?: string;
+}
 interface NebulaClientConfig {
     apiKey: string;
     baseUrl?: string;
@@ -166,55 +216,6 @@ declare class Nebula {
         limit?: number;
         offset?: number;
     }): 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;
-        collection_ids?: string[];
-        metadata_filters?: Record<string, any>;
-    }): Promise<any[]>;
-    /**
-     * 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[]>>;
     /** Update a collection */
     updateCollection(options: {
         collectionId: string;
@@ -293,8 +294,6 @@ declare class Nebula {
         collectionIds?: string[];
         mergeMetadata?: boolean;
     }): Promise<boolean>;
-    /** Delete a conversation and all its messages */
-    deleteConversation(conversationId: string): Promise<boolean>;
     /**
      * Get all memories from specific collections with optional metadata filtering
      *
@@ -434,20 +433,11 @@ declare class Nebula {
      */
     search(options: {
         query: string;
-        collection_ids: string | string[];
+        collection_ids?: string | string[];
         limit?: number;
         filters?: Record<string, any>;
-        search_mode?: 'fast' | 'super';
         searchSettings?: Record<string, any>;
-    }): Promise<SearchResult[]>;
-    /**
-     * Legacy wrapper: store a two-message conversation turn as a document
-     */
-    storeConversation(userMessage: string, assistantMessage: string, collectionId: string, sessionId: string): Promise<MemoryResponse>;
-    /**
-     * Legacy wrapper: search conversations optionally scoped by session
-     */
-    searchConversations(query: string, collectionId: string, sessionId?: string, includeAllSessions?: boolean): Promise<SearchResult[]>;
+    }): Promise<MemoryRecall>;
     healthCheck(): Promise<Record<string, any>>;
     private _collectionFromDict;
     private _memoryResponseFromDict;
@@ -457,4 +447,4 @@ declare class Nebula {
     private _formDataFromObject;
 }
 
-export { type AgentResponse, type Chunk, type Collection, type GraphCommunityResult, type GraphEntityResult, type GraphRelationshipResult, GraphSearchResultType, type Memory, type MemoryResponse, Nebula, NebulaAuthenticationException, type NebulaClientConfig, NebulaClientException, NebulaCollectionNotFoundException, NebulaException, NebulaNotFoundException, NebulaRateLimitException, NebulaValidationException, type SearchOptions, type SearchResult, type StructuredChunk, Nebula as default };
+export { type ActivatedEntity, type ActivatedFact, type AgentResponse, type Chunk, type Collection, type GraphCommunityResult, type GraphEntityResult, type GraphRelationshipResult, GraphSearchResultType, type GroundedUtterance, type Memory, type MemoryRecall, type MemoryResponse, Nebula, NebulaAuthenticationException, type NebulaClientConfig, NebulaClientException, NebulaCollectionNotFoundException, NebulaException, NebulaNotFoundException, NebulaRateLimitException, NebulaValidationException, type RecallFocus, type SearchOptions, type SearchResult, type StructuredChunk, Nebula as default };

package/dist/index.js

@@ -208,110 +208,6 @@ var Nebula = class {
     }
     return collections.map((collection) => this._collectionFromDict(collection));
   }
-  // Conversations Methods
-  /**
-   * 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' }
-   *   }
-   * });
-   */
-  async listConversations(options) {
-    const params = {
-      limit: options?.limit ?? 100,
-      offset: options?.offset ?? 0
-    };
-    if (options?.collection_ids && options.collection_ids.length > 0) {
-      params.collection_ids = options.collection_ids;
-    }
-    if (options?.metadata_filters) {
-      params.metadata_filters = JSON.stringify(options.metadata_filters);
-    }
-    const response = await this._makeRequest("GET", "/v1/memories", void 0, params);
-    let conversations;
-    if (response && response.results) {
-      conversations = response.results;
-    } else if (Array.isArray(response)) {
-      conversations = response;
-    } else {
-      conversations = response ? [response] : [];
-    }
-    return conversations;
-  }
-  async getConversationMessages(conversationIdOrIds) {
-    if (typeof conversationIdOrIds === "string") {
-      const batchResults = await this.getConversationMessages([conversationIdOrIds]);
-      return batchResults[conversationIdOrIds] || [];
-    }
-    if (!Array.isArray(conversationIdOrIds) || conversationIdOrIds.length === 0) {
-      return {};
-    }
-    const params = { ids: conversationIdOrIds };
-    const response = await this._makeRequest("GET", "/v1/memories", void 0, params);
-    const results = {};
-    if (response && response.results && Array.isArray(response.results)) {
-      for (const doc of response.results) {
-        const conversationId = doc.id;
-        if (!conversationId) {
-          continue;
-        }
-        if (Array.isArray(doc.chunks) && doc.chunks.length > 0) {
-          const messages = [];
-          for (let i = 0; i < doc.chunks.length; i++) {
-            const structuredChunk = doc.chunks[i];
-            if (!structuredChunk || typeof structuredChunk.text !== "string" || structuredChunk.text.length === 0) {
-              continue;
-            }
-            const text = structuredChunk.text;
-            const role = structuredChunk.role ?? "user";
-            messages.push({
-              id: `${doc.id}-${i}`,
-              content: text,
-              metadata: {
-                ...doc.metadata,
-                // Copy engram metadata (playground, session_id, etc.)
-                role
-                // Add/override role for this specific message
-              },
-              created_at: doc.created_at,
-              collection_ids: doc.collection_ids || []
-            });
-          }
-          results[conversationId] = messages;
-        } else {
-          results[conversationId] = [];
-        }
-      }
-    }
-    for (const conversationId of conversationIdOrIds) {
-      if (!(conversationId in results)) {
-        results[conversationId] = [];
-      }
-    }
-    return results;
-  }
   /** Update a collection */
   async updateCollection(options) {
     const data = {};
@@ -674,18 +570,6 @@ var Nebula = class {
       throw error;
     }
   }
-  /** Delete a conversation and all its messages */
-  async deleteConversation(conversationId) {
-    try {
-      await this._makeRequest("DELETE", `/v1/memories/${conversationId}`);
-      return true;
-    } catch (error) {
-      if (error instanceof Error) {
-        throw error;
-      }
-      throw new NebulaClientException(`Unknown error: ${String(error)}`);
-    }
-  }
   /**
    * Get all memories from specific collections with optional metadata filtering
    *
@@ -855,65 +739,34 @@ var Nebula = class {
    * https://docs.nebulacloud.app/guides/metadata-filtering
    */
   async search(options) {
-    const collectionIds = Array.isArray(options.collection_ids) ? options.collection_ids : [options.collection_ids];
-    const validCollectionIds = collectionIds.filter((id) => id && id.trim() !== "");
-    if (!validCollectionIds.length) {
-      throw new NebulaClientException("collection_ids must be provided to search().");
-    }
-    const limit = options.limit ?? 10;
-    const searchMode = options.search_mode ?? "super";
-    const effectiveSettings = {
-      ...options.searchSettings
-    };
-    effectiveSettings.limit = limit;
-    const userFilters = { ...effectiveSettings.filters };
-    if (options.filters) {
-      Object.assign(userFilters, options.filters);
-    }
-    userFilters.collection_ids = { $overlap: validCollectionIds };
-    effectiveSettings.filters = userFilters;
     const data = {
       query: options.query,
-      search_mode: searchMode,
-      search_settings: effectiveSettings
+      limit: options.limit ?? 10
     };
-    const response = await this._makeRequest("POST", "/v1/retrieval/search", data);
-    let chunkResults = [];
-    let graphResults = [];
-    if (response.results) {
-      chunkResults = response.results.chunk_search_results || [];
-      graphResults = response.results.graph_search_results || [];
+    if (options.collection_ids) {
+      const collectionIds = Array.isArray(options.collection_ids) ? options.collection_ids : [options.collection_ids];
+      const validCollectionIds = collectionIds.filter((id) => id && id.trim() !== "");
+      if (validCollectionIds.length) {
+        data.collection_ids = validCollectionIds;
+      }
     }
-    const out = [];
-    out.push(...chunkResults.map((result) => this._searchResultFromDict(result)));
-    for (const g of graphResults) {
-      out.push(this._searchResultFromGraphDict(g));
+    if (options.filters) {
+      data.filters = options.filters;
     }
-    return out;
-  }
-  /**
-   * Legacy wrapper: store a two-message conversation turn as a document
-   */
-  async storeConversation(userMessage, assistantMessage, collectionId, sessionId) {
-    const content = `User: ${String(userMessage || "")}
-Assistant: ${String(assistantMessage || "")}`;
-    const metadata = { session_id: sessionId, content_type: "conversation" };
-    return this.store(content, collectionId, metadata);
-  }
-  /**
-   * Legacy wrapper: search conversations optionally scoped by session
-   */
-  async searchConversations(query, collectionId, sessionId, includeAllSessions = true) {
-    const filters = { "metadata.content_type": "conversation" };
-    if (sessionId && !includeAllSessions) {
-      filters["metadata.session_id"] = sessionId;
+    if (options.searchSettings) {
+      data.search_settings = options.searchSettings;
     }
-    return this.search({
-      query,
-      collection_ids: [collectionId],
-      limit: 10,
-      filters
-    });
+    const response = await this._makeRequest("POST", "/v1/retrieval/search", data);
+    const memoryRecall = response.results || {
+      query: options.query,
+      entities: [],
+      facts: [],
+      utterances: [],
+      fact_to_chunks: {},
+      entity_to_facts: {},
+      retrieved_at: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    return memoryRecall;
   }
   // Health Check
   async healthCheck() {