@soulcraft/brainy 2.10.1 → 2.12.0

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/typeValidation.d.ts

@@ -0,0 +1,25 @@
+import { NounType, VerbType } from '../types/graphTypes.js';
+export declare function isValidNounType(type: unknown): type is NounType;
+export declare function isValidVerbType(type: unknown): type is VerbType;
+export declare function validateNounType(type: unknown): NounType;
+export declare function validateVerbType(type: unknown): VerbType;
+export interface ValidatedGraphNoun {
+    noun: NounType;
+    [key: string]: any;
+}
+export interface ValidatedGraphVerb {
+    verb: VerbType;
+    [key: string]: any;
+}
+export declare function validateGraphNoun(noun: unknown): ValidatedGraphNoun;
+export declare function validateGraphVerb(verb: unknown): ValidatedGraphVerb;
+export declare function validateNounTypes(types: unknown[]): NounType[];
+export declare function validateVerbTypes(types: unknown[]): VerbType[];
+export interface ValidationStats {
+    validated: number;
+    failed: number;
+    inferred: number;
+    suggestions: number;
+}
+export declare function getValidationStats(): ValidationStats;
+export declare function resetValidationStats(): void;

package/dist/utils/typeValidation.js

@@ -0,0 +1,127 @@
+import { NounType, VerbType } from '../types/graphTypes.js';
+// Type sets for O(1) validation
+const VALID_NOUN_TYPES = new Set(Object.values(NounType));
+const VALID_VERB_TYPES = new Set(Object.values(VerbType));
+// Type guards
+export function isValidNounType(type) {
+    return typeof type === 'string' && VALID_NOUN_TYPES.has(type);
+}
+export function isValidVerbType(type) {
+    return typeof type === 'string' && VALID_VERB_TYPES.has(type);
+}
+// Validators with helpful errors
+export function validateNounType(type) {
+    if (!isValidNounType(type)) {
+        const suggestion = findClosestMatch(String(type), VALID_NOUN_TYPES);
+        throw new Error(`Invalid noun type: '${type}'. ${suggestion ? `Did you mean '${suggestion}'?` : ''} ` +
+            `Valid types are: ${[...VALID_NOUN_TYPES].sort().join(', ')}`);
+    }
+    return type;
+}
+export function validateVerbType(type) {
+    if (!isValidVerbType(type)) {
+        const suggestion = findClosestMatch(String(type), VALID_VERB_TYPES);
+        throw new Error(`Invalid verb type: '${type}'. ${suggestion ? `Did you mean '${suggestion}'?` : ''} ` +
+            `Valid types are: ${[...VALID_VERB_TYPES].sort().join(', ')}`);
+    }
+    return type;
+}
+export function validateGraphNoun(noun) {
+    if (!noun || typeof noun !== 'object') {
+        throw new Error('Invalid noun: must be an object');
+    }
+    const n = noun;
+    if (!n.noun) {
+        throw new Error('Invalid noun: missing required "noun" type field');
+    }
+    n.noun = validateNounType(n.noun);
+    return n;
+}
+export function validateGraphVerb(verb) {
+    if (!verb || typeof verb !== 'object') {
+        throw new Error('Invalid verb: must be an object');
+    }
+    const v = verb;
+    if (!v.verb) {
+        throw new Error('Invalid verb: missing required "verb" type field');
+    }
+    v.verb = validateVerbType(v.verb);
+    return v;
+}
+// Helper for suggestions using Levenshtein distance
+function findClosestMatch(input, validSet) {
+    if (!input)
+        return null;
+    const lower = input.toLowerCase();
+    let bestMatch = null;
+    let bestScore = Infinity;
+    for (const valid of validSet) {
+        const validLower = valid.toLowerCase();
+        // Exact match (case-insensitive)
+        if (validLower === lower) {
+            return valid;
+        }
+        // Substring match
+        if (validLower.includes(lower) || lower.includes(validLower)) {
+            return valid;
+        }
+        // Calculate Levenshtein distance
+        const distance = levenshteinDistance(lower, validLower);
+        if (distance < bestScore && distance <= 3) { // Threshold of 3 for suggestions
+            bestScore = distance;
+            bestMatch = valid;
+        }
+    }
+    return bestMatch;
+}
+// Levenshtein distance implementation
+function levenshteinDistance(str1, str2) {
+    const m = str1.length;
+    const n = str2.length;
+    const dp = Array(m + 1).fill(null).map(() => Array(n + 1).fill(0));
+    for (let i = 0; i <= m; i++) {
+        dp[i][0] = i;
+    }
+    for (let j = 0; j <= n; j++) {
+        dp[0][j] = j;
+    }
+    for (let i = 1; i <= m; i++) {
+        for (let j = 1; j <= n; j++) {
+            if (str1[i - 1] === str2[j - 1]) {
+                dp[i][j] = dp[i - 1][j - 1];
+            }
+            else {
+                dp[i][j] = 1 + Math.min(dp[i - 1][j], // deletion
+                dp[i][j - 1], // insertion
+                dp[i - 1][j - 1] // substitution
+                );
+            }
+        }
+    }
+    return dp[m][n];
+}
+// Batch validation helpers
+export function validateNounTypes(types) {
+    return types.map(validateNounType);
+}
+export function validateVerbTypes(types) {
+    return types.map(validateVerbType);
+}
+let stats = {
+    validated: 0,
+    failed: 0,
+    inferred: 0,
+    suggestions: 0
+};
+export function getValidationStats() {
+    return { ...stats };
+}
+export function resetValidationStats() {
+    stats = {
+        validated: 0,
+        failed: 0,
+        inferred: 0,
+        suggestions: 0
+    };
+}
+//# sourceMappingURL=typeValidation.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soulcraft/brainy",
-  "version": "2.10.1",
+  "version": "2.12.0",
   "description": "Universal Knowledge Protocol™ - World's first Triple Intelligence database unifying vector, graph, and document search in one API. 31 nouns × 40 verbs for infinite expressiveness.",
   "main": "dist/index.js",
   "module": "dist/index.js",