@cmdoss/memwal-sdk 0.6.0

package/dist/client/namespaces/SearchNamespace.d.ts

@@ -0,0 +1,382 @@
+/**
+ * Search Namespace - All Search Methods
+ *
+ * Provides comprehensive search capabilities:
+ * - Vector similarity search
+ * - Semantic search (AI-enhanced)
+ * - Keyword search (metadata)
+ * - Hybrid search (combined)
+ * - Temporal search (date-based)
+ * - Category filtering
+ *
+ * @module client/namespaces
+ */
+import type { ServiceContainer } from '../SimplePDWClient';
+/**
+ * Search result item
+ *
+ * NOTE: `content` is empty by default for privacy. Content is stored encrypted
+ * on Walrus and not in the index. Use `pdw.search.withContent()` or
+ * `pdw.memory.get(blobId)` to retrieve decrypted content.
+ */
+export interface SearchResult {
+    id: string;
+    /** Empty by default - use withContent() to fetch from Walrus */
+    content: string;
+    score: number;
+    similarity: number;
+    category?: string;
+    importance?: number;
+    topic?: string;
+    /** Use this to fetch content: pdw.memory.get(blobId) */
+    blobId: string;
+    metadata?: Record<string, any>;
+    timestamp: number;
+}
+/**
+ * Vector search options
+ */
+export interface VectorSearchOptions {
+    limit?: number;
+    threshold?: number;
+    category?: string;
+    includeEmbeddings?: boolean;
+    /**
+     * Fetch content from Walrus for each result (slower but includes content)
+     * @default false
+     */
+    fetchContent?: boolean;
+}
+/**
+ * Semantic search options
+ */
+export interface SemanticSearchOptions extends VectorSearchOptions {
+    rerank?: boolean;
+}
+/**
+ * Keyword search options
+ */
+export interface KeywordSearchOptions {
+    limit?: number;
+    category?: string;
+    fields?: string[];
+    caseSensitive?: boolean;
+}
+/**
+ * Hybrid search options
+ */
+export interface HybridSearchOptions {
+    limit?: number;
+    vectorWeight?: number;
+    keywordWeight?: number;
+    category?: string;
+}
+/**
+ * Date range for temporal search
+ */
+export interface DateRange {
+    start: Date | string;
+    end?: Date | string;
+}
+/**
+ * Search Namespace
+ *
+ * Handles all types of search operations
+ */
+export declare class SearchNamespace {
+    private services;
+    constructor(services: ServiceContainer);
+    /**
+     * Vector similarity search
+     *
+     * Searches memories by semantic similarity using embeddings.
+     *
+     * NOTE: Content is NOT included by default for privacy (content is encrypted on Walrus).
+     * Use `fetchContent: true` option or call `pdw.memory.get(blobId)` to get content.
+     *
+     * @param query - Text query to search for
+     * @param options - Search options
+     * @returns Sorted array of results by similarity (content empty unless fetchContent=true)
+     *
+     * @example
+     * ```typescript
+     * // Fast search (no content)
+     * const results = await pdw.search.vector('programming');
+     *
+     * // Search with content (slower - fetches from Walrus)
+     * const results = await pdw.search.vector('programming', { fetchContent: true });
+     *
+     * // Or fetch content for specific result
+     * const memory = await pdw.memory.get(results[0].blobId);
+     * ```
+     */
+    vector(query: string, options?: VectorSearchOptions): Promise<SearchResult[]>;
+    /**
+     * Semantic search (AI-enhanced)
+     *
+     * Uses AI to understand query intent and rerank results
+     *
+     * @param query - Natural language query
+     * @param options - Search options
+     * @returns Semantically relevant results
+     */
+    semantic(query: string, options?: SemanticSearchOptions): Promise<SearchResult[]>;
+    /**
+     * Keyword search (metadata-based)
+     *
+     * Searches in metadata fields using keywords
+     *
+     * @param query - Keyword to search for
+     * @param options - Search options
+     * @returns Matching memories
+     */
+    keyword(query: string, options?: KeywordSearchOptions): Promise<SearchResult[]>;
+    /**
+     * Hybrid search (vector + keyword)
+     *
+     * Combines vector similarity and keyword matching
+     *
+     * @param query - Search query
+     * @param options - Hybrid search options
+     * @returns Ranked results from both methods
+     */
+    hybrid(query: string, options?: HybridSearchOptions): Promise<SearchResult[]>;
+    /**
+     * Search by category
+     *
+     * First tries local vector index (for recently created memories),
+     * then queries blockchain for on-chain Memory objects.
+     * Combines results and deduplicates by blobId.
+     *
+     * @param category - Category to filter by
+     * @param options - Additional options
+     * @returns Memories in category
+     */
+    byCategory(category: string, options?: VectorSearchOptions): Promise<SearchResult[]>;
+    /**
+     * Search by date range
+     *
+     * @param dateRange - Start and end dates
+     * @param options - Additional options
+     * @returns Memories within date range
+     */
+    byDate(dateRange: DateRange, options?: VectorSearchOptions): Promise<SearchResult[]>;
+    /**
+     * Search by importance range
+     *
+     * @param min - Minimum importance (1-10)
+     * @param max - Maximum importance (1-10)
+     * @param options - Additional options
+     * @returns Memories within importance range
+     */
+    byImportance(min: number, max?: number, options?: VectorSearchOptions): Promise<SearchResult[]>;
+    /**
+     * Advanced search with complex filters
+     *
+     * @param query - Search query or filters
+     * @returns Filtered and ranked results
+     */
+    advanced(query: {
+        text?: string;
+        category?: string;
+        importance?: {
+            min: number;
+            max: number;
+        };
+        dateRange?: DateRange;
+        limit?: number;
+    }): Promise<SearchResult[]>;
+    /**
+     * Graph-based search
+     *
+     * Search using knowledge graph relationships
+     *
+     * @param query - Entity or concept to search
+     * @param options - Search options
+     * @returns Related memories via graph connections
+     */
+    graph(query: string, options?: VectorSearchOptions): Promise<SearchResult[]>;
+    /**
+     * Search with embedding vectors included
+     *
+     * Same as vector search but includes embedding vectors in results
+     *
+     * @param query - Search query
+     * @param options - Search options
+     * @returns Results with embedding vectors
+     */
+    withEmbeddings(query: string, options?: VectorSearchOptions): Promise<SearchResult[]>;
+    /**
+     * Multi-vector search
+     *
+     * Search using multiple query vectors/texts
+     *
+     * @param queries - Array of query texts
+     * @param options - Search options
+     * @returns Combined and deduplicated results
+     */
+    multiVector(queries: string[], options?: VectorSearchOptions): Promise<SearchResult[]>;
+    /**
+     * Rerank search results using AI
+     *
+     * Takes existing results and reranks them using AI for better relevance
+     *
+     * @param results - Initial search results
+     * @param query - Original query for context
+     * @param options - Rerank options
+     * @returns Reranked results
+     */
+    rerank(results: SearchResult[], query: string, options?: {
+        limit?: number;
+    }): Promise<SearchResult[]>;
+    /**
+     * Populate content for search results by fetching from Walrus
+     *
+     * Fetches and decrypts content for each result in parallel.
+     * Modifies results in-place.
+     *
+     * @param results - Search results to populate
+     */
+    private populateContent;
+    /**
+     * Search and fetch content in one call
+     *
+     * Convenience method that combines vector search with content fetching.
+     *
+     * @param query - Search query
+     * @param options - Search options
+     * @returns Results with content populated
+     *
+     * @example
+     * ```typescript
+     * const results = await pdw.search.withContent('programming');
+     * console.log(results[0].content); // "I love TypeScript..."
+     * ```
+     */
+    withContent(query: string, options?: VectorSearchOptions): Promise<SearchResult[]>;
+    /**
+     * Get all entities from knowledge graph
+     *
+     * @param options - Filter options
+     * @returns Array of entities
+     *
+     * @example
+     * ```typescript
+     * const entities = await pdw.search.entities({ type: 'PERSON' });
+     * ```
+     */
+    entities(options?: {
+        type?: string;
+        minConfidence?: number;
+        limit?: number;
+    }): Promise<Array<{
+        id: string;
+        name: string;
+        type: string;
+        confidence: number;
+    }>>;
+    /**
+     * Get all relationships from knowledge graph
+     *
+     * @param options - Filter options
+     * @returns Array of relationships
+     *
+     * @example
+     * ```typescript
+     * const rels = await pdw.search.relationships({ type: 'WORKS_AT' });
+     * ```
+     */
+    relationships(options?: {
+        type?: string;
+        sourceId?: string;
+        targetId?: string;
+        minConfidence?: number;
+        limit?: number;
+    }): Promise<Array<{
+        id: string;
+        source: string;
+        target: string;
+        type: string;
+        confidence: number;
+    }>>;
+    /**
+     * Index management operations
+     *
+     * Access via pdw.search.index.*
+     */
+    get index(): IndexSubNamespace;
+    private _indexSubNamespace?;
+}
+/**
+ * Index sub-namespace for HNSW index management
+ */
+declare class IndexSubNamespace {
+    private services;
+    constructor(services: ServiceContainer);
+    /**
+     * Get the underlying index service
+     */
+    private getService;
+    /**
+     * Save index to Walrus storage
+     *
+     * Persists the HNSW index binary to Walrus for durability.
+     *
+     * @param spaceId - Index space identifier (userAddress)
+     * @returns Blob ID of saved index on Walrus, or null if no index exists
+     *
+     * @example
+     * ```typescript
+     * const blobId = await pdw.search.index.save(userAddress);
+     * console.log('Index saved to Walrus:', blobId);
+     * ```
+     */
+    save(spaceId: string): Promise<void>;
+    /**
+     * Load index from Walrus storage
+     *
+     * Loads a previously saved HNSW index from Walrus.
+     *
+     * @param spaceId - Index space identifier (userAddress)
+     * @param blobId - Blob ID of the saved index on Walrus
+     *
+     * @example
+     * ```typescript
+     * await pdw.search.index.load(userAddress, 'blobId123');
+     * ```
+     */
+    load(spaceId: string, blobId: string): Promise<void>;
+    /**
+     * Get index statistics
+     *
+     * @param spaceId - Index space identifier
+     * @returns Index statistics
+     *
+     * @example
+     * ```typescript
+     * const stats = pdw.search.index.stats(userAddress);
+     * console.log('Total vectors:', stats.totalVectors);
+     * ```
+     */
+    stats(spaceId: string): {
+        totalVectors: number;
+        dimension: number;
+        spaceType: string;
+        maxElements: number;
+        currentCount: number;
+    };
+    /**
+     * Clear index and remove all vectors
+     *
+     * @param spaceId - Index space identifier
+     */
+    clear(spaceId: string): void;
+    /**
+     * Force flush pending vectors
+     *
+     * @param spaceId - Index space identifier
+     */
+    flush(spaceId: string): Promise<void>;
+}
+export {};
+//# sourceMappingURL=SearchNamespace.d.ts.map

