@soulcraft/brainy 3.50.1 → 4.0.0

package/dist/cli/commands/insights.js

@@ -0,0 +1,300 @@
+/**
+ * Insights & Analytics Commands
+ *
+ * Database insights, field statistics, and query optimization
+ */
+import chalk from 'chalk';
+import ora from 'ora';
+import inquirer from 'inquirer';
+import Table from 'cli-table3';
+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 insightsCommands = {
+    /**
+     * Get comprehensive database insights
+     */
+    async insights(options) {
+        const spinner = ora('Analyzing database...').start();
+        try {
+            const brain = getBrainy();
+            // Get insights from Brainy
+            const insights = await brain.insights();
+            spinner.succeed('Analysis complete');
+            if (!options.json) {
+                console.log(chalk.cyan('\n📊 Database Insights:\n'));
+                // Overview - using actual insights return type
+                console.log(chalk.bold('Overview:'));
+                console.log(`  Total Entities: ${chalk.yellow(insights.entities)}`);
+                console.log(`  Total Relationships: ${chalk.yellow(insights.relationships)}`);
+                console.log(`  Unique Types: ${chalk.yellow(Object.keys(insights.types).length)}`);
+                console.log(`  Active Services: ${chalk.yellow(insights.services.join(', '))}`);
+                console.log(`  Graph Density: ${chalk.yellow((insights.density * 100).toFixed(2))}%`);
+                // Entity types breakdown
+                const typeEntries = Object.entries(insights.types).sort((a, b) => b[1] - a[1]);
+                if (typeEntries.length > 0) {
+                    console.log(chalk.bold('\n🏆 Entities by Type:'));
+                    const typeTable = new Table({
+                        head: [chalk.cyan('Type'), chalk.cyan('Count'), chalk.cyan('Percentage')],
+                        colWidths: [25, 12, 15]
+                    });
+                    typeEntries.slice(0, 10).forEach(([type, count]) => {
+                        const percentage = insights.entities > 0 ? (count / insights.entities * 100) : 0;
+                        typeTable.push([
+                            type,
+                            count.toString(),
+                            `${percentage.toFixed(1)}%`
+                        ]);
+                    });
+                    console.log(typeTable.toString());
+                    if (typeEntries.length > 10) {
+                        console.log(chalk.dim(`\n... and ${typeEntries.length - 10} more types`));
+                    }
+                }
+                // Recommendations based on actual data
+                console.log(chalk.bold('\n💡 Recommendations:'));
+                if (insights.entities === 0) {
+                    console.log(`  ${chalk.yellow('→')} Database is empty - add entities to get started`);
+                }
+                else {
+                    if (insights.density < 0.1) {
+                        console.log(`  ${chalk.yellow('→')} Low graph density - consider adding more relationships`);
+                    }
+                    if (insights.relationships === 0) {
+                        console.log(`  ${chalk.yellow('→')} No relationships yet - use 'brainy relate' to connect entities`);
+                    }
+                    if (Object.keys(insights.types).length === 1) {
+                        console.log(`  ${chalk.yellow('→')} Only one entity type - consider adding diverse types for better organization`);
+                    }
+                }
+            }
+            else {
+                formatOutput(insights, options);
+            }
+        }
+        catch (error) {
+            spinner.fail('Failed to get insights');
+            console.error(chalk.red('Insights failed:', error.message));
+            if (options.verbose) {
+                console.error(chalk.dim(error.stack));
+            }
+            process.exit(1);
+        }
+    },
+    /**
+     * Get available fields across all entities
+     */
+    async fields(options) {
+        const spinner = ora('Analyzing fields...').start();
+        try {
+            const brain = getBrainy();
+            // Get available fields from metadata index
+            const fields = await brain.getAvailableFields();
+            spinner.succeed(`Found ${fields.length} fields`);
+            if (!options.json) {
+                if (fields.length === 0) {
+                    console.log(chalk.yellow('\nNo metadata fields found'));
+                    console.log(chalk.dim('Add entities with metadata to see field statistics'));
+                }
+                else {
+                    console.log(chalk.cyan(`\n📋 Available Fields (${fields.length}):\n`));
+                    // Get statistics for each field
+                    const statistics = await brain.getFieldStatistics();
+                    const table = new Table({
+                        head: [chalk.cyan('Field'), chalk.cyan('Occurrences'), chalk.cyan('Unique Values')],
+                        colWidths: [30, 15, 20]
+                    });
+                    for (const field of fields.slice(0, 50)) {
+                        const stats = statistics.get(field);
+                        table.push([
+                            field,
+                            stats?.count || 0,
+                            stats?.uniqueValues || 0
+                        ]);
+                    }
+                    console.log(table.toString());
+                    if (fields.length > 50) {
+                        console.log(chalk.dim(`\n... and ${fields.length - 50} more fields`));
+                    }
+                    console.log(chalk.dim('\n💡 Use --json to see all fields'));
+                }
+            }
+            else {
+                const statistics = await brain.getFieldStatistics();
+                const fieldsWithStats = fields.map(field => ({
+                    field,
+                    ...Object.fromEntries(statistics.get(field) || [])
+                }));
+                formatOutput(fieldsWithStats, options);
+            }
+        }
+        catch (error) {
+            spinner.fail('Failed to get fields');
+            console.error(chalk.red('Fields analysis failed:', error.message));
+            if (options.verbose) {
+                console.error(chalk.dim(error.stack));
+            }
+            process.exit(1);
+        }
+    },
+    /**
+     * Get field values for a specific field
+     */
+    async fieldValues(field, options) {
+        let spinner = null;
+        try {
+            // Interactive mode if no field provided
+            if (!field) {
+                spinner = ora('Getting available fields...').start();
+                const brain = getBrainy();
+                const availableFields = await brain.getAvailableFields();
+                spinner.stop();
+                const answer = await inquirer.prompt([{
+                        type: 'list',
+                        name: 'field',
+                        message: 'Select field:',
+                        choices: availableFields.slice(0, 50),
+                        pageSize: 15
+                    }]);
+                field = answer.field;
+            }
+            spinner = ora(`Getting values for field: ${field}...`).start();
+            const brain = getBrainy();
+            const values = await brain.getFieldValues(field);
+            const limit = options.limit ? parseInt(options.limit) : 100;
+            spinner.succeed(`Found ${values.length} unique values`);
+            if (!options.json) {
+                console.log(chalk.cyan(`\n🔍 Values for field "${chalk.bold(field)}":\n`));
+                if (values.length === 0) {
+                    console.log(chalk.yellow('No values found for this field'));
+                }
+                else {
+                    // Group by value and count
+                    const valueCounts = values.reduce((acc, val) => {
+                        acc[val] = (acc[val] || 0) + 1;
+                        return acc;
+                    }, {});
+                    const sorted = Object.entries(valueCounts)
+                        .sort((a, b) => b[1] - a[1])
+                        .slice(0, limit);
+                    const table = new Table({
+                        head: [chalk.cyan('Value'), chalk.cyan('Count')],
+                        colWidths: [50, 12]
+                    });
+                    sorted.forEach(([value, count]) => {
+                        table.push([value, count.toString()]);
+                    });
+                    console.log(table.toString());
+                    if (values.length > limit) {
+                        console.log(chalk.dim(`\n... and ${values.length - limit} more values (use --limit to show more)`));
+                    }
+                }
+            }
+            else {
+                formatOutput({ field, values, count: values.length }, options);
+            }
+        }
+        catch (error) {
+            if (spinner)
+                spinner.fail('Failed to get field values');
+            console.error(chalk.red('Field values failed:', error.message));
+            if (options.verbose) {
+                console.error(chalk.dim(error.stack));
+            }
+            process.exit(1);
+        }
+    },
+    /**
+     * Get optimal query plan for filters
+     */
+    async queryPlan(options) {
+        let spinner = null;
+        try {
+            let filters = {};
+            // Interactive mode if no filters provided
+            if (!options.filters) {
+                const answer = await inquirer.prompt([{
+                        type: 'editor',
+                        name: 'filters',
+                        message: 'Enter filter JSON (e.g., {"status": "active", "priority": {"$gte": 5}}):',
+                        validate: (input) => {
+                            if (!input.trim())
+                                return 'Filters cannot be empty';
+                            try {
+                                JSON.parse(input);
+                                return true;
+                            }
+                            catch {
+                                return 'Invalid JSON format';
+                            }
+                        }
+                    }]);
+                filters = JSON.parse(answer.filters);
+            }
+            else {
+                try {
+                    filters = JSON.parse(options.filters);
+                }
+                catch {
+                    console.error(chalk.red('Invalid JSON in --filters'));
+                    process.exit(1);
+                }
+            }
+            spinner = ora('Analyzing optimal query plan...').start();
+            const brain = getBrainy();
+            const plan = await brain.getOptimalQueryPlan(filters);
+            spinner.succeed('Query plan generated');
+            if (!options.json) {
+                console.log(chalk.cyan('\n🎯 Optimal Query Plan:\n'));
+                console.log(chalk.bold('Filters:'));
+                console.log(JSON.stringify(filters, null, 2));
+                console.log(chalk.bold('\n📊 Query Execution Plan:'));
+                console.log(`  Strategy: ${chalk.yellow(plan.strategy)}`);
+                console.log(`  Estimated Cost: ${chalk.yellow(plan.estimatedCost)}`);
+                if (plan.fieldOrder && plan.fieldOrder.length > 0) {
+                    console.log(chalk.bold('\n🔍 Field Processing Order (Optimized):'));
+                    plan.fieldOrder.forEach((field, index) => {
+                        console.log(`  ${index + 1}. ${chalk.green(field)}`);
+                    });
+                }
+                console.log(chalk.bold('\n💡 Strategy Explanation:'));
+                if (plan.strategy === 'exact') {
+                    console.log(`  ${chalk.yellow('→')} Using exact-match indexing for fast lookups`);
+                }
+                else if (plan.strategy === 'range') {
+                    console.log(`  ${chalk.yellow('→')} Using range-based scanning for numeric/date filters`);
+                }
+                else if (plan.strategy === 'hybrid') {
+                    console.log(`  ${chalk.yellow('→')} Using hybrid approach combining multiple index types`);
+                }
+                console.log(chalk.bold('\n⚡ Performance Tips:'));
+                console.log(`  ${chalk.yellow('→')} Lower estimated cost means faster queries`);
+                console.log(`  ${chalk.yellow('→')} Fields are processed in optimal order`);
+                console.log(`  ${chalk.yellow('→')} Consider adding indexes for frequently used fields`);
+            }
+            else {
+                formatOutput({ filters, plan }, options);
+            }
+        }
+        catch (error) {
+            if (spinner)
+                spinner.fail('Failed to generate query plan');
+            console.error(chalk.red('Query plan failed:', error.message));
+            if (options.verbose) {
+                console.error(chalk.dim(error.stack));
+            }
+            process.exit(1);
+        }
+    }
+};
+//# sourceMappingURL=insights.js.map

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

