@soulcraft/brainy 3.0.0 → 3.0.1

package/dist/brainyDataV3.d.ts

@@ -0,0 +1,186 @@
+/**
+ * BrainyData V3 - Consistent API Design
+ *
+ * This is a proposed update to BrainyData with consistent method signatures.
+ * All methods use object parameters for consistency and extensibility.
+ */
+import type { AddNounParams, AddVerbParams, SearchParams, SimilarityParams, RelatedParams, BatchNounsParams, BatchVerbsParams, GetNounsParams, GetVerbsParams, UpdateNounParams, MetadataParams, StatisticsParams, SearchResult, PaginatedResult, BatchResult, StatisticsResult } from './types/apiTypes.js';
+/**
+ * Proposed consistent API for BrainyData
+ * All methods use object parameters
+ */
+export declare class BrainyDataV3 {
+    constructor(config?: any);
+    init(): Promise<void>;
+    close(): Promise<void>;
+    /**
+     * Add a single noun
+     * OLD: addNoun(data, type, metadata)
+     * NEW: addNoun({ data, type, metadata })
+     */
+    addNoun(params: AddNounParams): Promise<string>;
+    /**
+     * Add multiple nouns in batch
+     * NEW METHOD for better performance
+     */
+    addNouns(params: BatchNounsParams): Promise<BatchResult>;
+    /**
+     * Get a single noun by ID
+     * OLD: getNoun(id)
+     * NEW: getNoun(id) - unchanged, simple enough
+     */
+    getNoun(id: string): Promise<any | null>;
+    /**
+     * Get multiple nouns with filtering
+     * NEW METHOD for batch retrieval
+     */
+    getNouns(params: GetNounsParams): Promise<PaginatedResult<any>>;
+    /**
+     * Update a noun
+     * OLD: updateNoun(id, data, metadata) - scattered
+     * NEW: updateNoun({ id, data, metadata })
+     */
+    updateNoun(params: UpdateNounParams): Promise<void>;
+    /**
+     * Delete a noun
+     * OLD: deleteNoun(id)
+     * NEW: deleteNoun(id) - unchanged, simple enough
+     */
+    deleteNoun(id: string): Promise<void>;
+    /**
+     * Add a single verb (relationship)
+     * OLD: addVerb(source, target, type, metadata, weight)
+     * NEW: addVerb({ source, target, type, weight, metadata })
+     */
+    addVerb(params: AddVerbParams): Promise<string>;
+    /**
+     * Add multiple verbs in batch
+     * NEW METHOD for better performance
+     */
+    addVerbs(params: BatchVerbsParams): Promise<BatchResult>;
+    /**
+     * Get a single verb by ID
+     * OLD: getVerb(id)
+     * NEW: getVerb(id) - unchanged, simple enough
+     */
+    getVerb(id: string): Promise<any | null>;
+    /**
+     * Get multiple verbs with filtering
+     * OLD: getVerbsBySource(id), getVerbsByTarget(id), etc.
+     * NEW: getVerbs({ source?, target?, type? })
+     */
+    getVerbs(params: GetVerbsParams): Promise<PaginatedResult<any>>;
+    /**
+     * Delete a verb
+     * OLD: deleteVerb(id)
+     * NEW: deleteVerb(id) - unchanged, simple enough
+     */
+    deleteVerb(id: string): Promise<void>;
+    /**
+     * Unified search method
+     * OLD: search(options), searchText(query, limit)
+     * NEW: search({ query, limit, filter })
+     */
+    search(params: SearchParams): Promise<SearchResult[]>;
+    /**
+     * Find similar items
+     * OLD: findSimilar(id, limit)
+     * NEW: findSimilar({ id, limit, filter })
+     */
+    findSimilar(params: SimilarityParams): Promise<SearchResult[]>;
+    /**
+     * Find related items through graph traversal
+     * OLD: getRelated(id, options)
+     * NEW: findRelated({ id, depth, types })
+     */
+    findRelated(params: RelatedParams): Promise<PaginatedResult<any>>;
+    /**
+     * Get metadata for an entity
+     * OLD: getMetadata(id)
+     * NEW: getMetadata(id) - unchanged, simple enough
+     */
+    getMetadata(id: string): Promise<any | null>;
+    /**
+     * Update metadata for an entity
+     * OLD: updateMetadata(id, metadata)
+     * NEW: updateMetadata({ id, metadata, merge })
+     */
+    updateMetadata(params: MetadataParams): Promise<void>;
+    /**
+     * Get database statistics
+     * OLD: getStatistics()
+     * NEW: getStatistics({ detailed?, includeAugmentations? })
+     */
+    getStatistics(params?: StatisticsParams): Promise<StatisticsResult>;
+    get neural(): {
+        /**
+         * Calculate similarity between two items
+         * Already good: neural.similar(a, b)
+         */
+        similar: (a: any, b: any) => Promise<number>;
+        /**
+         * Cluster items semantically
+         * Already good: neural.clusters(items?)
+         */
+        clusters: (items?: string[]) => Promise<any[]>;
+        /**
+         * Find nearest neighbors
+         * Already good: neural.neighbors(id, { limit })
+         */
+        neighbors: (id: string, options?: any) => Promise<any[]>;
+        /**
+         * Build semantic hierarchy
+         * Already good: neural.hierarchy(id)
+         */
+        hierarchy: (id: string) => Promise<any>;
+        /**
+         * Detect outliers
+         * Already good: neural.outliers()
+         */
+        outliers: () => Promise<any[]>;
+        /**
+         * Get visualization data
+         * Already good: neural.visualize()
+         */
+        visualize: () => Promise<any>;
+    };
+    get augmentations(): {
+        add: (aug: any) => void;
+        remove: (name: string) => void;
+        get: (name: string) => null;
+        execute: (op: string, params: any) => Promise<void>;
+        getTypes: () => never[];
+    };
+}
+/**
+ * Migration wrapper for backward compatibility
+ * This allows existing code to work with the new API
+ */
+export declare class BrainyDataMigrationWrapper extends BrainyDataV3 {
+    /**
+     * OLD SIGNATURE: addNoun(data, type, metadata)
+     * Wraps to NEW: addNoun({ data, type, metadata })
+     */
+    addNoun(dataOrParams: any | AddNounParams, type?: string, metadata?: any): Promise<string>;
+    /**
+     * OLD SIGNATURE: addVerb(source, target, type, metadata, weight)
+     * Wraps to NEW: addVerb({ source, target, type, weight, metadata })
+     */
+    addVerb(sourceOrParams: string | AddVerbParams, target?: string, type?: string, metadata?: any, weight?: number): Promise<string>;
+    /**
+     * OLD SIGNATURE: searchText(query, limit)
+     * Wraps to NEW: search({ query, limit })
+     */
+    searchText(query: string, limit?: number): Promise<SearchResult[]>;
+    /**
+     * OLD SIGNATURE: findSimilar(id, limit)
+     * Wraps to NEW: findSimilar({ id, limit })
+     */
+    findSimilar(idOrParams: string | SimilarityParams, limit?: number): Promise<SearchResult[]>;
+    /**
+     * OLD METHODS: getVerbsBySource, getVerbsByTarget
+     * Wraps to NEW: getVerbs({ source }) or getVerbs({ target })
+     */
+    getVerbsBySource(sourceId: string): Promise<any[]>;
+    getVerbsByTarget(targetId: string): Promise<any[]>;
+}