package/dist/client/namespaces/SearchNamespace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SearchNamespace.d.ts","sourceRoot":"","sources":["../../../src/client/namespaces/SearchNamespace.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE3D;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,gEAAgE;IAChE,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wDAAwD;IACxD,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC/B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAsB,SAAQ,mBAAmB;IAChE,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,IAAI,GAAG,MAAM,CAAC;IACrB,GAAG,CAAC,EAAE,IAAI,GAAG,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,qBAAa,eAAe;IACd,OAAO,CAAC,QAAQ;gBAAR,QAAQ,EAAE,gBAAgB;IAE9C;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IA4DvF;;;;;;;;OAQG;IACG,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,qBAA0B,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAoC3F;;;;;;;;OAQG;IACG,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,oBAAyB,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IA6BzF;;;;;;;;OAQG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAkCvF;;;;;;;;;;OAUG;IACG,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IA+E9F;;;;;;OAMG;IACG,MAAM,CAAC,SAAS,EAAE,SAAS,EAAE,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAmC9F;;;;;;;OAOG;IACG,YAAY,CAChB,GAAG,EAAE,MAAM,EACX,GAAG,GAAE,MAAW,EAChB,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,YAAY,EAAE,CAAC;IAyB1B;;;;;OAKG;IACG,QAAQ,CAAC,KAAK,EAAE;QACpB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,UAAU,CAAC,EAAE;YAAE,GAAG,EAAE,MAAM,CAAC;YAAC,GAAG,EAAE,MAAM,CAAA;SAAE,CAAC;QAC1C,SAAS,CAAC,EAAE,SAAS,CAAC;QACtB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IA6D3B;;;;;;;;OAQG;IACG,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAiCtF;;;;;;;;OAQG;IACG,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAO/F;;;;;;;;OAQG;IACG,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IA6BhG;;;;;;;;;OASG;IACG,MAAM,CACV,OAAO,EAAE,YAAY,EAAE,EACvB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAO,GAC/B,OAAO,CAAC,YAAY,EAAE,CAAC;IAwC1B;;;;;;;OAOG;YACW,eAAe;IAiC7B;;;;;;;;;;;;;;OAcG;IACG,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAQ5F;;;;;;;;;;OAUG;IACG,QAAQ,CAAC,OAAO,GAAE;QACtB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,KAAK,CAAC,EAAE,MAAM,CAAC;KACX,GAAG,OAAO,CAAC,KAAK,CAAC;QACrB,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC,CAAC;IA4BH;;;;;;;;;;OAUG;IACG,aAAa,CAAC,OAAO,GAAE;QAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,KAAK,CAAC,EAAE,MAAM,CAAC;KACX,GAAG,OAAO,CAAC,KAAK,CAAC;QACrB,EAAE,EAAE,MAAM,CAAC;QACX,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,EAAE,MAAM,CAAC;QACb,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC,CAAC;IA8CH;;;;OAIG;IACH,IAAI,KAAK,IAAI,iBAAiB,CAK7B;IAED,OAAO,CAAC,kBAAkB,CAAC,CAAoB;CAChD;AAED;;GAEG;AACH,cAAM,iBAAiB;IACT,OAAO,CAAC,QAAQ;gBAAR,QAAQ,EAAE,gBAAgB;IAE9C;;OAEG;IACH,OAAO,CAAC,UAAU;IAUlB;;;;;;;;;;;;;OAaG;IACG,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAW1C;;;;;;;;;;;;OAYG;IACG,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAW1D;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG;QACtB,YAAY,EAAE,MAAM,CAAC;QACrB,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC;QAClB,WAAW,EAAE,MAAM,CAAC;QACpB,YAAY,EAAE,MAAM,CAAC;KACtB;IA4BD;;;;OAIG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAU5B;;;;OAIG;IACG,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAO5C"}