@@ -22,18 +22,12 @@ 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;
+    similar(a?: string, b?: string, options?: any): Promise<void>;
+    cluster(options?: any): Promise<void>;
+    hierarchy(id?: string, options?: any): Promise<void>;
+    related(id?: string, options?: any): Promise<void>;
+    outliers(options?: any): Promise<void>;
+    visualize(options?: any): Promise<void>;
 };
 export default neuralCommand;

package/dist/cli/commands/neural.js

@@ -205,13 +205,49 @@ async function handleSimilarCommand(neural, argv) {
     }
 }
 async function handleClustersCommand(neural, argv) {
-    const spinner = ora('🎯 Finding semantic clusters...').start();
+    let spinner = null;
     try {
-        const options = {
+        let options = {
             algorithm: argv.algorithm,
             threshold: argv.threshold,
             maxClusters: argv.limit
         };
+        // Interactive mode if no algorithm specified or using defaults
+        if (!argv.algorithm || argv.algorithm === 'hierarchical') {
+            const answers = await inquirer.prompt([
+                {
+                    type: 'list',
+                    name: 'algorithm',
+                    message: 'Choose clustering algorithm:',
+                    default: argv.algorithm || 'hierarchical',
+                    choices: [
+                        { name: '🌳 Hierarchical (Tree-based, best for natural grouping)', value: 'hierarchical' },
+                        { name: '📊 K-Means (Fixed number of clusters)', value: 'kmeans' },
+                        { name: '🎯 DBSCAN (Density-based, finds arbitrary shapes)', value: 'dbscan' }
+                    ]
+                },
+                {
+                    type: 'number',
+                    name: 'maxClusters',
+                    message: 'Maximum number of clusters:',
+                    default: argv.limit || 5,
+                    when: (answers) => answers.algorithm === 'kmeans'
+                },
+                {
+                    type: 'number',
+                    name: 'threshold',
+                    message: 'Similarity threshold (0-1):',
+                    default: argv.threshold || 0.7,
+                    validate: (input) => (input >= 0 && input <= 1) || 'Must be between 0 and 1'
+                }
+            ]);
+            options = {
+                algorithm: answers.algorithm,
+                threshold: answers.threshold,
+                maxClusters: answers.maxClusters || options.maxClusters
+            };
+        }
+        const spinner = ora('🎯 Finding semantic clusters...').start();
         const clusters = await neural.clusters(argv.query || options);
         spinner.succeed(`✅ Found ${clusters.length} clusters`);
         if (argv.format === 'json') {
@@ -242,7 +278,8 @@ async function handleClustersCommand(neural, argv) {
         }
     }
     catch (error) {
-        spinner.fail('💥 Failed to find clusters');
+        if (spinner)
+            spinner.fail('💥 Failed to find clusters');
         throw error;
     }
 }
@@ -505,14 +542,80 @@ function showHelp() {
     console.log('  --explain, -e     Include explanations');
     console.log('');
 }
+// Commander-compatible wrappers
 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
+    async similar(a, b, options) {
+        const brain = new Brainy();
+        const neural = brain.neural();
+        // Build argv-style object for handler
+        const argv = {
+            _: ['neural', 'similar', a || '', b || ''].filter(x => x),
+            id: a,
+            query: b,
+            explain: options?.explain,
+            ...options
+        };
+        await handleSimilarCommand(neural, argv);
+    },
+    async cluster(options) {
+        const brain = new Brainy();
+        const neural = brain.neural();
+        const argv = {
+            _: ['neural', 'cluster'],
+            algorithm: options?.algorithm || 'hierarchical',
+            threshold: options?.threshold ? parseFloat(options.threshold) : 0.7,
+            limit: options?.maxClusters ? parseInt(options.maxClusters) : 10,
+            query: options?.near,
+            ...options
+        };
+        await handleClustersCommand(neural, argv);
+    },
+    async hierarchy(id, options) {
+        const brain = new Brainy();
+        const neural = brain.neural();
+        const argv = {
+            _: ['neural', 'hierarchy', id || ''].filter(x => x),
+            id,
+            ...options
+        };
+        await handleHierarchyCommand(neural, argv);
+    },
+    async related(id, options) {
+        const brain = new Brainy();
+        const neural = brain.neural();
+        const argv = {
+            _: ['neural', 'related', id || ''].filter(x => x),
+            id,
+            limit: options?.limit ? parseInt(options.limit) : 10,
+            threshold: options?.radius ? parseFloat(options.radius) : 0.3,
+            ...options
+        };
+        await handleNeighborsCommand(neural, argv);
+    },
+    async outliers(options) {
+        const brain = new Brainy();
+        const neural = brain.neural();
+        const argv = {
+            _: ['neural', 'outliers'],
+            threshold: options?.threshold ? parseFloat(options.threshold) : 0.3,
+            explain: options?.explain,
+            ...options
+        };
+        await handleOutliersCommand(neural, argv);
+    },
+    async visualize(options) {
+        const brain = new Brainy();
+        const neural = brain.neural();
+        const argv = {
+            _: ['neural', 'visualize'],
+            format: options?.format || 'json',
+            dimensions: options?.dimensions ? parseInt(options.dimensions) : 2,
+            limit: options?.maxNodes ? parseInt(options.maxNodes) : 500,
+            output: options?.output,
+            ...options
+        };
+        await handleVisualizeCommand(neural, argv);
+    }
 };
 export default neuralCommand;
 //# sourceMappingURL=neural.js.map

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

@@ -0,0 +1,28 @@
+/**
+ * NLP Commands - Natural Language Processing
+ *
+ * Extract entities, concepts, and insights from text using Brainy's neural NLP
+ */
+interface NLPOptions {
+    verbose?: boolean;
+    json?: boolean;
+    pretty?: boolean;
+    quiet?: boolean;
+}
+export declare const nlpCommands: {
+    /**
+     * Extract entities from text
+     */
+    extract(text: string | undefined, options: NLPOptions): Promise<void>;
+    /**
+     * Extract concepts from text
+     */
+    extractConcepts(text: string | undefined, options: NLPOptions & {
+        threshold?: string;
+    }): Promise<void>;
+    /**
+     * Analyze text with full NLP pipeline
+     */
+    analyze(text: string | undefined, options: NLPOptions): Promise<void>;
+};
+export {};