package/dist/brainyDataV3.js

@@ -0,0 +1,337 @@
+/**
+ * BrainyData V3 - Consistent API Design
+ *
+ * This is a proposed update to BrainyData with consistent method signatures.
+ * All methods use object parameters for consistency and extensibility.
+ */
+/**
+ * Proposed consistent API for BrainyData
+ * All methods use object parameters
+ */
+export class BrainyDataV3 {
+    // ============= INITIALIZATION =============
+    constructor(config) {
+        // Same as before
+    }
+    async init() {
+        // Same as before
+    }
+    async close() {
+        // Same as before
+    }
+    // ============= NOUN OPERATIONS =============
+    /**
+     * Add a single noun
+     * OLD: addNoun(data, type, metadata)
+     * NEW: addNoun({ data, type, metadata })
+     */
+    async addNoun(params) {
+        // Implementation
+        return 'id';
+    }
+    /**
+     * Add multiple nouns in batch
+     * NEW METHOD for better performance
+     */
+    async addNouns(params) {
+        // Implementation
+        return {
+            successful: [],
+            failed: [],
+            total: 0,
+            duration: 0
+        };
+    }
+    /**
+     * Get a single noun by ID
+     * OLD: getNoun(id)
+     * NEW: getNoun(id) - unchanged, simple enough
+     */
+    async getNoun(id) {
+        // Implementation
+        return null;
+    }
+    /**
+     * Get multiple nouns with filtering
+     * NEW METHOD for batch retrieval
+     */
+    async getNouns(params) {
+        // Implementation
+        return {
+            items: [],
+            hasMore: false
+        };
+    }
+    /**
+     * Update a noun
+     * OLD: updateNoun(id, data, metadata) - scattered
+     * NEW: updateNoun({ id, data, metadata })
+     */
+    async updateNoun(params) {
+        // Implementation
+    }
+    /**
+     * Delete a noun
+     * OLD: deleteNoun(id)
+     * NEW: deleteNoun(id) - unchanged, simple enough
+     */
+    async deleteNoun(id) {
+        // Implementation
+    }
+    // ============= VERB OPERATIONS =============
+    /**
+     * Add a single verb (relationship)
+     * OLD: addVerb(source, target, type, metadata, weight)
+     * NEW: addVerb({ source, target, type, weight, metadata })
+     */
+    async addVerb(params) {
+        // Implementation
+        return 'id';
+    }
+    /**
+     * Add multiple verbs in batch
+     * NEW METHOD for better performance
+     */
+    async addVerbs(params) {
+        // Implementation
+        return {
+            successful: [],
+            failed: [],
+            total: 0,
+            duration: 0
+        };
+    }
+    /**
+     * Get a single verb by ID
+     * OLD: getVerb(id)
+     * NEW: getVerb(id) - unchanged, simple enough
+     */
+    async getVerb(id) {
+        // Implementation
+        return null;
+    }
+    /**
+     * Get multiple verbs with filtering
+     * OLD: getVerbsBySource(id), getVerbsByTarget(id), etc.
+     * NEW: getVerbs({ source?, target?, type? })
+     */
+    async getVerbs(params) {
+        // Implementation
+        return {
+            items: [],
+            hasMore: false
+        };
+    }
+    /**
+     * Delete a verb
+     * OLD: deleteVerb(id)
+     * NEW: deleteVerb(id) - unchanged, simple enough
+     */
+    async deleteVerb(id) {
+        // Implementation
+    }
+    // ============= SEARCH OPERATIONS =============
+    /**
+     * Unified search method
+     * OLD: search(options), searchText(query, limit)
+     * NEW: search({ query, limit, filter })
+     */
+    async search(params) {
+        // Implementation
+        return [];
+    }
+    /**
+     * Find similar items
+     * OLD: findSimilar(id, limit)
+     * NEW: findSimilar({ id, limit, filter })
+     */
+    async findSimilar(params) {
+        // Implementation
+        return [];
+    }
+    /**
+     * Find related items through graph traversal
+     * OLD: getRelated(id, options)
+     * NEW: findRelated({ id, depth, types })
+     */
+    async findRelated(params) {
+        // Implementation
+        return {
+            items: [],
+            hasMore: false
+        };
+    }
+    // ============= METADATA OPERATIONS =============
+    /**
+     * Get metadata for an entity
+     * OLD: getMetadata(id)
+     * NEW: getMetadata(id) - unchanged, simple enough
+     */
+    async getMetadata(id) {
+        // Implementation
+        return null;
+    }
+    /**
+     * Update metadata for an entity
+     * OLD: updateMetadata(id, metadata)
+     * NEW: updateMetadata({ id, metadata, merge })
+     */
+    async updateMetadata(params) {
+        // Implementation
+    }
+    // ============= STATISTICS =============
+    /**
+     * Get database statistics
+     * OLD: getStatistics()
+     * NEW: getStatistics({ detailed?, includeAugmentations? })
+     */
+    async getStatistics(params) {
+        // Implementation
+        return {
+            nouns: { total: 0, byType: {} },
+            verbs: { total: 0, byType: {} },
+            storage: { used: 0, type: 'memory' }
+        };
+    }
+    // ============= NEURAL API (unchanged - already good) =============
+    get neural() {
+        return {
+            /**
+             * Calculate similarity between two items
+             * Already good: neural.similar(a, b)
+             */
+            similar: async (a, b) => {
+                // Implementation
+                return 0;
+            },
+            /**
+             * Cluster items semantically
+             * Already good: neural.clusters(items?)
+             */
+            clusters: async (items) => {
+                // Implementation
+                return [];
+            },
+            /**
+             * Find nearest neighbors
+             * Already good: neural.neighbors(id, { limit })
+             */
+            neighbors: async (id, options) => {
+                // Implementation
+                return [];
+            },
+            /**
+             * Build semantic hierarchy
+             * Already good: neural.hierarchy(id)
+             */
+            hierarchy: async (id) => {
+                // Implementation
+                return {};
+            },
+            /**
+             * Detect outliers
+             * Already good: neural.outliers()
+             */
+            outliers: async () => {
+                // Implementation
+                return [];
+            },
+            /**
+             * Get visualization data
+             * Already good: neural.visualize()
+             */
+            visualize: async () => {
+                // Implementation
+                return {};
+            }
+        };
+    }
+    // ============= AUGMENTATIONS (unchanged - already consistent) =============
+    get augmentations() {
+        return {
+            add: (aug) => { },
+            remove: (name) => { },
+            get: (name) => null,
+            execute: async (op, params) => { },
+            getTypes: () => []
+        };
+    }
+}
+/**
+ * Migration wrapper for backward compatibility
+ * This allows existing code to work with the new API
+ */
+export class BrainyDataMigrationWrapper extends BrainyDataV3 {
+    /**
+     * OLD SIGNATURE: addNoun(data, type, metadata)
+     * Wraps to NEW: addNoun({ data, type, metadata })
+     */
+    async addNoun(dataOrParams, type, metadata) {
+        // If called with object params (new style)
+        if (arguments.length === 1 && typeof dataOrParams === 'object' && 'type' in dataOrParams) {
+            return super.addNoun(dataOrParams);
+        }
+        // If called with positional params (old style)
+        console.warn('Deprecated: Use addNoun({ data, type, metadata }) instead');
+        return super.addNoun({
+            data: dataOrParams,
+            type: type,
+            metadata
+        });
+    }
+    /**
+     * OLD SIGNATURE: addVerb(source, target, type, metadata, weight)
+     * Wraps to NEW: addVerb({ source, target, type, weight, metadata })
+     */
+    async addVerb(sourceOrParams, target, type, metadata, weight) {
+        // If called with object params (new style)
+        if (arguments.length === 1 && typeof sourceOrParams === 'object' && 'source' in sourceOrParams) {
+            return super.addVerb(sourceOrParams);
+        }
+        // If called with positional params (old style)
+        console.warn('Deprecated: Use addVerb({ source, target, type, weight, metadata }) instead');
+        return super.addVerb({
+            source: sourceOrParams,
+            target: target,
+            type: type,
+            weight,
+            metadata
+        });
+    }
+    /**
+     * OLD SIGNATURE: searchText(query, limit)
+     * Wraps to NEW: search({ query, limit })
+     */
+    async searchText(query, limit) {
+        console.warn('Deprecated: Use search({ query, limit }) instead');
+        return this.search({ query, limit });
+    }
+    /**
+     * OLD SIGNATURE: findSimilar(id, limit)
+     * Wraps to NEW: findSimilar({ id, limit })
+     */
+    async findSimilar(idOrParams, limit) {
+        // If called with object params (new style)
+        if (typeof idOrParams === 'object') {
+            return super.findSimilar(idOrParams);
+        }
+        // If called with positional params (old style)
+        console.warn('Deprecated: Use findSimilar({ id, limit }) instead');
+        return super.findSimilar({ id: idOrParams, limit });
+    }
+    /**
+     * OLD METHODS: getVerbsBySource, getVerbsByTarget
+     * Wraps to NEW: getVerbs({ source }) or getVerbs({ target })
+     */
+    async getVerbsBySource(sourceId) {
+        console.warn('Deprecated: Use getVerbs({ source }) instead');
+        const result = await this.getVerbs({ source: sourceId });
+        return result.items;
+    }
+    async getVerbsByTarget(targetId) {
+        console.warn('Deprecated: Use getVerbs({ target }) instead');
+        const result = await this.getVerbs({ target: targetId });
+        return result.items;
+    }
+}
+//# sourceMappingURL=brainyDataV3.js.map

