@soulcraft/brainy 0.16.0 → 0.18.0

package/dist/brainyData.d.ts

@@ -299,6 +299,22 @@ export declare class BrainyData<T = any> implements BrainyDataInterface<T> {
     /**
      * Add a verb between two nouns
      * If metadata is provided and vector is not, the metadata will be vectorized using the embedding function
+     *
+     * @param sourceId ID of the source noun
+     * @param targetId ID of the target noun
+     * @param vector Optional vector for the verb
+     * @param options Additional options:
+     *   - type: Type of the verb
+     *   - weight: Weight of the verb
+     *   - metadata: Metadata for the verb
+     *   - forceEmbed: Force using the embedding function for metadata even if vector is provided
+     *   - id: Optional ID to use instead of generating a new one
+     *   - autoCreateMissingNouns: Automatically create missing nouns if they don't exist
+     *   - missingNounMetadata: Metadata to use when auto-creating missing nouns
+     *
+     * @returns The ID of the added verb
+     *
+     * @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;
@@ -306,6 +322,8 @@ export declare class BrainyData<T = any> implements BrainyDataInterface<T> {
         metadata?: any;
         forceEmbed?: boolean;
         id?: string;
+        autoCreateMissingNouns?: boolean;
+        missingNounMetadata?: any;
     }): Promise<string>;
     /**
      * Get a verb by ID
@@ -339,6 +357,16 @@ export declare class BrainyData<T = any> implements BrainyDataInterface<T> {
      * Get the number of vectors in the database
      */
     size(): number;
+    /**
+     * Get statistics about the current state of the database
+     * @returns Object containing counts of nouns, verbs, metadata entries, and HNSW index size
+     */
+    getStatistics(): Promise<{
+        nounCount: number;
+        verbCount: number;
+        metadataCount: number;
+        hnswIndexSize: number;
+    }>;
     /**
      * Check if the database is in read-only mode
      * @returns True if the database is in read-only mode, false otherwise

package/dist/unified.js

@@ -10179,6 +10179,22 @@ class BrainyData {
     /**
      * Add a verb between two nouns
      * If metadata is provided and vector is not, the metadata will be vectorized using the embedding function
+     *
+     * @param sourceId ID of the source noun
+     * @param targetId ID of the target noun
+     * @param vector Optional vector for the verb
+     * @param options Additional options:
+     *   - type: Type of the verb
+     *   - weight: Weight of the verb
+     *   - metadata: Metadata for the verb
+     *   - forceEmbed: Force using the embedding function for metadata even if vector is provided
+     *   - id: Optional ID to use instead of generating a new one
+     *   - autoCreateMissingNouns: Automatically create missing nouns if they don't exist
+     *   - missingNounMetadata: Metadata to use when auto-creating missing nouns
+     *
+     * @returns The ID of the added verb
+     *
+     * @throws Error if source or target nouns don't exist and autoCreateMissingNouns is false or auto-creation fails
      */
     async addVerb(sourceId, targetId, vector, options = {}) {
         await this.ensureInitialized();
@@ -10186,8 +10202,51 @@ class BrainyData {
         this.checkReadOnly();
         try {
             // Check if source and target nouns exist
-            const sourceNoun = this.index.getNouns().get(sourceId);
-            const targetNoun = this.index.getNouns().get(targetId);
+            let sourceNoun = this.index.getNouns().get(sourceId);
+            let targetNoun = this.index.getNouns().get(targetId);
+            // Auto-create missing nouns if option is enabled
+            if (!sourceNoun && options.autoCreateMissingNouns) {
+                try {
+                    // Create a placeholder vector for the missing noun
+                    const placeholderVector = new Array(this._dimensions).fill(0);
+                    // Add metadata if provided
+                    const metadata = options.missingNounMetadata || {
+                        autoCreated: true,
+                        createdAt: new Date().toISOString(),
+                        noun: NounType.Concept
+                    };
+                    // Add the missing noun
+                    await this.add(placeholderVector, metadata, { id: sourceId });
+                    // Get the newly created noun
+                    sourceNoun = this.index.getNouns().get(sourceId);
+                    console.warn(`Auto-created missing source noun with ID ${sourceId}`);
+                }
+                catch (createError) {
+                    console.error(`Failed to auto-create source noun with ID ${sourceId}:`, createError);
+                    throw new Error(`Failed to auto-create source noun with ID ${sourceId}: ${createError}`);
+                }
+            }
+            if (!targetNoun && options.autoCreateMissingNouns) {
+                try {
+                    // Create a placeholder vector for the missing noun
+                    const placeholderVector = new Array(this._dimensions).fill(0);
+                    // Add metadata if provided
+                    const metadata = options.missingNounMetadata || {
+                        autoCreated: true,
+                        createdAt: new Date().toISOString(),
+                        noun: NounType.Concept
+                    };
+                    // Add the missing noun
+                    await this.add(placeholderVector, metadata, { id: targetId });
+                    // Get the newly created noun
+                    targetNoun = this.index.getNouns().get(targetId);
+                    console.warn(`Auto-created missing target noun with ID ${targetId}`);
+                }
+                catch (createError) {
+                    console.error(`Failed to auto-create target noun with ID ${targetId}:`, createError);
+                    throw new Error(`Failed to auto-create target noun with ID ${targetId}: ${createError}`);
+                }
+            }
             if (!sourceNoun) {
                 throw new Error(`Source noun with ID ${sourceId} not found`);
             }
@@ -10392,6 +10451,47 @@ class BrainyData {
     size() {
         return this.index.size();
     }
+    /**
+     * Get statistics about the current state of the database
+     * @returns Object containing counts of nouns, verbs, metadata entries, and HNSW index size
+     */
+    async getStatistics() {
+        await this.ensureInitialized();
+        try {
+            // Get noun count from the index
+            const nounCount = this.index.getNouns().size;
+            // Get verb count from storage
+            const allVerbs = await this.storage.getAllVerbs();
+            const verbCount = allVerbs.length;
+            // Count metadata entries by checking each noun for metadata
+            let metadataCount = 0;
+            const nouns = this.index.getNouns();
+            for (const [id] of nouns.entries()) {
+                try {
+                    const metadata = await this.storage.getMetadata(id);
+                    if (metadata !== null && metadata !== undefined) {
+                        metadataCount++;
+                    }
+                }
+                catch (error) {
+                    // Ignore errors when checking individual metadata entries
+                    // This could happen if metadata is corrupted or missing
+                }
+            }
+            // Get HNSW index size
+            const hnswIndexSize = this.index.size();
+            return {
+                nounCount,
+                verbCount,
+                metadataCount,
+                hnswIndexSize
+            };
+        }
+        catch (error) {
+            console.error('Failed to get statistics:', error);
+            throw new Error(`Failed to get statistics: ${error}`);
+        }
+    }
     /**
      * Check if the database is in read-only mode
      * @returns True if the database is in read-only mode, false otherwise