@soulcraft/brainy 0.63.0 → 1.0.0-rc.2

package/dist/brainyData.d.ts

@@ -7,7 +7,7 @@ import { HNSWIndexOptimized, HNSWOptimizedConfig } from './hnsw/hnswIndexOptimiz
 import { DistanceFunction, GraphVerb, EmbeddingFunction, HNSWConfig, SearchResult, SearchCursor, PaginatedSearchResult, StorageAdapter, Vector, VectorDocument } from './coreTypes.js';
 import { MetadataIndexManager, MetadataIndexConfig } from './utils/metadataIndex.js';
 import { NounType, VerbType } from './types/graphTypes.js';
-import { WebSocketConnection } from './types/augmentations.js';
+import { WebSocketConnection, IAugmentation } from './types/augmentations.js';
 import { BrainyDataInterface } from './types/brainyDataInterface.js';
 import { DistributedConfig } from './types/distributedTypes.js';
 import { SearchCacheConfig } from './utils/searchCache.js';
@@ -532,34 +532,31 @@ export declare class BrainyData<T = any> implements BrainyDataInterface<T> {
      */
     connectToRemoteServer(serverUrl: string, protocols?: string | string[]): Promise<WebSocketConnection>;
     /**
-     * Add data to the database (literal storage by default)
-     *
-     * 🔒 Safe by default: Only stores your data literally without AI processing
-     * 🧠 AI processing: Set { process: true } or use addSmart() for Neural Import
+     * Add data to the database with intelligent processing
      *
      * @param vectorOrData Vector or data to add
      * @param metadata Optional metadata to associate with the data
-     * @param options Additional options - use { process: true } for AI analysis
+     * @param options Additional options for processing
      * @returns The ID of the added data
      *
      * @example
-     * // Literal storage (safe, no AI processing)
-     * await brainy.add("API_KEY=secret123")
+     * // Auto mode - intelligently decides processing
+     * await brainy.add("Customer feedback: Great product!")
      *
      * @example
-     * // With AI processing (explicit opt-in)
-     * await brainy.add("John works at Acme Corp", null, { process: true })
+     * // Explicit literal mode for sensitive data
+     * await brainy.add("API_KEY=secret123", null, { process: 'literal' })
      *
      * @example
-     * // Smart processing (recommended for data analysis)
-     * await brainy.addSmart("Customer feedback: Great product!")
+     * // Force neural processing
+     * await brainy.add("John works at Acme Corp", null, { process: 'neural' })
      */
     add(vectorOrData: Vector | any, metadata?: T, options?: {
         forceEmbed?: boolean;
         addToRemote?: boolean;
         id?: string;
         service?: string;
-        process?: boolean;
+        process?: 'auto' | 'literal' | 'neural';
     }): Promise<string>;
     /**
      * Add a text item to the database with automatic embedding
@@ -782,6 +779,9 @@ export declare class BrainyData<T = any> implements BrainyDataInterface<T> {
      */
     delete(id: string, options?: {
         service?: string;
+        soft?: boolean;
+        cascade?: boolean;
+        force?: boolean;
     }): Promise<boolean>;
     /**
      * Update metadata for a vector
@@ -824,17 +824,7 @@ export declare class BrainyData<T = any> implements BrainyDataInterface<T> {
      *
      * @throws Error if source or target nouns don't exist and autoCreateMissingNouns is false or auto-creation fails
      */
-    addVerb(sourceId: string, targetId: string, vector?: Vector, options?: {
-        type?: string;
-        weight?: number;
-        metadata?: any;
-        forceEmbed?: boolean;
-        id?: string;
-        autoCreateMissingNouns?: boolean;
-        missingNounMetadata?: any;
-        service?: string;
-        writeOnlyMode?: boolean;
-    }): Promise<string>;
+    private _addVerbInternal;
     /**
      * Get a verb by ID
      * This is a direct storage operation that works in write-only mode when allowDirectReads is enabled
@@ -946,25 +936,10 @@ export declare class BrainyData<T = any> implements BrainyDataInterface<T> {
      */
     private adaptCacheConfiguration;
     /**
-     * Add data with AI processing enabled by default
-     *
-     * 🧠 This method automatically enables Neural Import and other AI augmentations
-     * for intelligent data understanding, entity detection, and relationship analysis.
-     *
-     * Use this when you want AI to understand and process your data.
-     * Use regular add() when you want literal storage only.
-     *
-     * @param vectorOrData The data to add (any format)
-     * @param metadata Optional metadata to associate with the data
-     * @param options Additional options (process defaults to true)
-     * @returns The ID of the added data
+     * @deprecated Use add() instead - it's smart by default now
+     * @hidden
      */
-    addSmart(vectorOrData: Vector | any, metadata?: T, options?: {
-        forceEmbed?: boolean;
-        addToRemote?: boolean;
-        id?: string;
-        service?: string;
-    }): Promise<string>;
+    addSmart(vectorOrData: Vector | any, metadata?: T, options?: any): Promise<string>;
     /**
      * Get the number of nouns in the database (excluding verbs)
      * This is used for statistics reporting to match the expected behavior in tests
@@ -1345,7 +1320,7 @@ export declare class BrainyData<T = any> implements BrainyDataInterface<T> {
      */
     loadEnvironment(): Promise<void>;
     /**
-     * Set a configuration value in Cortex
+     * Set a configuration value with optional encryption
      * @param key Configuration key
      * @param value Configuration value
      * @param options Options including encryption
@@ -1354,11 +1329,132 @@ export declare class BrainyData<T = any> implements BrainyDataInterface<T> {
         encrypt?: boolean;
     }): Promise<void>;
     /**
-     * Get a configuration value from Cortex
+     * Get a configuration value with automatic decryption
      * @param key Configuration key
      * @returns Configuration value or undefined
      */
     getConfig(key: string): Promise<any>;
+    /**
+     * Encrypt data using universal crypto utilities
+     */
+    encryptData(data: string): Promise<string>;
+    /**
+     * Decrypt data using universal crypto utilities
+     */
+    decryptData(encryptedData: string): Promise<string>;
+    /**
+     * Neural Import - Smart bulk data import with semantic type detection
+     * Uses transformer embeddings to automatically detect and classify data types
+     * @param data Array of data items or single item to import
+     * @param options Import options including type hints and processing mode
+     * @returns Array of created IDs
+     */
+    import(data: any[] | any, options?: {
+        typeHint?: NounType;
+        autoDetect?: boolean;
+        batchSize?: number;
+        process?: 'auto' | 'guided' | 'explicit' | 'literal';
+    }): Promise<string[]>;
+    /**
+     * Add Noun - Explicit noun creation with strongly-typed NounType
+     * For when you know exactly what type of noun you're creating
+     * @param data The noun data
+     * @param nounType The explicit noun type from NounType enum
+     * @param metadata Additional metadata
+     * @returns Created noun ID
+     */
+    addNoun(data: any, nounType: NounType, metadata?: any): Promise<string>;
+    /**
+     * Add Verb - Unified relationship creation between nouns
+     * Creates typed relationships with proper vector embeddings from metadata
+     * @param sourceId Source noun ID
+     * @param targetId Target noun ID
+     * @param verbType Relationship type from VerbType enum
+     * @param metadata Additional metadata for the relationship (will be embedded for searchability)
+     * @param weight Relationship weight/strength (0-1, default: 0.5)
+     * @returns Created verb ID
+     */
+    addVerb(sourceId: string, targetId: string, verbType: VerbType, metadata?: any, weight?: number): Promise<string>;
+    /**
+     * Auto-detect whether to use neural processing for data
+     * @private
+     */
+    private shouldAutoProcessNeurally;
+    /**
+     * Detect noun type using semantic analysis
+     * @private
+     */
+    private detectNounType;
+    /**
+     * Get Noun with Connected Verbs - Retrieve noun and all its relationships
+     * Provides complete traversal view of a noun and its connections using existing searchVerbs
+     * @param nounId The noun ID to retrieve
+     * @param options Traversal options
+     * @returns Noun data with connected verbs and related nouns
+     */
+    getNounWithVerbs(nounId: string, options?: {
+        includeIncoming?: boolean;
+        includeOutgoing?: boolean;
+        verbLimit?: number;
+        verbTypes?: string[];
+    }): Promise<{
+        noun: {
+            id: string;
+            data: any;
+            metadata: any;
+            nounType?: NounType;
+        };
+        incomingVerbs: any[];
+        outgoingVerbs: any[];
+        totalConnections: number;
+    } | null>;
+    /**
+     * Update - Smart noun update with automatic index synchronization
+     * Updates both data and metadata while maintaining search index integrity
+     * @param id The noun ID to update
+     * @param data New data (optional - if not provided, only metadata is updated)
+     * @param metadata New metadata (merged with existing)
+     * @param options Update options
+     * @returns Success boolean
+     */
+    update(id: string, data?: any, metadata?: any, options?: {
+        merge?: boolean;
+        reindex?: boolean;
+        cascade?: boolean;
+    }): Promise<boolean>;
+    /**
+     * Preload Transformer Model - Essential for container deployments
+     * Downloads and caches models during initialization to avoid runtime delays
+     * @param options Preload options
+     * @returns Success boolean and model info
+     */
+    static preloadModel(options?: {
+        model?: string;
+        cacheDir?: string;
+        device?: string;
+        force?: boolean;
+    }): Promise<{
+        success: boolean;
+        modelPath: string;
+        modelSize: number;
+        device: string;
+    }>;
+    /**
+     * Warmup - Initialize BrainyData with preloaded models (container-optimized)
+     * For production deployments where models should be ready immediately
+     * @param config BrainyData configuration
+     * @param options Warmup options
+     */
+    static warmup(config?: BrainyDataConfig, options?: {
+        preloadModel?: boolean;
+        modelOptions?: Parameters<typeof BrainyData.preloadModel>[0];
+        testEmbedding?: boolean;
+    }): Promise<BrainyData>;
+    /**
+     * Get model size for deployment info
+     * @private
+     */
+    private static getModelSize;
     /**
      * Coordinate storage migration across distributed services
      * @param options Migration options
@@ -1378,6 +1474,51 @@ export declare class BrainyData<T = any> implements BrainyDataInterface<T> {
      * Exposed for Cortex reindex command
      */
     rebuildMetadataIndex(): Promise<void>;
+    /**
+     * UNIFIED API METHOD #8: Augment - Complete augmentation management
+     * Register, enable, disable, list, and manage augmentations
+     *
+     * @param action The action to perform or augmentation to register
+     * @param options Additional options for the action
+     * @returns Various return types based on action
+     */
+    augment(action: IAugmentation | 'list' | 'enable' | 'disable' | 'unregister' | 'enable-type' | 'disable-type', options?: string | {
+        name?: string;
+        type?: string;
+    }): this | any;
+    /**
+     * UNIFIED API METHOD #9: Export - Extract your data in various formats
+     * Export your brain's knowledge for backup, migration, or integration
+     *
+     * @param options Export configuration
+     * @returns The exported data in the specified format
+     */
+    export(options?: {
+        format?: 'json' | 'csv' | 'graph' | 'embeddings';
+        includeVectors?: boolean;
+        includeMetadata?: boolean;
+        includeRelationships?: boolean;
+        filter?: any;
+        limit?: number;
+    }): Promise<any>;
+    /**
+     * Helper: Convert data to CSV format
+     * @private
+     */
+    private convertToCSV;
+    /**
+     * Helper: Convert data to graph format
+     * @private
+     */
+    private convertToGraphFormat;
+    /**
+     * Unregister an augmentation by name
+     * Remove augmentations from the pipeline
+     *
+     * @param name The name of the augmentation to unregister
+     * @returns The BrainyData instance for chaining
+     */
+    unregister(name: string): this;
     /**
      * Enable an augmentation by name
      * Universal control for built-in, community, and premium augmentations