@soulcraft/brainy 3.0.0 → 3.0.1

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>;

package/dist/utils/brainyTypes.js

@@ -0,0 +1,261 @@
+/**
+ * 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';
+import { BrainyTypes as InternalBrainyTypes } from '../augmentations/typeMatching/brainyTypes.js';
+/**
+ * BrainyTypes - Complete type management for Brainy
+ *
+ * Static class providing type lists, validation, and intelligent suggestions.
+ * No instantiation needed - all methods are static.
+ */
+export class BrainyTypes {
+    /**
+     * Get or create the internal matcher instance
+     */
+    static async getInternalMatcher() {
+        if (!this.instance) {
+            this.instance = new InternalBrainyTypes();
+            await this.instance.init();
+            this.initialized = true;
+        }
+        return this.instance;
+    }
+    /**
+     * 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) {
+        return this.nouns.includes(type);
+    }
+    /**
+     * 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) {
+        return this.verbs.includes(type);
+    }
+    /**
+     * 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 async suggestNoun(data) {
+        const matcher = await this.getInternalMatcher();
+        const result = await matcher.matchNounType(data);
+        return {
+            type: result.type,
+            confidence: result.confidence,
+            reason: result.reasoning,
+            alternatives: result.alternatives?.map(alt => ({
+                type: alt.type,
+                confidence: alt.confidence
+            }))
+        };
+    }
+    /**
+     * 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 async suggestVerb(source, target, hint) {
+        const matcher = await this.getInternalMatcher();
+        const result = await matcher.matchVerbType(source, target, hint);
+        return {
+            type: result.type,
+            confidence: result.confidence,
+            reason: result.reasoning,
+            alternatives: result.alternatives?.map(alt => ({
+                type: alt.type,
+                confidence: alt.confidence
+            }))
+        };
+    }
+    /**
+     * 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) {
+        if (!this.isValidNoun(name)) {
+            throw new Error(`Invalid noun type: '${name}'. Valid types are: ${this.nouns.join(', ')}`);
+        }
+        return name;
+    }
+    /**
+     * 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) {
+        if (!this.isValidVerb(name)) {
+            throw new Error(`Invalid verb type: '${name}'. Valid types are: ${this.verbs.join(', ')}`);
+        }
+        return name;
+    }
+    /**
+     * Clear the internal cache
+     * Useful when processing many different types of data
+     */
+    static clearCache() {
+        this.instance?.clearCache();
+    }
+    /**
+     * Dispose of resources
+     * Call when completely done using BrainyTypes
+     */
+    static async dispose() {
+        if (this.instance) {
+            await this.instance.dispose();
+            this.instance = null;
+            this.initialized = false;
+        }
+    }
+    /**
+     * Get noun types as a plain object (for iteration)
+     * @returns Object with noun type names as keys
+     */
+    static getNounMap() {
+        const map = {};
+        for (const noun of this.nouns) {
+            map[noun] = noun;
+        }
+        return map;
+    }
+    /**
+     * Get verb types as a plain object (for iteration)
+     * @returns Object with verb type names as keys
+     */
+    static getVerbMap() {
+        const map = {};
+        for (const verb of this.verbs) {
+            map[verb] = verb;
+        }
+        return map;
+    }
+}
+BrainyTypes.instance = null;
+BrainyTypes.initialized = false;
+/**
+ * All available noun types
+ * @example
+ * ```typescript
+ * BrainyTypes.nouns.forEach(type => console.log(type))
+ * // 'Person', 'Organization', 'Location', ...
+ * ```
+ */
+BrainyTypes.nouns = Object.freeze(Object.values(NounType));
+/**
+ * All available verb types
+ * @example
+ * ```typescript
+ * BrainyTypes.verbs.forEach(type => console.log(type))
+ * // 'Contains', 'Creates', 'RelatedTo', ...
+ * ```
+ */
+BrainyTypes.verbs = Object.freeze(Object.values(VerbType));
+// Re-export the enums for convenience
+export { NounType, VerbType };
+export async function suggestType(kind, ...args) {
+    if (kind === 'noun') {
+        return BrainyTypes.suggestNoun(args[0]);
+    }
+    else {
+        return BrainyTypes.suggestVerb(args[0], args[1], args[2]);
+    }
+}
+//# sourceMappingURL=brainyTypes.js.map

package/dist/utils/cacheAutoConfig.d.ts

@@ -3,7 +3,7 @@
  * Adapts cache settings based on environment, usage patterns, and storage type
  */
 import { SearchCacheConfig } from './searchCache.js';
-import { BrainyDataConfig } from '../brainyData.js';
+import { BrainyConfig } from '../brainy.js';
 export interface CacheUsageStats {
     totalQueries: number;
     repeatQueries: number;
@@ -16,7 +16,7 @@ export interface CacheUsageStats {
 }
 export interface AutoConfigResult {
     cacheConfig: SearchCacheConfig;
-    realtimeConfig: NonNullable<BrainyDataConfig['realtimeUpdates']>;
+    realtimeConfig: NonNullable<BrainyConfig['realtimeUpdates']>;
     reasoning: string[];
 }
 export declare class CacheAutoConfigurator {
@@ -26,7 +26,7 @@ export declare class CacheAutoConfigurator {
     /**
      * Auto-detect optimal cache configuration based on current conditions
      */
-    autoDetectOptimalConfig(storageConfig?: BrainyDataConfig['storage'], currentStats?: Partial<CacheUsageStats>): AutoConfigResult;
+    autoDetectOptimalConfig(storageConfig?: BrainyConfig['storage'], currentStats?: Partial<CacheUsageStats>): AutoConfigResult;
     /**
      * Dynamically adjust configuration based on runtime performance
      */

package/dist/utils/embedding.d.ts

@@ -25,8 +25,8 @@ export interface TransformerEmbeddingOptions {
     cacheDir?: string;
     /** Force local files only (no downloads) */
     localFilesOnly?: boolean;
-    /** Quantization setting (fp32, fp16, q8, q4) */
-    dtype?: 'fp32' | 'fp16' | 'q8' | 'q4';
+    /** Model precision: 'q8' = 75% smaller quantized model, 'fp32' = full precision (default) */
+    precision?: 'fp32' | 'q8';
     /** Device to run inference on - 'auto' detects best available */
     device?: 'auto' | 'cpu' | 'webgpu' | 'cuda' | 'gpu';
 }
@@ -51,6 +51,10 @@ export declare class TransformerEmbedding implements EmbeddingModel {
      * Log message only if verbose mode is enabled
      */
     private logger;
+    /**
+     * Generate mock embeddings for unit tests
+     */
+    private getMockEmbedding;
     /**
      * Initialize the embedding model
      */
@@ -78,12 +82,13 @@ export declare const UniversalSentenceEncoder: typeof TransformerEmbedding;
  */
 export declare function createEmbeddingModel(options?: TransformerEmbeddingOptions): EmbeddingModel;
 /**
- * Default embedding function using the hybrid model manager (BEST OF BOTH WORLDS)
- * Prevents multiple model loads while supporting multi-source downloading
+ * Default embedding function using the unified EmbeddingManager
+ * Simple, clean, reliable - no more layers of indirection
  */
 export declare const defaultEmbeddingFunction: EmbeddingFunction;
 /**
  * Create an embedding function with custom options
+ * NOTE: Options are validated but the singleton EmbeddingManager is always used
  */
 export declare function createEmbeddingFunction(options?: TransformerEmbeddingOptions): EmbeddingFunction;
 /**