From 06b3bc77e1fd4c5544dc61cccd4814bd7a26a1dd Mon Sep 17 00:00:00 2001 From: David Snelling Date: Tue, 7 Oct 2025 17:01:20 -0700 Subject: [PATCH] fix: export ImportManager and add getStats() convenience method Resolves API accessibility issues reported by Brain Cloud Studio team: 1. Export ImportManager and createImportManager - ImportManager class was fully implemented but not exported - Consumers can now access AI-powered import features - Includes ImportOptions and ImportResult types 2. Add brain.getStats() convenience method - Documentation showed getStats() as top-level method - Implementation had it nested under brain.counts.getStats() - Added convenience method that delegates to counts API - Maintains backward compatibility 3. Update API documentation - Corrected getStats() signature and return type - Added comprehensive ImportManager documentation - Included examples for all import patterns These changes expose existing, tested functionality without modifying core behavior. All tests pass. --- docs/API_REFERENCE.md | 118 +++++++++++++++++++++++++++++++++++++++--- src/brainy.ts | 9 ++++ src/index.ts | 8 ++- 3 files changed, 127 insertions(+), 8 deletions(-) diff --git a/docs/API_REFERENCE.md b/docs/API_REFERENCE.md index 6dc10d08..9f0dbad2 100644 --- a/docs/API_REFERENCE.md +++ b/docs/API_REFERENCE.md @@ -775,14 +775,120 @@ const exported = await data.export({ --- -### `async getStats(): Promise` -Gets storage statistics. +### `getStats(): StatsResult` +Gets complete statistics about entities and relationships. **Returns:** -- `entities` - Entity count -- `relations` - Relationship count -- `storageSize` - Storage size in bytes -- `vectorDimensions` - Embedding dimensions +```typescript +{ + entities: { + total: number + byType: Record + } + relationships: { + totalRelationships: number + byType: Record + } + density: number // relationships per entity +} +``` + +**Example:** +```typescript +const stats = brain.getStats() +console.log(`Total entities: ${stats.entities.total}`) +console.log(`Total relationships: ${stats.relationships.totalRelationships}`) +console.log(`Graph density: ${stats.density.toFixed(2)}`) +``` + +**Note:** For more granular counting operations, see the `brain.counts` API below. + +--- + +## Import API + +### `createImportManager(brain: Brainy): ImportManager` +Creates an import manager for intelligent data import. + +**Example:** +```typescript +import { Brainy, createImportManager } from '@soulcraft/brainy' + +const brain = new Brainy({ preset: 'memory' }) +await brain.init() + +const importer = createImportManager(brain) +await importer.init() +``` + +--- + +### `async ImportManager.import(source, options?): Promise` +Import data from various sources with AI-powered entity detection. + +**Parameters:** +- `source` - String, Buffer, array, or object to import +- `options.source` - 'data' | 'file' | 'url' | 'auto' (default: 'auto') +- `options.format` - 'json' | 'csv' | 'text' | 'yaml' | 'auto' (default: 'auto') +- `options.batchSize` - Batch size for processing (default: 50) +- `options.autoDetect` - Auto-detect entity types (default: true) +- `options.typeHint` - Suggested entity type +- `options.extractRelationships` - Extract relationships (default: true) +- `options.csvDelimiter` - CSV delimiter character +- `options.csvHeaders` - CSV has headers (default: true) +- `options.parallel` - Process in parallel (default: true) +- `options.maxConcurrency` - Max concurrent operations + +**Returns:** +```typescript +{ + success: boolean + nouns: string[] // IDs of imported entities + verbs: string[] // IDs of created relationships + errors: string[] + stats: { + total: number + imported: number + failed: number + relationships: number + } +} +``` + +**Examples:** + +```typescript +// Import from CSV file +const result = await importer.importFile('./data.csv', { + format: 'csv', + extractRelationships: true +}) + +// Import from URL +const result = await importer.importUrl('https://api.example.com/data.json') + +// Import array of objects +const data = [ + { name: 'Alice', role: 'Developer' }, + { name: 'Bob', role: 'Designer' } +] +const result = await importer.import(data, { + typeHint: NounType.Person, + extractRelationships: true +}) + +console.log(`Imported ${result.stats.imported}/${result.stats.total} items`) +console.log(`Created ${result.stats.relationships} relationships`) +``` + +**Features:** +- 🧠 **AI Entity Detection** - Auto-detect entity types from data +- 🔗 **Relationship Extraction** - Discover connections automatically +- 📊 **Multi-Format Support** - CSV, JSON, YAML, text files +- 🚀 **Batch Processing** - Efficient handling of large datasets +- 💡 **Neural Analysis** - Confidence scoring and insights +- 🎯 **Smart CSV Parsing** - Auto-delimiter detection +- 🌐 **URL Imports** - Direct import from web sources --- diff --git a/src/brainy.ts b/src/brainy.ts index 12be28a8..834dd248 100644 --- a/src/brainy.ts +++ b/src/brainy.ts @@ -2101,6 +2101,15 @@ export class Brainy implements BrainyInterface { } } + /** + * Get complete statistics - convenience method + * For more granular counting, use brain.counts API + * @returns Complete statistics including entities, relationships, and density + */ + getStats() { + return this.counts.getStats() + } + // ============= HELPER METHODS ============= /** diff --git a/src/index.ts b/src/index.ts index dae3286c..f4ee60ab 100644 --- a/src/index.ts +++ b/src/index.ts @@ -62,14 +62,18 @@ export { // Export Neural Import (AI data understanding) export { NeuralImport } from './cortex/neuralImport.js' -export type { +export type { NeuralAnalysisResult, DetectedEntity, DetectedRelationship, NeuralInsight, - NeuralImportOptions + NeuralImportOptions } from './cortex/neuralImport.js' +// Export Import Manager (comprehensive data import) +export { ImportManager, createImportManager } from './importManager.js' +export type { ImportOptions, ImportResult } from './importManager.js' + // Augmentation types are already exported later in the file // Export distance functions for convenience