@soulcraft/brainy 3.1.1 → 3.2.0

package/dist/augmentations/metricsAugmentation.d.ts

@@ -1,11 +1,19 @@
 /**
  * Metrics Augmentation - Optional Performance & Usage Metrics
  *
- * Replaces the hardcoded StatisticsCollector in Brainy with an optional augmentation.
- * Tracks performance metrics, usage patterns, and system statistics.
+ * IMPORTANT: This is SEPARATE from core counting (brain.counts.*) which is always enabled.
+ *
+ * Core counting provides O(1) entity/relationship counts for scalability.
+ * This augmentation provides performance analytics and observability.
+ *
+ * Features:
+ * - Search performance tracking (latency, throughput)
+ * - Cache hit/miss rates
+ * - Operation timing analysis
+ * - Usage pattern insights
  *
  * Zero-config: Automatically enabled for observability
- * Can be disabled or customized via augmentation registry
+ * Can be disabled via augmentation registry without affecting core performance
  */
 import { BaseAugmentation } from './brainyAugmentation.js';
 export interface MetricsConfig {
@@ -71,10 +79,16 @@ export declare class MetricsAugmentation extends BaseAugmentation {
      */
     private persistMetrics;
     /**
-     * Get current metrics
+     * Get current metrics (performance analytics only)
+     *
+     * NOTE: For production counting (entities, relationships), use:
+     * - brain.counts.entities() - O(1) total count
+     * - brain.counts.byType() - O(1) type-specific counts
+     * - brain.counts.relationships() - O(1) relationship counts
      */
     getStatistics(): {
         enabled: boolean;
+        note: string;
         totalSearches: number;
         totalUpdates: number;
         contentTypes: {};
@@ -166,6 +180,7 @@ export declare class MetricsAugmentation extends BaseAugmentation {
         lastUpdated?: string | undefined;
         distributedConfig?: import("../types/distributedTypes.js").SharedConfig | undefined;
         enabled: boolean;
+        note: string;
         totalSearches?: undefined;
         totalUpdates?: undefined;
         verbTypes?: undefined;

package/dist/augmentations/metricsAugmentation.js

@@ -1,11 +1,19 @@
 /**
  * Metrics Augmentation - Optional Performance & Usage Metrics
  *
- * Replaces the hardcoded StatisticsCollector in Brainy with an optional augmentation.
- * Tracks performance metrics, usage patterns, and system statistics.
+ * IMPORTANT: This is SEPARATE from core counting (brain.counts.*) which is always enabled.
+ *
+ * Core counting provides O(1) entity/relationship counts for scalability.
+ * This augmentation provides performance analytics and observability.
+ *
+ * Features:
+ * - Search performance tracking (latency, throughput)
+ * - Cache hit/miss rates
+ * - Operation timing analysis
+ * - Usage pattern insights
  *
  * Zero-config: Automatically enabled for observability
- * Can be disabled or customized via augmentation registry
+ * Can be disabled via augmentation registry without affecting core performance
  */
 import { BaseAugmentation } from './brainyAugmentation.js';
 import { StatisticsCollector } from '../utils/statisticsCollector.js';
@@ -224,12 +232,18 @@ export class MetricsAugmentation extends BaseAugmentation {
         }
     }
     /**
-     * Get current metrics
+     * Get current metrics (performance analytics only)
+     *
+     * NOTE: For production counting (entities, relationships), use:
+     * - brain.counts.entities() - O(1) total count
+     * - brain.counts.byType() - O(1) type-specific counts
+     * - brain.counts.relationships() - O(1) relationship counts
      */
     getStatistics() {
         if (!this.statisticsCollector) {
             return {
                 enabled: false,
+                note: 'For core counting, use brain.counts.* APIs which are always available',
                 totalSearches: 0,
                 totalUpdates: 0,
                 contentTypes: {},
@@ -243,6 +257,7 @@ export class MetricsAugmentation extends BaseAugmentation {
         }
         return {
             enabled: true,
+            note: 'Performance analytics only. Core counting available via brain.counts.*',
             ...this.statisticsCollector.getStatistics()
         };
     }

package/dist/brainy.d.ts

@@ -195,6 +195,82 @@ export declare class Brainy<T = any> {
         services: string[];
         density: number;
     }>;
+    /**
+     * Efficient Pagination API - Production-scale pagination using index-first approach
+     * Automatically optimizes based on query type and applies pagination at the index level
+     */
+    get pagination(): {
+        find: (params: FindParams<T> & {
+            page?: number;
+            pageSize?: number;
+        }) => Promise<Result<T>[]>;
+        count: (params: Omit<FindParams<T>, "limit" | "offset">) => Promise<number>;
+        meta: (params: FindParams<T> & {
+            page?: number;
+            pageSize?: number;
+        }) => Promise<{
+            page: number;
+            pageSize: number;
+            totalCount: number;
+            totalPages: number;
+            hasNext: boolean;
+            hasPrev: boolean;
+        }>;
+    };
+    /**
+     * Streaming API - Process millions of entities with constant memory using existing Pipeline
+     * Integrates with index-based optimizations for maximum efficiency
+     */
+    get streaming(): {
+        entities: (filter?: Partial<FindParams<T>>) => AsyncGenerator<Entity<T>>;
+        search: (params: FindParams<T>, batchSize?: number) => AsyncGenerator<{
+            id: string;
+            score: number;
+            entity: Entity<T>;
+        }>;
+        relationships: (filter?: {
+            type?: string;
+            sourceId?: string;
+            targetId?: string;
+        }) => AsyncGenerator<any>;
+        pipeline: (source: AsyncIterable<any>) => any;
+        process: (processor: (entity: Entity<T>) => Promise<Entity<T>>, filter?: Partial<FindParams<T>>, options?: {
+            batchSize: number;
+            parallel: number;
+        }) => Promise<void>;
+    };
+    /**
+     * O(1) Count API - Production-scale counting using existing indexes
+     * Works across all storage adapters (FileSystem, OPFS, S3, Memory)
+     */
+    get counts(): {
+        entities: () => number;
+        relationships: () => number;
+        byType: (type?: string) => number | {
+            [k: string]: number;
+        };
+        byRelationshipType: (type?: string) => number | {
+            [k: string]: number;
+        };
+        byCriteria: (field: string, value: any) => Promise<number>;
+        getAllTypeCounts: () => Map<string, number>;
+        getStats: () => {
+            entities: {
+                total: number;
+                byType: {
+                    [k: string]: number;
+                };
+            };
+            relationships: {
+                totalRelationships: number;
+                relationshipsByType: Record<string, number>;
+                uniqueSourceNodes: number;
+                uniqueTargetNodes: number;
+                totalNodes: number;
+            };
+            density: number;
+        };
+    };
     /**
      * Augmentations API - Clean and simple
      */

package/dist/brainy.js

@@ -16,6 +16,7 @@ import { NaturalLanguageProcessor } from './neural/naturalLanguageProcessor.js';
 import { TripleIntelligenceSystem } from './triple/TripleIntelligenceSystem.js';
 import { MetadataIndexManager } from './utils/metadataIndex.js';
 import { GraphAdjacencyIndex } from './graph/graphAdjacencyIndex.js';
+import { createPipeline } from './streaming/pipeline.js';
 import { configureLogger, LogLevel } from './utils/logger.js';
 import { NounType } from './types/graphTypes.js';
 /**
@@ -468,22 +469,51 @@ export class Brainy {
                 const filteredIds = await this.metadataIndex.getIdsForFilter(filter);
                 // CRITICAL FIX: Handle both cases properly
                 if (results.length > 0) {
-                    // Filter existing results (from vector search)
+                    // OPTIMIZED: Filter existing results (from vector search) efficiently
                     const filteredIdSet = new Set(filteredIds);
                     results = results.filter((r) => filteredIdSet.has(r.id));
+                    // Apply early pagination for vector + metadata queries
+                    const limit = params.limit || 10;
+                    const offset = params.offset || 0;
+                    // If we have enough filtered results, sort and paginate early
+                    if (results.length >= offset + limit) {
+                        results.sort((a, b) => b.score - a.score);
+                        results = results.slice(offset, offset + limit);
+                        // Load entities only for the paginated results
+                        for (const result of results) {
+                            if (!result.entity) {
+                                const entity = await this.get(result.id);
+                                if (entity) {
+                                    result.entity = entity;
+                                }
+                            }
+                        }
+                        // Early return if no other processing needed
+                        if (!params.connected && !params.fusion) {
+                            return results;
+                        }
+                    }
                 }
                 else {
-                    // Create results from metadata matches (metadata-only query)
-                    for (const id of filteredIds) {
+                    // OPTIMIZED: Apply pagination to filtered IDs BEFORE loading entities
+                    const limit = params.limit || 10;
+                    const offset = params.offset || 0;
+                    const pageIds = filteredIds.slice(offset, offset + limit);
+                    // Load only entities for current page - O(page_size) instead of O(total_results)
+                    for (const id of pageIds) {
                         const entity = await this.get(id);
                         if (entity) {
                             results.push({
                                 id,
                                 score: 1.0, // All metadata matches are equally relevant
-                                entity
+                                entity: entity
                             });
                         }
                     }
+                    // Early return for metadata-only queries with pagination applied
+                    if (!params.query && !params.connected) {
+                        return results;
+                    }
                 }
             }
             // Graph search component with O(1) traversal
@@ -494,10 +524,11 @@ export class Brainy {
             if (params.fusion && results.length > 0) {
                 results = this.applyFusionScoring(results, params.fusion);
             }
-            // Sort by score and apply pagination
+            // OPTIMIZED: Sort first, then apply efficient pagination
             results.sort((a, b) => b.score - a.score);
             const limit = params.limit || 10;
             const offset = params.offset || 0;
+            // Efficient pagination - only slice what we need
             return results.slice(offset, offset + limit);
         });
         // Record performance for auto-tuning
@@ -863,24 +894,16 @@ export class Brainy {
      */
     async insights() {
         await this.ensureInitialized();
-        // Get all entities count - use getNouns with high limit
-        const entitiesResult = await this.storage.getNouns({
-            pagination: { limit: 10000 }
-        });
-        const entities = entitiesResult.totalCount || entitiesResult.items.length;
-        // Get relationships count - use getVerbs with high limit
-        const verbsResult = await this.storage.getVerbs({
-            pagination: { limit: 10000 }
-        });
-        const relationships = verbsResult.totalCount || verbsResult.items.length;
-        // Count by type
-        const types = {};
-        for (const entity of entitiesResult.items) {
-            const type = entity.metadata?.noun || 'unknown';
-            types[type] = (types[type] || 0) + 1;
-        }
-        // Get unique services
-        const services = [...new Set(entitiesResult.items.map((e) => e.metadata?.service).filter(Boolean))];
+        // O(1) entity counting using existing MetadataIndexManager
+        const entities = this.metadataIndex.getTotalEntityCount();
+        // O(1) count by type using existing index tracking
+        const typeCountsMap = this.metadataIndex.getAllEntityCounts();
+        const types = Object.fromEntries(typeCountsMap);
+        // O(1) relationships count using GraphAdjacencyIndex
+        const relationships = this.graphIndex.getTotalRelationshipCount();
+        // Get unique services - O(log n) using index
+        const serviceValues = await this.metadataIndex.getFilterValues('service');
+        const services = serviceValues.filter(Boolean);
         // Calculate density (relationships per entity)
         const density = entities > 0 ? relationships / entities : 0;
         return {
@@ -891,6 +914,229 @@ export class Brainy {
             density
         };
     }
+    /**
+     * Efficient Pagination API - Production-scale pagination using index-first approach
+     * Automatically optimizes based on query type and applies pagination at the index level
+     */
+    get pagination() {
+        return {
+            // Get paginated results with automatic optimization
+            find: async (params) => {
+                const page = params.page || 1;
+                const pageSize = params.pageSize || 10;
+                const offset = (page - 1) * pageSize;
+                return this.find({
+                    ...params,
+                    limit: pageSize,
+                    offset
+                });
+            },
+            // Get total count for pagination UI (O(1) when possible)
+            count: async (params) => {
+                // For simple type queries, use O(1) index counting
+                if (params.type && !params.query && !params.where && !params.connected) {
+                    const types = Array.isArray(params.type) ? params.type : [params.type];
+                    return types.reduce((sum, type) => sum + this.metadataIndex.getEntityCountByType(type), 0);
+                }
+                // For complex queries, use metadata index for efficient counting
+                if (params.where || params.service) {
+                    let filter = {};
+                    if (params.where)
+                        Object.assign(filter, params.where);
+                    if (params.service)
+                        filter.service = params.service;
+                    if (params.type) {
+                        const types = Array.isArray(params.type) ? params.type : [params.type];
+                        if (types.length === 1) {
+                            filter.noun = types[0];
+                        }
+                        else {
+                            const baseFilter = { ...filter };
+                            filter = {
+                                anyOf: types.map(type => ({ noun: type, ...baseFilter }))
+                            };
+                        }
+                    }
+                    const filteredIds = await this.metadataIndex.getIdsForFilter(filter);
+                    return filteredIds.length;
+                }
+                // Fallback: total entity count
+                return this.metadataIndex.getTotalEntityCount();
+            },
+            // Get pagination metadata
+            meta: async (params) => {
+                const page = params.page || 1;
+                const pageSize = params.pageSize || 10;
+                const totalCount = await this.pagination.count(params);
+                const totalPages = Math.ceil(totalCount / pageSize);
+                return {
+                    page,
+                    pageSize,
+                    totalCount,
+                    totalPages,
+                    hasNext: page < totalPages,
+                    hasPrev: page > 1
+                };
+            }
+        };
+    }
+    /**
+     * Streaming API - Process millions of entities with constant memory using existing Pipeline
+     * Integrates with index-based optimizations for maximum efficiency
+     */
+    get streaming() {
+        return {
+            // Stream all entities with optional filtering
+            entities: async function* (filter) {
+                if (filter?.type || filter?.where || filter?.service) {
+                    // Use MetadataIndexManager for efficient filtered streaming
+                    let filterObj = {};
+                    if (filter.where)
+                        Object.assign(filterObj, filter.where);
+                    if (filter.service)
+                        filterObj.service = filter.service;
+                    if (filter.type) {
+                        const types = Array.isArray(filter.type) ? filter.type : [filter.type];
+                        if (types.length === 1) {
+                            filterObj.noun = types[0];
+                        }
+                        else {
+                            const baseFilterObj = { ...filterObj };
+                            filterObj = {
+                                anyOf: types.map(type => ({ noun: type, ...baseFilterObj }))
+                            };
+                        }
+                    }
+                    const filteredIds = await this.metadataIndex.getIdsForFilter(filterObj);
+                    // Stream filtered entities in batches for memory efficiency
+                    const batchSize = 100;
+                    for (let i = 0; i < filteredIds.length; i += batchSize) {
+                        const batchIds = filteredIds.slice(i, i + batchSize);
+                        for (const id of batchIds) {
+                            const entity = await this.get(id);
+                            if (entity)
+                                yield entity;
+                        }
+                    }
+                }
+                else {
+                    // Stream all entities using storage adapter pagination
+                    let offset = 0;
+                    const batchSize = 100;
+                    let hasMore = true;
+                    while (hasMore) {
+                        const result = await this.storage.getNouns({
+                            pagination: { offset, limit: batchSize }
+                        });
+                        for (const noun of result.items) {
+                            // Convert HNSWNoun to Entity<T>
+                            yield noun;
+                        }
+                        hasMore = result.hasMore;
+                        offset += batchSize;
+                    }
+                }
+            }.bind(this),
+            // Stream search results efficiently
+            search: async function* (params, batchSize = 50) {
+                const originalLimit = params.limit;
+                let offset = 0;
+                let hasMore = true;
+                while (hasMore) {
+                    const batchResults = await this.find({
+                        ...params,
+                        limit: batchSize,
+                        offset
+                    });
+                    for (const result of batchResults) {
+                        yield result;
+                    }
+                    hasMore = batchResults.length === batchSize;
+                    offset += batchSize;
+                    // Respect original limit if specified
+                    if (originalLimit && offset >= originalLimit) {
+                        break;
+                    }
+                }
+            }.bind(this),
+            // Stream relationships efficiently
+            relationships: async function* (filter) {
+                let offset = 0;
+                const batchSize = 100;
+                let hasMore = true;
+                while (hasMore) {
+                    const result = await this.storage.getVerbs({
+                        pagination: { offset, limit: batchSize },
+                        filter
+                    });
+                    for (const verb of result.items) {
+                        yield verb;
+                    }
+                    hasMore = result.hasMore;
+                    offset += batchSize;
+                }
+            }.bind(this),
+            // Create processing pipeline from stream
+            pipeline: (source) => {
+                return createPipeline(this).source(source);
+            },
+            // Batch process entities with Pipeline system
+            process: async function (processor, filter, options = { batchSize: 50, parallel: 4 }) {
+                return createPipeline(this)
+                    .source(this.streaming.entities(filter))
+                    .batch(options.batchSize)
+                    .parallelSink(async (batch) => {
+                    await Promise.all(batch.map(processor));
+                }, options.parallel)
+                    .run();
+            }.bind(this)
+        };
+    }
+    /**
+     * O(1) Count API - Production-scale counting using existing indexes
+     * Works across all storage adapters (FileSystem, OPFS, S3, Memory)
+     */
+    get counts() {
+        return {
+            // O(1) total entity count
+            entities: () => this.metadataIndex.getTotalEntityCount(),
+            // O(1) total relationship count
+            relationships: () => this.graphIndex.getTotalRelationshipCount(),
+            // O(1) count by type
+            byType: (type) => {
+                if (type) {
+                    return this.metadataIndex.getEntityCountByType(type);
+                }
+                return Object.fromEntries(this.metadataIndex.getAllEntityCounts());
+            },
+            // O(1) count by relationship type
+            byRelationshipType: (type) => {
+                if (type) {
+                    return this.graphIndex.getRelationshipCountByType(type);
+                }
+                return Object.fromEntries(this.graphIndex.getAllRelationshipCounts());
+            },
+            // O(1) count by field-value criteria
+            byCriteria: async (field, value) => {
+                return this.metadataIndex.getCountForCriteria(field, value);
+            },
+            // Get all type counts as Map for performance-critical operations
+            getAllTypeCounts: () => this.metadataIndex.getAllEntityCounts(),
+            // Get complete statistics
+            getStats: () => {
+                const entityStats = {
+                    total: this.metadataIndex.getTotalEntityCount(),
+                    byType: Object.fromEntries(this.metadataIndex.getAllEntityCounts())
+                };
+                const relationshipStats = this.graphIndex.getRelationshipStats();
+                return {
+                    entities: entityStats,
+                    relationships: relationshipStats,
+                    density: entityStats.total > 0 ? relationshipStats.totalRelationships / entityStats.total : 0
+                };
+            }
+        };
+    }
     /**
      * Augmentations API - Clean and simple
      */

package/dist/graph/graphAdjacencyIndex.d.ts

@@ -42,6 +42,7 @@ export declare class GraphAdjacencyIndex {
     private flushTimer?;
     private rebuildStartTime;
     private totalRelationshipsIndexed;
+    private relationshipCountsByType;
     constructor(storage: StorageAdapter, config?: GraphIndexConfig);
     /**
      * Core API - O(1) neighbor lookup
@@ -49,9 +50,31 @@ export declare class GraphAdjacencyIndex {
      */
     getNeighbors(id: string, direction?: 'in' | 'out' | 'both'): Promise<string[]>;
     /**
-     * Get relationship count
+     * Get total relationship count - O(1) operation
      */
     size(): number;
+    /**
+     * Get relationship count by type - O(1) operation using existing tracking
+     */
+    getRelationshipCountByType(type: string): number;
+    /**
+     * Get total relationship count - O(1) operation
+     */
+    getTotalRelationshipCount(): number;
+    /**
+     * Get all relationship types and their counts - O(1) operation
+     */
+    getAllRelationshipCounts(): Map<string, number>;
+    /**
+     * Get relationship statistics with enhanced counting information
+     */
+    getRelationshipStats(): {
+        totalRelationships: number;
+        relationshipsByType: Record<string, number>;
+        uniqueSourceNodes: number;
+        uniqueTargetNodes: number;
+        totalNodes: number;
+    };
     /**
      * Add relationship to index - O(1) amortized
      */

package/dist/graph/graphAdjacencyIndex.js

@@ -28,6 +28,8 @@ export class GraphAdjacencyIndex {
         this.isRebuilding = false;
         this.rebuildStartTime = 0;
         this.totalRelationshipsIndexed = 0;
+        // Production-scale relationship counting by type
+        this.relationshipCountsByType = new Map();
         this.storage = storage;
         this.config = {
             maxIndexSize: config.maxIndexSize ?? 100000,
@@ -70,11 +72,50 @@ export class GraphAdjacencyIndex {
         return result;
     }
     /**
-     * Get relationship count
+     * Get total relationship count - O(1) operation
      */
     size() {
         return this.verbIndex.size;
     }
+    /**
+     * Get relationship count by type - O(1) operation using existing tracking
+     */
+    getRelationshipCountByType(type) {
+        return this.relationshipCountsByType.get(type) || 0;
+    }
+    /**
+     * Get total relationship count - O(1) operation
+     */
+    getTotalRelationshipCount() {
+        return this.verbIndex.size;
+    }
+    /**
+     * Get all relationship types and their counts - O(1) operation
+     */
+    getAllRelationshipCounts() {
+        return new Map(this.relationshipCountsByType);
+    }
+    /**
+     * Get relationship statistics with enhanced counting information
+     */
+    getRelationshipStats() {
+        const totalRelationships = this.verbIndex.size;
+        const relationshipsByType = Object.fromEntries(this.relationshipCountsByType);
+        const uniqueSourceNodes = this.sourceIndex.size;
+        const uniqueTargetNodes = this.targetIndex.size;
+        // Calculate total unique nodes (source ∪ target)
+        const allNodes = new Set();
+        this.sourceIndex.keys().forEach(id => allNodes.add(id));
+        this.targetIndex.keys().forEach(id => allNodes.add(id));
+        const totalNodes = allNodes.size;
+        return {
+            totalRelationships,
+            relationshipsByType,
+            uniqueSourceNodes,
+            uniqueTargetNodes,
+            totalNodes
+        };
+    }
     /**
      * Add relationship to index - O(1) amortized
      */
@@ -98,6 +139,9 @@ export class GraphAdjacencyIndex {
         // Cache immediately for hot data
         await this.cacheIndexEntry(verb.sourceId, 'source');
         await this.cacheIndexEntry(verb.targetId, 'target');
+        // Update type-specific counts atomically
+        const verbType = verb.type || 'unknown';
+        this.relationshipCountsByType.set(verbType, (this.relationshipCountsByType.get(verbType) || 0) + 1);
         const elapsed = performance.now() - startTime;
         this.totalRelationshipsIndexed++;
         // Performance assertion
@@ -115,6 +159,15 @@ export class GraphAdjacencyIndex {
         const startTime = performance.now();
         // Remove from verb cache
         this.verbIndex.delete(verbId);
+        // Update type-specific counts atomically
+        const verbType = verb.type || 'unknown';
+        const currentCount = this.relationshipCountsByType.get(verbType) || 0;
+        if (currentCount > 1) {
+            this.relationshipCountsByType.set(verbType, currentCount - 1);
+        }
+        else {
+            this.relationshipCountsByType.delete(verbType);
+        }
         // Remove from source index
         const sourceNeighbors = this.sourceIndex.get(verb.sourceId);
         if (sourceNeighbors) {

package/dist/utils/metadataIndex.d.ts

@@ -224,7 +224,24 @@ export declare class MetadataIndexManager {
      */
     private loadSortedIndex;
     /**
-     * Get index statistics
+     * Get count of entities by type - O(1) operation using existing tracking
+     * This exposes the production-ready counting that's already maintained
+     */
+    getEntityCountByType(type: string): number;
+    /**
+     * Get total count of all entities - O(1) operation
+     */
+    getTotalEntityCount(): number;
+    /**
+     * Get all entity types and their counts - O(1) operation
+     */
+    getAllEntityCounts(): Map<string, number>;
+    /**
+     * Get count of entities matching field-value criteria - O(1) lookup from existing indexes
+     */
+    getCountForCriteria(field: string, value: any): Promise<number>;
+    /**
+     * Get index statistics with enhanced counting information
      */
     getStats(): Promise<MetadataIndexStats>;
     /**

package/dist/utils/metadataIndex.js

@@ -1209,7 +1209,45 @@ export class MetadataIndexManager {
         return cached;
     }
     /**
-     * Get index statistics
+     * Get count of entities by type - O(1) operation using existing tracking
+     * This exposes the production-ready counting that's already maintained
+     */
+    getEntityCountByType(type) {
+        return this.totalEntitiesByType.get(type) || 0;
+    }
+    /**
+     * Get total count of all entities - O(1) operation
+     */
+    getTotalEntityCount() {
+        let total = 0;
+        for (const count of this.totalEntitiesByType.values()) {
+            total += count;
+        }
+        return total;
+    }
+    /**
+     * Get all entity types and their counts - O(1) operation
+     */
+    getAllEntityCounts() {
+        return new Map(this.totalEntitiesByType);
+    }
+    /**
+     * Get count of entities matching field-value criteria - O(1) lookup from existing indexes
+     */
+    async getCountForCriteria(field, value) {
+        const key = this.getIndexKey(field, value);
+        let entry = this.indexCache.get(key);
+        if (!entry) {
+            const loadedEntry = await this.loadIndexEntry(key);
+            if (loadedEntry) {
+                entry = loadedEntry;
+                this.indexCache.set(key, entry);
+            }
+        }
+        return entry ? entry.ids.size : 0;
+    }
+    /**
+     * Get index statistics with enhanced counting information
      */
     async getStats() {
         const fields = new Set();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soulcraft/brainy",
-  "version": "3.1.1",
+  "version": "3.2.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",