package/dist/browserFramework.d.ts

@@ -3,13 +3,13 @@
  * Optimized for modern frameworks like Angular, React, Vue, etc.
  * Auto-detects environment and uses optimal storage (OPFS in browsers)
  */
-import { BrainyData, BrainyDataConfig } from './brainyData.js';
+import { Brainy, BrainyConfig } from './brainy.js';
 import { VerbType, NounType } from './types/graphTypes.js';
 /**
- * Create a BrainyData instance optimized for browser frameworks
+ * Create a Brainy instance optimized for browser frameworks
  * Auto-detects environment and selects optimal storage and settings
  */
-export declare function createBrowserBrainyData(config?: Partial<BrainyDataConfig>): Promise<BrainyData>;
-export { VerbType, NounType, BrainyData };
-export type { BrainyDataConfig };
-export default createBrowserBrainyData;
+export declare function createBrowserBrainy(config?: Partial<BrainyConfig>): Promise<Brainy>;
+export { VerbType, NounType, Brainy };
+export type { BrainyConfig };
+export default createBrowserBrainy;

package/dist/browserFramework.js

@@ -3,29 +3,32 @@
  * Optimized for modern frameworks like Angular, React, Vue, etc.
  * Auto-detects environment and uses optimal storage (OPFS in browsers)
  */
