@soulcraft/brainy 3.19.0 → 3.20.0

package/dist/cli/commands/core.js

@@ -5,13 +5,13 @@
  */
 import chalk from 'chalk';
 import ora from 'ora';
-import { readFileSync, writeFileSync } from 'fs';
-import { BrainyData } from '../../brainyData.js';
+import { readFileSync, writeFileSync } from 'node:fs';
+import { Brainy } from '../../brainy.js';
+import { BrainyTypes, NounType } from '../../index.js';
 let brainyInstance = null;
-const getBrainy = async () => {
+const getBrainy = () => {
     if (!brainyInstance) {
-        brainyInstance = new BrainyData();
-        await brainyInstance.init();
+        brainyInstance = new Brainy();
     }
     return brainyInstance;
 };
@@ -27,7 +27,7 @@ export const coreCommands = {
     async add(text, options) {
         const spinner = ora('Adding to neural database...').start();
         try {
-            const brain = await getBrainy();
+            const brain = getBrainy();
             let metadata = {};
             if (options.metadata) {
                 try {
@@ -41,11 +41,36 @@ export const coreCommands = {
             if (options.id) {
                 metadata.id = options.id;
             }
+            // Determine noun type
+            let nounType;
             if (options.type) {
-                metadata.type = options.type;
+                // Validate provided type
+                if (!BrainyTypes.isValidNoun(options.type)) {
+                    spinner.fail(`Invalid noun type: ${options.type}`);
+                    console.log(chalk.dim('Run "brainy types --noun" to see valid types'));
+                    process.exit(1);
+                }
+                nounType = options.type;
             }
-            // Smart detection by default
-            const result = await brain.add(text, metadata);
+            else {
+                // Use AI to suggest type
+                spinner.text = 'Detecting type with AI...';
+                const suggestion = await BrainyTypes.suggestNoun(typeof text === 'string' ? { content: text, ...metadata } : text);
+                if (suggestion.confidence < 0.6) {
+                    spinner.fail('Could not determine type with confidence');
+                    console.log(chalk.yellow(`Suggestion: ${suggestion.type} (${(suggestion.confidence * 100).toFixed(1)}%)`));
+                    console.log(chalk.dim('Use --type flag to specify explicitly'));
+                    process.exit(1);
+                }
+                nounType = suggestion.type;
+                spinner.text = `Using detected type: ${nounType}`;
+            }
+            // Add with explicit type
+            const result = await brain.add({
+                data: text,
+                type: nounType,
+                metadata
+            });
             spinner.succeed('Added successfully');
             if (!options.json) {
                 console.log(chalk.green(`✓ Added with ID: ${result}`));
@@ -67,43 +92,157 @@ export const coreCommands = {
         }
     },
     /**
-     * Search the neural database
+     * Search the neural database with Triple Intelligence™
      */
     async search(query, options) {
-        const spinner = ora('Searching neural database...').start();
+        const spinner = ora('Searching with Triple Intelligence™...').start();
         try {
-            const brain = await getBrainy();
-            const searchOptions = {
+            const brain = getBrainy();
+            // Build comprehensive search params
+            const searchParams = {
+                query,
                 limit: options.limit ? parseInt(options.limit) : 10
             };
+            // Pagination
+            if (options.offset) {
+                searchParams.offset = parseInt(options.offset);
+            }
+            // Vector Intelligence - similarity threshold
             if (options.threshold) {
-                searchOptions.threshold = parseFloat(options.threshold);
+                searchParams.near = { threshold: parseFloat(options.threshold) };
             }
-            if (options.metadata) {
+            // Metadata Intelligence - type filtering
+            if (options.type) {
+                const types = options.type.split(',').map(t => t.trim());
+                searchParams.type = types.length === 1 ? types[0] : types;
+            }
+            // Metadata Intelligence - field filtering
+            if (options.where) {
                 try {
-                    searchOptions.filter = JSON.parse(options.metadata);
+                    searchParams.where = JSON.parse(options.where);
                 }
                 catch {
-                    spinner.fail('Invalid metadata filter JSON');
+                    spinner.fail('Invalid --where JSON');
+                    console.log(chalk.dim('Example: --where \'{"status":"active","priority":{"$gte":5}}\''));
                     process.exit(1);
                 }
             }
-            const results = await brain.search(query, searchOptions.limit, searchOptions);
+            // Vector Intelligence - proximity search
+            if (options.near) {
+                searchParams.near = {
+                    id: options.near,
+                    threshold: options.threshold ? parseFloat(options.threshold) : 0.7
+                };
+            }
+            // Graph Intelligence - connection constraints
+            if (options.connectedTo || options.connectedFrom || options.via) {
+                searchParams.connected = {};
+                if (options.connectedTo) {
+                    searchParams.connected.to = options.connectedTo;
+                }
+                if (options.connectedFrom) {
+                    searchParams.connected.from = options.connectedFrom;
+                }
+                if (options.via) {
+                    const vias = options.via.split(',').map(v => v.trim());
+                    searchParams.connected.via = vias.length === 1 ? vias[0] : vias;
+                }
+            }
+            // Explanation
+            if (options.explain) {
+                searchParams.explain = true;
+            }
+            // Include relationships
+            if (options.includeRelations) {
+                searchParams.includeRelations = true;
+            }
+            // Triple Intelligence Fusion - custom weighting
+            if (options.fusion || options.vectorWeight || options.graphWeight || options.fieldWeight) {
+                searchParams.fusion = {
+                    strategy: options.fusion || 'adaptive',
+                    weights: {}
+                };
+                if (options.vectorWeight) {
+                    searchParams.fusion.weights.vector = parseFloat(options.vectorWeight);
+                }
+                if (options.graphWeight) {
+                    searchParams.fusion.weights.graph = parseFloat(options.graphWeight);
+                }
+                if (options.fieldWeight) {
+                    searchParams.fusion.weights.field = parseFloat(options.fieldWeight);
+                }
+            }
+            const results = await brain.find(searchParams);
             spinner.succeed(`Found ${results.length} results`);
             if (!options.json) {
                 if (results.length === 0) {
-                    console.log(chalk.yellow('No results found'));
+                    console.log(chalk.yellow('\nNo results found'));
+                    // Show helpful hints
+                    console.log(chalk.dim('\nTips:'));
+                    console.log(chalk.dim('  • Try different search terms'));
+                    console.log(chalk.dim('  • Remove filters (--type, --where, --connected-to)'));
+                    console.log(chalk.dim('  • Lower the --threshold value'));
                 }
                 else {
+                    console.log(chalk.cyan(`\n📊 Triple Intelligence Results:\n`));
                     results.forEach((result, i) => {
-                        console.log(chalk.cyan(`\n${i + 1}. ${result.content || result.id}`));
+                        const entity = result.entity || result;
+                        console.log(chalk.bold(`${i + 1}. ${entity.id}`));
+                        // Show score with breakdown
                         if (result.score !== undefined) {
-                            console.log(chalk.dim(`   Similarity: ${(result.score * 100).toFixed(1)}%`));
+                            console.log(chalk.green(`   Score: ${(result.score * 100).toFixed(1)}%`));
+                            if (options.explain && result.scores) {
+                                const scores = result.scores;
+                                if (scores.vector !== undefined) {
+                                    console.log(chalk.dim(`     Vector: ${(scores.vector * 100).toFixed(1)}%`));
+                                }
+                                if (scores.graph !== undefined) {
+                                    console.log(chalk.dim(`     Graph: ${(scores.graph * 100).toFixed(1)}%`));
+                                }
+                                if (scores.field !== undefined) {
+                                    console.log(chalk.dim(`     Field: ${(scores.field * 100).toFixed(1)}%`));
+                                }
+                            }
+                        }
+                        // Show type
+                        if (entity.type) {
+                            console.log(chalk.dim(`   Type: ${entity.type}`));
+                        }
+                        // Show content preview
+                        if (entity.content) {
+                            const preview = entity.content.substring(0, 80);
+                            console.log(chalk.dim(`   Content: ${preview}${entity.content.length > 80 ? '...' : ''}`));
                         }
-                        if (result.metadata) {
-                            console.log(chalk.dim(`   Metadata: ${JSON.stringify(result.metadata)}`));
+                        // Show metadata
+                        if (entity.metadata && Object.keys(entity.metadata).length > 0) {
+                            console.log(chalk.dim(`   Metadata: ${JSON.stringify(entity.metadata)}`));
                         }
+                        // Show relationships
+                        if (options.includeRelations && result.relations) {
+                            const relations = result.relations;
+                            if (relations.length > 0) {
+                                console.log(chalk.dim(`   Relations: ${relations.length} connections`));
+                            }
+                        }
+                        console.log();
                     });
+                    // Show search summary
+                    console.log(chalk.cyan('Search Configuration:'));
+                    if (searchParams.type) {
+                        console.log(chalk.dim(`  Type filter: ${Array.isArray(searchParams.type) ? searchParams.type.join(', ') : searchParams.type}`));
+                    }
+                    if (searchParams.where) {
+                        console.log(chalk.dim(`  Field filter: ${JSON.stringify(searchParams.where)}`));
+                    }
+                    if (searchParams.connected) {
+                        console.log(chalk.dim(`  Graph filter: ${JSON.stringify(searchParams.connected)}`));
+                    }
+                    if (searchParams.fusion) {
+                        console.log(chalk.dim(`  Fusion: ${searchParams.fusion.strategy}`));
+                        if (searchParams.fusion.weights && Object.keys(searchParams.fusion.weights).length > 0) {
+                            console.log(chalk.dim(`  Weights: ${JSON.stringify(searchParams.fusion.weights)}`));
+                        }
+                    }
                 }
             }
             else {
@@ -113,6 +252,9 @@ export const coreCommands = {
         catch (error) {
             spinner.fail('Search failed');
             console.error(chalk.red(error.message));
+            if (options.verbose) {
+                console.error(chalk.dim(error.stack));
+            }
             process.exit(1);
         }
     },
@@ -122,15 +264,14 @@ export const coreCommands = {
     async get(id, options) {
         const spinner = ora('Fetching item...').start();
         try {
-            const brain = await getBrainy();
+            const brain = getBrainy();
             // Try to get the item
-            const results = await brain.search(id, 1);
-            if (results.length === 0) {
+            const item = await brain.get(id);
+            if (!item) {
                 spinner.fail('Item not found');
                 console.log(chalk.yellow(`No item found with ID: ${id}`));
                 process.exit(1);
             }
-            const item = results[0];
             spinner.succeed('Item found');
             if (!options.json) {
                 console.log(chalk.cyan('\nItem Details:'));
@@ -167,7 +308,7 @@ export const coreCommands = {
     async relate(source, verb, target, options) {
         const spinner = ora('Creating relationship...').start();
         try {
-            const brain = await getBrainy();
+            const brain = getBrainy();
             let metadata = {};
             if (options.metadata) {
                 try {
@@ -182,7 +323,12 @@ export const coreCommands = {
                 metadata.weight = parseFloat(options.weight);
             }
             // Create the relationship
-            const result = await brain.addVerb(source, target, verb, metadata);
+            const result = await brain.relate({
+                from: source,
+                to: target,
+                type: verb,
+                metadata
+            });
             spinner.succeed('Relationship created');
             if (!options.json) {
                 console.log(chalk.green(`✓ Created relationship with ID: ${result}`));
@@ -207,7 +353,7 @@ export const coreCommands = {
     async import(file, options) {
         const spinner = ora('Importing data...').start();
         try {
-            const brain = await getBrainy();
+            const brain = getBrainy();
             const format = options.format || 'json';
             const batchSize = options.batchSize ? parseInt(options.batchSize) : 100;
             // Read file content
@@ -245,15 +391,28 @@ export const coreCommands = {
             for (let i = 0; i < items.length; i += batchSize) {
                 const batch = items.slice(i, i + batchSize);
                 for (const item of batch) {
+                    let content;
+                    let metadata = {};
                     if (typeof item === 'string') {
-                        await brain.add(item);
+                        content = item;
                     }
                     else if (item.content || item.text) {
-                        await brain.add(item.content || item.text, item.metadata || item);
+                        content = item.content || item.text;
+                        metadata = item.metadata || item;
                     }
                     else {
-                        await brain.add(JSON.stringify(item), { originalData: item });
+                        content = JSON.stringify(item);
+                        metadata = { originalData: item };
                     }
+                    // Use AI to detect type for each item
+                    const suggestion = await BrainyTypes.suggestNoun(typeof content === 'string' ? { content, ...metadata } : content);
+                    // Use suggested type or default to Content if low confidence
+                    const nounType = suggestion.confidence >= 0.5 ? suggestion.type : NounType.Content;
+                    await brain.add({
+                        data: content,
+                        type: nounType,
+                        metadata
+                    });
                     imported++;
                 }
                 spinner.text = `Imported ${imported}/${items.length} items...`;
@@ -280,10 +439,11 @@ export const coreCommands = {
     async export(file, options) {
         const spinner = ora('Exporting database...').start();
         try {
-            const brain = await getBrainy();
+            const brain = getBrainy();
             const format = options.format || 'json';
             // Export all data
-            const data = await brain.export({ format: 'json' });
+            const dataApi = await brain.data();
+            const data = await dataApi.export({ format: 'json' });
             let output = '';
             switch (format) {
                 case 'json':

package/dist/cli/commands/data.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Data Management Commands
+ *
+ * Backup, restore, import, export operations
+ */
+interface DataOptions {
+    verbose?: boolean;
+    json?: boolean;
+    pretty?: boolean;
+}
+export declare const dataCommands: {
+    /**
+     * Backup database
+     */
+    backup(file: string, options: DataOptions & {
+        compress?: boolean;
+    }): Promise<void>;
+    /**
+     * Restore from backup
+     */
+    restore(file: string, options: DataOptions & {
+        merge?: boolean;
+    }): Promise<void>;
+    /**
+     * Get database statistics
+     */
+    stats(options: DataOptions): Promise<void>;
+};
+export {};

package/dist/cli/commands/data.js

@@ -0,0 +1,139 @@
+/**
+ * Data Management Commands
+ *
+ * Backup, restore, import, export operations
+ */
+import chalk from 'chalk';
+import ora from 'ora';
+import { readFileSync, writeFileSync } from 'node:fs';
+import { Brainy } from '../../brainy.js';
+let brainyInstance = null;
+const getBrainy = () => {
+    if (!brainyInstance) {
+        brainyInstance = new Brainy();
+    }
+    return brainyInstance;
+};
+const formatOutput = (data, options) => {
+    if (options.json) {
+        console.log(options.pretty ? JSON.stringify(data, null, 2) : JSON.stringify(data));
+    }
+};
+export const dataCommands = {
+    /**
+     * Backup database
+     */
+    async backup(file, options) {
+        const spinner = ora('Creating backup...').start();
+        try {
+            const brain = getBrainy();
+            const dataApi = await brain.data();
+            const backup = await dataApi.backup({
+                compress: options.compress
+            });
+            spinner.text = 'Writing backup file...';
+            // Write backup to file
+            const content = typeof backup === 'string'
+                ? backup
+                : JSON.stringify(backup, null, options.pretty ? 2 : 0);
+            writeFileSync(file, content);
+            spinner.succeed('Backup created');
+            if (!options.json) {
+                console.log(chalk.green(`✓ Backup saved to: ${file}`));
+                if (backup.compressed) {
+                    console.log(chalk.dim(`  Original size: ${formatBytes(backup.originalSize)}`));
+                    console.log(chalk.dim(`  Compressed size: ${formatBytes(backup.compressedSize)}`));
+                    console.log(chalk.dim(`  Compression ratio: ${((backup.compressedSize / backup.originalSize) * 100).toFixed(1)}%`));
+                }
+            }
+            else {
+                formatOutput({ file, backup: true }, options);
+            }
+        }
+        catch (error) {
+            spinner.fail('Backup failed');
+            console.error(chalk.red(error.message));
+            process.exit(1);
+        }
+    },
+    /**
+     * Restore from backup
+     */
+    async restore(file, options) {
+        const spinner = ora('Restoring from backup...').start();
+        try {
+            const brain = getBrainy();
+            const dataApi = await brain.data();
+            // Read backup file
+            const content = readFileSync(file, 'utf-8');
+            const backup = JSON.parse(content);
+            // Restore
+            await dataApi.restore({
+                backup,
+                merge: options.merge || false
+            });
+            spinner.succeed('Restore complete');
+            if (!options.json) {
+                console.log(chalk.green(`✓ Restored from: ${file}`));
+                if (options.merge) {
+                    console.log(chalk.dim('  Mode: Merged with existing data'));
+                }
+                else {
+                    console.log(chalk.dim('  Mode: Replaced all data'));
+                }
+            }
+            else {
+                formatOutput({ file, restored: true }, options);
+            }
+        }
+        catch (error) {
+            spinner.fail('Restore failed');
+            console.error(chalk.red(error.message));
+            process.exit(1);
+        }
+    },
+    /**
+     * Get database statistics
+     */
+    async stats(options) {
+        const spinner = ora('Gathering statistics...').start();
+        try {
+            const brain = getBrainy();
+            const dataApi = await brain.data();
+            const stats = await dataApi.getStats();
+            spinner.succeed('Statistics gathered');
+            if (!options.json) {
+                console.log(chalk.cyan('\n📊 Database Statistics:\n'));
+                console.log(chalk.bold('Entities:'));
+                console.log(`  Total: ${chalk.green(stats.entities)}`);
+                console.log(chalk.bold('\nRelationships:'));
+                console.log(`  Total: ${chalk.green(stats.relations)}`);
+                if (stats.storageSize) {
+                    console.log(chalk.bold('\nStorage:'));
+                    console.log(`  Size: ${chalk.green(formatBytes(stats.storageSize))}`);
+                }
+                if (stats.vectorDimensions) {
+                    console.log(chalk.bold('\nVector Index:'));
+                    console.log(`  Dimensions: ${stats.vectorDimensions}`);
+                }
+            }
+            else {
+                formatOutput(stats, options);
+            }
+        }
+        catch (error) {
+            spinner.fail('Failed to get statistics');
+            console.error(chalk.red(error.message));
+            process.exit(1);
+        }
+    }
+};
+function formatBytes(bytes) {
+    if (bytes === 0)
+        return '0 B';
+    const k = 1024;
+    const sizes = ['B', 'KB', 'MB', 'GB'];
+    const i = Math.floor(Math.log(bytes) / Math.log(k));
+    return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + ' ' + sizes[i];
+}
+//# sourceMappingURL=data.js.map

package/dist/cli/commands/neural.d.ts

@@ -22,4 +22,18 @@ export declare const neuralCommand: {
     builder: (yargs: any) => any;
     handler: (argv: CommandArguments) => Promise<void>;
 };
+declare function handleSimilarCommand(neural: any, argv: CommandArguments): Promise<void>;
+declare function handleClustersCommand(neural: any, argv: CommandArguments): Promise<void>;
+declare function handleHierarchyCommand(neural: any, argv: CommandArguments): Promise<void>;
+declare function handleNeighborsCommand(neural: any, argv: CommandArguments): Promise<void>;
+declare function handleOutliersCommand(neural: any, argv: CommandArguments): Promise<void>;
+declare function handleVisualizeCommand(neural: any, argv: CommandArguments): Promise<void>;
+export declare const neuralCommands: {
+    similar: typeof handleSimilarCommand;
+    cluster: typeof handleClustersCommand;
+    hierarchy: typeof handleHierarchyCommand;
+    related: typeof handleNeighborsCommand;
+    outliers: typeof handleOutliersCommand;
+    visualize: typeof handleVisualizeCommand;
+};
 export default neuralCommand;

package/dist/cli/commands/neural.js

@@ -6,10 +6,9 @@
 import inquirer from 'inquirer';
 import chalk from 'chalk';
 import ora from 'ora';
-import fs from 'fs';
-import path from 'path';
-import { BrainyData } from '../../brainyData.js';
-import { NeuralAPI } from '../../neural/neuralAPI.js';
+import fs from 'node:fs';
+import path from 'node:path';
+import { Brainy } from '../../brainy.js';
 export const neuralCommand = {
     command: 'neural [action]',
     describe: '🧠 Neural similarity and clustering operations',
@@ -79,8 +78,8 @@ export const neuralCommand = {
         console.log(chalk.cyan('\n🧠 NEURAL SIMILARITY API'));
         console.log(chalk.gray('━'.repeat(50)));
         // Initialize Brainy and Neural API
-        const brain = new BrainyData();
-        const neural = new NeuralAPI(brain);
+        const brain = new Brainy();
+        const neural = brain.neural();
         try {
             const action = argv.action || await promptForAction();
             switch (action) {
@@ -97,7 +96,9 @@ export const neuralCommand = {
                     await handleNeighborsCommand(neural, argv);
                     break;
                 case 'path':
-                    await handlePathCommand(neural, argv);
+                    console.log(chalk.yellow('\n⚠️  Semantic path finding coming in v3.21.0'));
+                    console.log(chalk.dim('This feature requires implementing graph traversal algorithms'));
+                    console.log(chalk.dim('Use "neighbors" and "hierarchy" commands to explore connections'));
                     break;
                 case 'outliers':
                     await handleOutliersCommand(neural, argv);
@@ -126,7 +127,7 @@ async function promptForAction() {
                 { name: '🎯 Find semantic clusters', value: 'clusters' },
                 { name: '🌳 Show item hierarchy', value: 'hierarchy' },
                 { name: '🕸️  Find semantic neighbors', value: 'neighbors' },
-                { name: '🛣️  Find semantic path between items', value: 'path' },
+                { name: '🛣️  Find semantic path between items (v3.21.0)', value: 'path', disabled: true },
                 { name: '🚨 Detect outliers', value: 'outliers' },
                 { name: '📊 Generate visualization data', value: 'visualize' }
             ]
@@ -504,5 +505,14 @@ function showHelp() {
     console.log('  --explain, -e     Include explanations');
     console.log('');
 }
+export const neuralCommands = {
+    similar: handleSimilarCommand,
+    cluster: handleClustersCommand,
+    hierarchy: handleHierarchyCommand,
+    related: handleNeighborsCommand,
+    // path: handlePathCommand, // Coming in v3.21.0 - requires graph traversal implementation
+    outliers: handleOutliersCommand,
+    visualize: handleVisualizeCommand
+};
 export default neuralCommand;
 //# sourceMappingURL=neural.js.map

package/dist/cli/commands/types.d.ts

@@ -0,0 +1,30 @@
+/**
+ * CLI Commands for Type Management
+ * Consistent with BrainyTypes public API
+ */
+/**
+ * List types - matches BrainyTypes.nouns and BrainyTypes.verbs
+ * Usage: brainy types
+ */
+export declare function types(options: {
+    json?: boolean;
+    noun?: boolean;
+    verb?: boolean;
+}): Promise<void>;
+/**
+ * Suggest type - matches BrainyTypes.suggestNoun() and suggestVerb()
+ * Usage: brainy suggest <data>
+ * Interactive if data not provided
+ */
+export declare function suggest(data?: string, options?: {
+    verb?: boolean;
+    json?: boolean;
+}): Promise<void>;
+/**
+ * Validate type - matches BrainyTypes.isValidNoun() and isValidVerb()
+ * Usage: brainy validate <type>
+ */
+export declare function validate(type?: string, options?: {
+    verb?: boolean;
+    json?: boolean;
+}): Promise<void>;