feat(core): enhance addVerb functionality with auto-creation of missing nouns

- Added `autoCreateMissingNouns` and `missingNounMetadata` options to the `addVerb` method in `brainyData.ts`, enabling automatic creation of missing source or target nouns.
- Improved error handling and logging for auto-creation failures, ensuring better feedback during runtime.
- Reformatted existing code for storage options validation to improve readability and maintain consistency.

**Purpose**: Simplify the addition of relationships by automating the process for non-existing nouns and enhance developer experience with better error handling and logging.

README.md

@@ -62,7 +62,8 @@ GitHub Pages that showcases Brainy's main features.
 npm install @soulcraft/brainy
 ```
 
-TensorFlow.js packages are included as bundled dependencies and will be automatically installed without any additional configuration.
+TensorFlow.js packages are included as bundled dependencies and will be automatically installed without any additional
+configuration.
 
 ## 🏁 Quick Start
 
@@ -107,7 +108,9 @@ import { BrainyData } from '@soulcraft/brainy'
 import {BrainyData} from '@soulcraft/brainy/min'
 ```
 
-> **Note**: The CLI functionality is available as a separate package `@soulcraft/brainy-cli` to reduce the bundle size of the main package. Install it globally with `npm install -g @soulcraft/brainy-cli` to use the command-line interface.
+> **Note**: The CLI functionality is available as a separate package `@soulcraft/brainy-cli` to reduce the bundle size
+> of the main package. Install it globally with `npm install -g @soulcraft/brainy-cli` to use the command-line
+> interface.
 
 ### Browser Usage
 
@@ -408,7 +411,8 @@ brainy visualize --root <id> --depth 3
 
 ### Using the CLI in Your Code
 
-The CLI functionality is available as a separate package `@soulcraft/brainy-cli`. If you need CLI functionality in your application, install the CLI package:
+The CLI functionality is available as a separate package `@soulcraft/brainy-cli`. If you need CLI functionality in your
+application, install the CLI package:
 
 ```bash
 npm install @soulcraft/brainy-cli
@@ -524,6 +528,19 @@ await db.addVerb(sourceId, targetId, {
     // other metadata...
 })
 
+// Add a relationship with auto-creation of missing nouns
+// This is useful when the target noun might not exist yet
+await db.addVerb(sourceId, targetId, {
+    verb: VerbType.RelatedTo,
+    // Enable auto-creation of missing nouns
+    autoCreateMissingNouns: true,
+    // Optional metadata for auto-created nouns
+    missingNounMetadata: {
+        noun: NounType.Concept,
+        description: 'Auto-created noun'
+    }
+})
+
 // Get all relationships
 const verbs = await db.getAllVerbs()
 
@@ -909,7 +926,8 @@ The simplified augmentation system provides:
 
 #### WebSocket Augmentation Types
 
-Brainy exports several WebSocket augmentation types that can be used by augmentation creators to add WebSocket capabilities to their augmentations:
+Brainy exports several WebSocket augmentation types that can be used by augmentation creators to add WebSocket
+capabilities to their augmentations:
 
 ```typescript
 import {
@@ -970,7 +988,8 @@ await mySenseAug.processRawData('data', 'text')
 await mySenseAug.connectWebSocket('wss://example.com')
 ```
 
-These WebSocket augmentation types combine the base augmentation interfaces with the `IWebSocketSupport` interface, providing type safety and autocompletion for augmentations with WebSocket capabilities.
+These WebSocket augmentation types combine the base augmentation interfaces with the `IWebSocketSupport` interface,
+providing type safety and autocompletion for augmentations with WebSocket capabilities.
 
 ### Model Control Protocol (MCP)
 
@@ -1034,7 +1053,6 @@ Works in all modern browsers:
 
 For browsers without OPFS support, falls back to in-memory storage.
 
-
 ## Related Projects
 
 - **[Cartographer](https://github.com/sodal-project/cartographer)** - A companion project that provides standardized

src/brainyData.ts

@@ -1253,6 +1253,22 @@ export 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
      */
     public async addVerb(
         sourceId: string,
@@ -1264,6 +1280,8 @@ export class BrainyData<T = any> implements BrainyDataInterface<T> {
             metadata?: any
             forceEmbed?: boolean // Force using the embedding function for metadata even if vector is provided
             id?: string // Optional ID to use instead of generating a new one
+            autoCreateMissingNouns?: boolean // Automatically create missing nouns
+            missingNounMetadata?: any // Metadata to use when auto-creating missing nouns
         } = {}
     ): Promise<string> {
         await this.ensureInitialized()
@@ -1273,8 +1291,59 @@ export class BrainyData<T = any> implements BrainyDataInterface<T> {
 
         try {
             // Check if source and target nouns exist
-            const sourceNoun = this.index.getNouns().get(sourceId)
+            let sourceNoun = this.index.getNouns().get(sourceId)
-            const targetNoun = this.index.getNouns().get(targetId)
+            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`)