-import { BrainyData } from './brainyData.js';
+import { Brainy } from './brainy.js';
 import { VerbType, NounType } from './types/graphTypes.js';
 /**
- * Create a BrainyData instance optimized for browser frameworks
+ * Create a Brainy instance optimized for browser frameworks
  * Auto-detects environment and selects optimal storage and settings
  */
-export async function createBrowserBrainyData(config = {}) {
-    // BrainyData already has environment detection and will automatically:
+export async function createBrowserBrainy(config = {}) {
+    // Brainy already has environment detection and will automatically:
     // - Use OPFS storage in browsers with fallback to Memory
     // - Use FileSystem storage in Node.js
     // - Request persistent storage when appropriate
     const browserConfig = {
         storage: {
-            requestPersistentStorage: true // Request persistent storage for better performance
+            type: 'opfs',
+            options: {
+                requestPersistentStorage: true // Request persistent storage for better performance
+            }
         },
         ...config
     };
-    const brainyData = new BrainyData(browserConfig);
+    const brainyData = new Brainy(browserConfig);
     await brainyData.init();
     return brainyData;
 }
 // Re-export types and constants for framework use
-export { VerbType, NounType, BrainyData };
+export { VerbType, NounType, Brainy };
 // Default export for easy importing
-export default createBrowserBrainyData;
+export default createBrowserBrainy;
 //# sourceMappingURL=browserFramework.js.map

package/dist/browserFramework.minimal.d.ts

@@ -3,12 +3,12 @@
  * Core MIT open source functionality only - no enterprise features
  * Optimized for browser usage with all dependencies bundled
  */
-import { BrainyData } from './brainyData.js';
+import { Brainy } from './brainy.js';
 import { VerbType, NounType } from './types/graphTypes.js';
 /**
- * Create a BrainyData instance optimized for browser usage
+ * Create a Brainy instance optimized for browser usage
  * Auto-detects environment and selects optimal storage and settings
  */
-export declare function createBrowserBrainyData(config?: {}): Promise<BrainyData<any>>;
-export { VerbType, NounType, BrainyData };
-export default createBrowserBrainyData;
+export declare function createBrowserBrainy(config?: {}): Promise<Brainy<any>>;
+export { VerbType, NounType, Brainy };
+export default createBrowserBrainy;

package/dist/browserFramework.minimal.js

@@ -3,29 +3,32 @@
  * Core MIT open source functionality only - no enterprise features
  * Optimized for browser usage with all dependencies bundled
  */
-import { BrainyData } from './brainyData.js';
+import { Brainy } from './brainy.js';
 import { VerbType, NounType } from './types/graphTypes.js';
 /**
- * Create a BrainyData instance optimized for browser usage
+ * Create a Brainy instance optimized for browser usage
  * Auto-detects environment and selects optimal storage and settings
  */
-export async function createBrowserBrainyData(config = {}) {
-    // BrainyData already has environment detection and will automatically:
+export async function createBrowserBrainy(config = {}) {
+    // Brainy already has environment detection and will automatically:
     // - Use OPFS storage in browsers with fallback to Memory
     // - Use FileSystem storage in Node.js
     // - Request persistent storage when appropriate
     const browserConfig = {
         storage: {
-            requestPersistentStorage: true // Request persistent storage for better performance
+            type: 'opfs',
+            options: {
+                requestPersistentStorage: true
+            }
         },
         ...config
     };
-    const brainyData = new BrainyData(browserConfig);
+    const brainyData = new Brainy(browserConfig);
     await brainyData.init();
     return brainyData;
 }
 // Re-export core types and classes for browser use
-export { VerbType, NounType, BrainyData };
+export { VerbType, NounType, Brainy };
 // Default export for easy importing
-export default createBrowserBrainyData;
+export default createBrowserBrainy;
 //# sourceMappingURL=browserFramework.minimal.js.map