@soulcraft/brainy 2.10.0 → 2.11.0

package/dist/storage/adapters/fileSystemStorage.d.ts

@@ -105,7 +105,7 @@ export declare class FileSystemStorage extends BaseStorage {
     /**
      * Save noun metadata to storage
      */
-    saveNounMetadata(id: string, metadata: any): Promise<void>;
+    protected saveNounMetadata_internal(id: string, metadata: any): Promise<void>;
     /**
      * Get noun metadata from storage
      */
@@ -113,7 +113,7 @@ export declare class FileSystemStorage extends BaseStorage {
     /**
      * Save verb metadata to storage
      */
-    saveVerbMetadata(id: string, metadata: any): Promise<void>;
+    protected saveVerbMetadata_internal(id: string, metadata: any): Promise<void>;
     /**
      * Get verb metadata from storage
      */

package/dist/storage/adapters/fileSystemStorage.js

@@ -433,7 +433,7 @@ export class FileSystemStorage extends BaseStorage {
     /**
      * Save noun metadata to storage
      */
-    async saveNounMetadata(id, metadata) {
+    async saveNounMetadata_internal(id, metadata) {
         await this.ensureInitialized();
         const filePath = path.join(this.nounMetadataDir, `${id}.json`);
         await fs.promises.writeFile(filePath, JSON.stringify(metadata, null, 2));
@@ -458,7 +458,7 @@ export class FileSystemStorage extends BaseStorage {
     /**
      * Save verb metadata to storage
      */
-    async saveVerbMetadata(id, metadata) {
+    async saveVerbMetadata_internal(id, metadata) {
         await this.ensureInitialized();
         const filePath = path.join(this.verbMetadataDir, `${id}.json`);
         await fs.promises.writeFile(filePath, JSON.stringify(metadata, null, 2));

package/dist/storage/adapters/memoryStorage.d.ts

@@ -131,17 +131,17 @@ export declare class MemoryStorage extends BaseStorage {
      */
     getMetadataBatch(ids: string[]): Promise<Map<string, any>>;
     /**
-     * Save noun metadata to storage
+     * Save noun metadata to storage (internal implementation)
      */
-    saveNounMetadata(id: string, metadata: any): Promise<void>;
+    protected saveNounMetadata_internal(id: string, metadata: any): Promise<void>;
     /**
      * Get noun metadata from storage
      */
     getNounMetadata(id: string): Promise<any | null>;
     /**
-     * Save verb metadata to storage
+     * Save verb metadata to storage (internal implementation)
      */
-    saveVerbMetadata(id: string, metadata: any): Promise<void>;
+    protected saveVerbMetadata_internal(id: string, metadata: any): Promise<void>;
     /**
      * Get verb metadata from storage
      */

package/dist/storage/adapters/memoryStorage.js

@@ -424,9 +424,9 @@ export class MemoryStorage extends BaseStorage {
         return results;
     }
     /**
-     * Save noun metadata to storage
+     * Save noun metadata to storage (internal implementation)
      */
-    async saveNounMetadata(id, metadata) {
+    async saveNounMetadata_internal(id, metadata) {
         this.nounMetadata.set(id, JSON.parse(JSON.stringify(metadata)));
     }
     /**
@@ -440,9 +440,9 @@ export class MemoryStorage extends BaseStorage {
         return JSON.parse(JSON.stringify(metadata));
     }
     /**
-     * Save verb metadata to storage
+     * Save verb metadata to storage (internal implementation)
      */
-    async saveVerbMetadata(id, metadata) {
+    async saveVerbMetadata_internal(id, metadata) {
         this.verbMetadata.set(id, JSON.parse(JSON.stringify(metadata)));
     }
     /**

package/dist/storage/adapters/opfsStorage.d.ts

@@ -144,7 +144,7 @@ export declare class OPFSStorage extends BaseStorage {
     /**
      * Save verb metadata to storage
      */
-    saveVerbMetadata(id: string, metadata: any): Promise<void>;
+    protected saveVerbMetadata_internal(id: string, metadata: any): Promise<void>;
     /**
      * Get verb metadata from storage
      */
@@ -152,7 +152,7 @@ export declare class OPFSStorage extends BaseStorage {
     /**
      * Save noun metadata to storage
      */
-    saveNounMetadata(id: string, metadata: any): Promise<void>;
+    protected saveNounMetadata_internal(id: string, metadata: any): Promise<void>;
     /**
      * Get noun metadata from storage
      */

package/dist/storage/adapters/opfsStorage.js

@@ -540,7 +540,7 @@ export class OPFSStorage extends BaseStorage {
     /**
      * Save verb metadata to storage
      */
-    async saveVerbMetadata(id, metadata) {
+    async saveVerbMetadata_internal(id, metadata) {
         await this.ensureInitialized();
         const fileName = `${id}.json`;
         const fileHandle = await this.verbMetadataDir.getFileHandle(fileName, { create: true });
@@ -570,7 +570,7 @@ export class OPFSStorage extends BaseStorage {
     /**
      * Save noun metadata to storage
      */
-    async saveNounMetadata(id, metadata) {
+    async saveNounMetadata_internal(id, metadata) {
         await this.ensureInitialized();
         const fileName = `${id}.json`;
         const fileHandle = await this.nounMetadataDir.getFileHandle(fileName, { create: true });

package/dist/storage/adapters/s3CompatibleStorage.d.ts

@@ -328,7 +328,7 @@ export declare class S3CompatibleStorage extends BaseStorage {
     /**
      * Save verb metadata to storage
      */
-    saveVerbMetadata(id: string, metadata: any): Promise<void>;
+    protected saveVerbMetadata_internal(id: string, metadata: any): Promise<void>;
     /**
      * Get verb metadata from storage
      */
@@ -336,7 +336,7 @@ export declare class S3CompatibleStorage extends BaseStorage {
     /**
      * Save noun metadata to storage
      */
-    saveNounMetadata(id: string, metadata: any): Promise<void>;
+    protected saveNounMetadata_internal(id: string, metadata: any): Promise<void>;
     /**
      * Get multiple metadata objects in batches (CRITICAL: Prevents socket exhaustion)
      * This is the solution to the metadata reading socket exhaustion during initialization

package/dist/storage/adapters/s3CompatibleStorage.js

@@ -1450,7 +1450,7 @@ export class S3CompatibleStorage extends BaseStorage {
     /**
      * Save verb metadata to storage
      */
-    async saveVerbMetadata(id, metadata) {
+    async saveVerbMetadata_internal(id, metadata) {
         await this.ensureInitialized();
         try {
             // Import the PutObjectCommand only when needed
@@ -1523,7 +1523,7 @@ export class S3CompatibleStorage extends BaseStorage {
     /**
      * Save noun metadata to storage
      */
-    async saveNounMetadata(id, metadata) {
+    async saveNounMetadata_internal(id, metadata) {
         await this.ensureInitialized();
         try {
             // Import the PutObjectCommand only when needed

package/dist/storage/baseStorage.d.ts

@@ -172,7 +172,12 @@ export declare abstract class BaseStorage extends BaseStorageAdapter {
      * Save noun metadata to storage
      * This method should be implemented by each specific adapter
      */
-    abstract saveNounMetadata(id: string, metadata: any): Promise<void>;
+    saveNounMetadata(id: string, metadata: any): Promise<void>;
+    /**
+     * Internal method for saving noun metadata
+     * This method should be implemented by each specific adapter
+     */
+    protected abstract saveNounMetadata_internal(id: string, metadata: any): Promise<void>;
     /**
      * Get noun metadata from storage
      * This method should be implemented by each specific adapter
@@ -182,7 +187,12 @@ export declare abstract class BaseStorage extends BaseStorageAdapter {
      * Save verb metadata to storage
      * This method should be implemented by each specific adapter
      */
-    abstract saveVerbMetadata(id: string, metadata: any): Promise<void>;
+    saveVerbMetadata(id: string, metadata: any): Promise<void>;
+    /**
+     * Internal method for saving verb metadata
+     * This method should be implemented by each specific adapter
+     */
+    protected abstract saveVerbMetadata_internal(id: string, metadata: any): Promise<void>;
     /**
      * Get verb metadata from storage
      * This method should be implemented by each specific adapter

package/dist/storage/baseStorage.js

@@ -3,6 +3,7 @@
  * Provides common functionality for all storage adapters
  */
 import { BaseStorageAdapter } from './adapters/baseStorageAdapter.js';
+import { validateNounType, validateVerbType } from '../utils/typeValidation.js';
 // Common directory/prefix names
 // Option A: Entity-Based Directory Structure
 export const ENTITIES_DIR = 'entities';
@@ -71,6 +72,11 @@ export class BaseStorage extends BaseStorageAdapter {
      */
     async saveNoun(noun) {
         await this.ensureInitialized();
+        // Validate noun type before saving - storage boundary protection
+        const metadata = await this.getNounMetadata(noun.id);
+        if (metadata?.noun) {
+            validateNounType(metadata.noun);
+        }
         return this.saveNoun_internal(noun);
     }
     /**
@@ -101,6 +107,10 @@ export class BaseStorage extends BaseStorageAdapter {
      */
     async saveVerb(verb) {
         await this.ensureInitialized();
+        // Validate verb type before saving - storage boundary protection
+        if (verb.verb) {
+            validateVerbType(verb.verb);
+        }
         // Extract the lightweight HNSWVerb data
         const hnswVerb = {
             id: verb.id,
@@ -488,6 +498,28 @@ export class BaseStorage extends BaseStorageAdapter {
         await this.ensureInitialized();
         return this.deleteVerb_internal(id);
     }
+    /**
+     * Save noun metadata to storage
+     * This method should be implemented by each specific adapter
+     */
+    async saveNounMetadata(id, metadata) {
+        // Validate noun type in metadata - storage boundary protection
+        if (metadata?.noun) {
+            validateNounType(metadata.noun);
+        }
+        return this.saveNounMetadata_internal(id, metadata);
+    }
+    /**
+     * Save verb metadata to storage
+     * This method should be implemented by each specific adapter
+     */
+    async saveVerbMetadata(id, metadata) {
+        // Validate verb type in metadata - storage boundary protection
+        if (metadata?.verb) {
+            validateVerbType(metadata.verb);
+        }
+        return this.saveVerbMetadata_internal(id, metadata);
+    }
     /**
      * Helper method to convert a Map to a plain object for serialization
      */

package/dist/types/brainyDataInterface.d.ts

@@ -18,14 +18,11 @@ export interface BrainyDataInterface<T = unknown> {
     /**
      * Add a noun (entity with vector and metadata) to the database
      * @param data Text string or vector representation (will auto-embed strings)
+     * @param nounType Required noun type (one of 31 types)
      * @param metadata Optional metadata to associate with the noun
-     * @param options Optional configuration including custom ID
      * @returns The ID of the added noun
      */
-    addNoun(data: string | Vector, metadata?: T, options?: {
-        id?: string;
-        [key: string]: any;
-    }): Promise<string>;
+    addNoun(data: string | Vector, nounType: string, metadata?: T): Promise<string>;
     /**
      * Search for text in the database
      * @param text The text to search for

package/dist/utils/brainyTypes.d.ts

@@ -0,0 +1,217 @@
+/**
+ * BrainyTypes - Complete type management for Brainy
+ *
+ * Provides type lists, validation, and intelligent suggestions
+ * for nouns and verbs using semantic embeddings.
+ *
+ * @example
+ * ```typescript
+ * import { BrainyTypes } from '@soulcraft/brainy'
+ *
+ * // Get all available types
+ * const nounTypes = BrainyTypes.nouns  // ['Person', 'Organization', ...]
+ * const verbTypes = BrainyTypes.verbs  // ['Contains', 'Creates', ...]
+ *
+ * // Validate types
+ * BrainyTypes.isValidNoun('Person')  // true
+ * BrainyTypes.isValidVerb('Unknown') // false
+ *
+ * // Get intelligent suggestions
+ * const personData = {
+ *   name: 'John Doe',
+ *   email: 'john@example.com'
+ * }
+ * const suggestion = await BrainyTypes.suggestNoun(personData)
+ * console.log(suggestion.type) // 'Person'
+ * console.log(suggestion.confidence) // 0.92
+ * ```
+ */
+import { NounType, VerbType } from '../types/graphTypes.js';
+/**
+ * Type suggestion result
+ */
+export interface TypeSuggestion {
+    /** The suggested type */
+    type: NounType | VerbType;
+    /** Confidence score between 0 and 1 */
+    confidence: number;
+    /** Human-readable explanation */
+    reason?: string;
+    /** Alternative suggestions */
+    alternatives?: Array<{
+        type: NounType | VerbType;
+        confidence: number;
+    }>;
+}
+/**
+ * BrainyTypes - Complete type management for Brainy
+ *
+ * Static class providing type lists, validation, and intelligent suggestions.
+ * No instantiation needed - all methods are static.
+ */
+export declare class BrainyTypes {
+    private static instance;
+    private static initialized;
+    /**
+     * All available noun types
+     * @example
+     * ```typescript
+     * BrainyTypes.nouns.forEach(type => console.log(type))
+     * // 'Person', 'Organization', 'Location', ...
+     * ```
+     */
+    static readonly nouns: readonly NounType[];
+    /**
+     * All available verb types
+     * @example
+     * ```typescript
+     * BrainyTypes.verbs.forEach(type => console.log(type))
+     * // 'Contains', 'Creates', 'RelatedTo', ...
+     * ```
+     */
+    static readonly verbs: readonly VerbType[];
+    /**
+     * Get or create the internal matcher instance
+     */
+    private static getInternalMatcher;
+    /**
+     * Check if a string is a valid noun type
+     *
+     * @param type The type string to check
+     * @returns True if valid noun type
+     *
+     * @example
+     * ```typescript
+     * BrainyTypes.isValidNoun('Person')     // true
+     * BrainyTypes.isValidNoun('Unknown')    // false
+     * BrainyTypes.isValidNoun('Contains')   // false (it's a verb)
+     * ```
+     */
+    static isValidNoun(type: string): type is NounType;
+    /**
+     * Check if a string is a valid verb type
+     *
+     * @param type The type string to check
+     * @returns True if valid verb type
+     *
+     * @example
+     * ```typescript
+     * BrainyTypes.isValidVerb('Contains')   // true
+     * BrainyTypes.isValidVerb('Unknown')    // false
+     * BrainyTypes.isValidVerb('Person')     // false (it's a noun)
+     * ```
+     */
+    static isValidVerb(type: string): type is VerbType;
+    /**
+     * Suggest the most appropriate noun type for an object
+     *
+     * @param data The object or data to analyze
+     * @returns Promise resolving to type suggestion with confidence score
+     *
+     * @example
+     * ```typescript
+     * const data = {
+     *   title: 'Quarterly Report',
+     *   author: 'Jane Smith',
+     *   pages: 42
+     * }
+     * const suggestion = await BrainyTypes.suggestNoun(data)
+     * console.log(suggestion.type)       // 'Document'
+     * console.log(suggestion.confidence) // 0.88
+     *
+     * // Check alternatives if confidence is low
+     * if (suggestion.confidence < 0.8) {
+     *   console.log('Also consider:', suggestion.alternatives)
+     * }
+     * ```
+     */
+    static suggestNoun(data: any): Promise<TypeSuggestion>;
+    /**
+     * Suggest the most appropriate verb type for a relationship
+     *
+     * @param source The source entity
+     * @param target The target entity
+     * @param hint Optional hint about the relationship
+     * @returns Promise resolving to type suggestion with confidence score
+     *
+     * @example
+     * ```typescript
+     * const source = { type: 'Person', name: 'Alice' }
+     * const target = { type: 'Document', title: 'Research Paper' }
+     *
+     * const suggestion = await BrainyTypes.suggestVerb(source, target, 'authored')
+     * console.log(suggestion.type)       // 'CreatedBy'
+     * console.log(suggestion.confidence) // 0.91
+     *
+     * // Without hint
+     * const suggestion2 = await BrainyTypes.suggestVerb(source, target)
+     * console.log(suggestion2.type)      // 'RelatedTo' (more generic)
+     * ```
+     */
+    static suggestVerb(source: any, target: any, hint?: string): Promise<TypeSuggestion>;
+    /**
+     * Get a noun type by name (with validation)
+     *
+     * @param name The noun type name
+     * @returns The NounType enum value
+     * @throws Error if invalid noun type
+     *
+     * @example
+     * ```typescript
+     * const type = BrainyTypes.getNoun('Person')  // NounType.Person
+     * const bad = BrainyTypes.getNoun('Unknown')  // throws Error
+     * ```
+     */
+    static getNoun(name: string): NounType;
+    /**
+     * Get a verb type by name (with validation)
+     *
+     * @param name The verb type name
+     * @returns The VerbType enum value
+     * @throws Error if invalid verb type
+     *
+     * @example
+     * ```typescript
+     * const type = BrainyTypes.getVerb('Contains')  // VerbType.Contains
+     * const bad = BrainyTypes.getVerb('Unknown')    // throws Error
+     * ```
+     */
+    static getVerb(name: string): VerbType;
+    /**
+     * Clear the internal cache
+     * Useful when processing many different types of data
+     */
+    static clearCache(): void;
+    /**
+     * Dispose of resources
+     * Call when completely done using BrainyTypes
+     */
+    static dispose(): Promise<void>;
+    /**
+     * Get noun types as a plain object (for iteration)
+     * @returns Object with noun type names as keys
+     */
+    static getNounMap(): Record<string, NounType>;
+    /**
+     * Get verb types as a plain object (for iteration)
+     * @returns Object with verb type names as keys
+     */
+    static getVerbMap(): Record<string, VerbType>;
+}
+export { NounType, VerbType };
+/**
+ * Helper function to validate and suggest types in one call
+ *
+ * @example
+ * ```typescript
+ * import { suggestType } from '@soulcraft/brainy'
+ *
+ * // For nouns
+ * const nounSuggestion = await suggestType('noun', data)
+ *
+ * // For verbs
+ * const verbSuggestion = await suggestType('verb', source, target)
+ * ```
+ */
+export declare function suggestType(kind: 'noun', data: any): Promise<TypeSuggestion>;
+export declare function suggestType(kind: 'verb', source: any, target: any, hint?: string): Promise<TypeSuggestion>;