@soulcraft/brainy 3.0.0 → 3.1.0

package/dist/types/apiTypes.d.ts

@@ -0,0 +1,278 @@
+/**
+ * Consistent API Types for Brainy
+ *
+ * These types provide a uniform interface for all public methods,
+ * using object parameters for consistency and extensibility.
+ */
+import type { Vector } from '../coreTypes.js';
+import type { NounType, VerbType } from './graphTypes.js';
+/**
+ * Parameters for adding a noun
+ */
+export interface AddNounParams {
+    data: any | Vector;
+    type: NounType | string;
+    metadata?: any;
+    id?: string;
+    service?: string;
+}
+/**
+ * Parameters for updating a noun
+ */
+export interface UpdateNounParams {
+    id: string;
+    data?: any;
+    metadata?: any;
+    type?: NounType | string;
+}
+/**
+ * Parameters for getting nouns
+ */
+export interface GetNounsParams {
+    ids?: string[];
+    type?: NounType | string | string[];
+    limit?: number;
+    offset?: number;
+    cursor?: string;
+    filter?: Record<string, any>;
+    service?: string;
+}
+/**
+ * Parameters for adding a verb (relationship)
+ */
+export interface AddVerbParams {
+    source: string;
+    target: string;
+    type: VerbType | string;
+    weight?: number;
+    metadata?: any;
+    service?: string;
+}
+/**
+ * Parameters for getting verbs
+ */
+export interface GetVerbsParams {
+    source?: string;
+    target?: string;
+    type?: VerbType | string | string[];
+    limit?: number;
+    offset?: number;
+    cursor?: string;
+    filter?: Record<string, any>;
+    service?: string;
+}
+/**
+ * Unified search parameters
+ */
+export interface SearchParams {
+    query: string | Vector;
+    limit?: number;
+    threshold?: number;
+    filter?: {
+        type?: NounType | string | string[];
+        metadata?: Record<string, any>;
+        service?: string;
+    };
+    includeMetadata?: boolean;
+    includeVectors?: boolean;
+}
+/**
+ * Parameters for similarity search
+ */
+export interface SimilarityParams {
+    id?: string;
+    data?: any | Vector;
+    limit?: number;
+    threshold?: number;
+    filter?: {
+        type?: NounType | string | string[];
+        metadata?: Record<string, any>;
+        service?: string;
+    };
+}
+/**
+ * Parameters for related items search
+ */
+export interface RelatedParams {
+    id: string;
+    depth?: number;
+    limit?: number;
+    types?: VerbType[] | string[];
+    direction?: 'outgoing' | 'incoming' | 'both';
+}
+/**
+ * Parameters for batch noun operations
+ */
+export interface BatchNounsParams {
+    items: AddNounParams[];
+    parallel?: boolean;
+    chunkSize?: number;
+    onProgress?: (completed: number, total: number) => void;
+}
+/**
+ * Parameters for batch verb operations
+ */
+export interface BatchVerbsParams {
+    items: AddVerbParams[];
+    parallel?: boolean;
+    chunkSize?: number;
+    onProgress?: (completed: number, total: number) => void;
+}
+/**
+ * Parameters for statistics queries
+ */
+export interface StatisticsParams {
+    detailed?: boolean;
+    includeAugmentations?: boolean;
+    includeMemory?: boolean;
+    service?: string;
+}
+/**
+ * Parameters for metadata operations
+ */
+export interface MetadataParams {
+    id: string;
+    metadata: any;
+    merge?: boolean;
+}
+/**
+ * Dynamic configuration update parameters
+ */
+export interface ConfigUpdateParams {
+    embeddings?: {
+        model?: string;
+        precision?: 'q8';
+        cache?: boolean;
+    };
+    augmentations?: {
+        [name: string]: boolean | Record<string, any>;
+    };
+    storage?: {
+        type?: string;
+        config?: any;
+    };
+    performance?: {
+        batchSize?: number;
+        maxConcurrency?: number;
+        cacheSize?: number;
+    };
+}
+/**
+ * API for Triple Intelligence Engine to access Brainy internals
+ * This provides type-safe access without 'as any' casts
+ */
+export interface TripleIntelligenceAPI {
+    vectorSearch(vector: Vector | string, limit: number): Promise<Array<{
+        id: string;
+        score: number;
+        entity?: any;
+    }>>;
+    graphTraversal(options: {
+        start: string | string[];
+        type?: string | string[];
+        direction?: 'in' | 'out' | 'both';
+        maxDepth?: number;
+    }): Promise<Array<{
+        id: string;
+        score: number;
+        depth: number;
+    }>>;
+    metadataQuery(where: Record<string, any>): Promise<Set<string>>;
+    getEntity(id: string): Promise<any>;
+    getVerbsBySource(sourceId: string): Promise<any[]>;
+    getVerbsByTarget(targetId: string): Promise<any[]>;
+    getStatistics(): Promise<{
+        totalCount: number;
+        fieldStats: Record<string, {
+            min: number;
+            max: number;
+            cardinality: number;
+            type: string;
+        }>;
+    }>;
+    getAllNouns(): Map<string, any>;
+    hasMetadataIndex(): boolean;
+}
+/**
+ * Unified search result
+ */
+export interface SearchResult<T = any> {
+    id: string;
+    score: number;
+    data?: T;
+    metadata?: any;
+    vector?: Vector;
+    type?: string;
+    distance?: number;
+}
+/**
+ * Paginated result wrapper
+ */
+export interface PaginatedResult<T> {
+    items: T[];
+    total?: number;
+    hasMore: boolean;
+    nextCursor?: string;
+    previousCursor?: string;
+}
+/**
+ * Batch operation result
+ */
+export interface BatchResult {
+    successful: string[];
+    failed: Array<{
+        index: number;
+        error: string;
+        item?: any;
+    }>;
+    total: number;
+    duration: number;
+}
+/**
+ * Statistics result
+ */
+export interface StatisticsResult {
+    nouns: {
+        total: number;
+        byType: Record<string, number>;
+    };
+    verbs: {
+        total: number;
+        byType: Record<string, number>;
+    };
+    storage: {
+        used: number;
+        type: string;
+    };
+    performance?: {
+        avgLatency: number;
+        throughput: number;
+        cacheHitRate?: number;
+    };
+    augmentations?: Record<string, any>;
+    memory?: {
+        used: number;
+        limit: number;
+    };
+}
+/**
+ * Structured error for API operations
+ */
+export declare class BrainyAPIError extends Error {
+    code: string;
+    statusCode: number;
+    details?: any | undefined;
+    constructor(message: string, code: string, statusCode?: number, details?: any | undefined);
+}
+export declare const ErrorCodes: {
+    readonly INVALID_TYPE: "INVALID_TYPE";
+    readonly NOT_FOUND: "NOT_FOUND";
+    readonly DUPLICATE_ID: "DUPLICATE_ID";
+    readonly INVALID_VECTOR: "INVALID_VECTOR";
+    readonly STORAGE_ERROR: "STORAGE_ERROR";
+    readonly EMBEDDING_ERROR: "EMBEDDING_ERROR";
+    readonly AUGMENTATION_ERROR: "AUGMENTATION_ERROR";
+    readonly VALIDATION_ERROR: "VALIDATION_ERROR";
+    readonly QUOTA_EXCEEDED: "QUOTA_EXCEEDED";
+    readonly UNAUTHORIZED: "UNAUTHORIZED";
+};

package/dist/types/apiTypes.js

@@ -0,0 +1,33 @@
+/**
+ * Consistent API Types for Brainy
+ *
+ * These types provide a uniform interface for all public methods,
+ * using object parameters for consistency and extensibility.
+ */
+// ============= ERRORS =============
+/**
+ * Structured error for API operations
+ */
+export class BrainyAPIError extends Error {
+    constructor(message, code, statusCode = 400, details) {
+        super(message);
+        this.code = code;
+        this.statusCode = statusCode;
+        this.details = details;
+        this.name = 'BrainyAPIError';
+    }
+}
+// Error codes
+export const ErrorCodes = {
+    INVALID_TYPE: 'INVALID_TYPE',
+    NOT_FOUND: 'NOT_FOUND',
+    DUPLICATE_ID: 'DUPLICATE_ID',
+    INVALID_VECTOR: 'INVALID_VECTOR',
+    STORAGE_ERROR: 'STORAGE_ERROR',
+    EMBEDDING_ERROR: 'EMBEDDING_ERROR',
+    AUGMENTATION_ERROR: 'AUGMENTATION_ERROR',
+    VALIDATION_ERROR: 'VALIDATION_ERROR',
+    QUOTA_EXCEEDED: 'QUOTA_EXCEEDED',
+    UNAUTHORIZED: 'UNAUTHORIZED'
+};
+//# sourceMappingURL=apiTypes.js.map

package/dist/types/brainy.types.d.ts

@@ -0,0 +1,308 @@
+/**
+ * 🧠 Brainy 3.0 Type Definitions
+ *
+ * Beautiful, consistent, type-safe interfaces for the future of neural databases
+ */
+import { Vector } from '../coreTypes.js';
+import { NounType, VerbType } from './graphTypes.js';
+/**
+ * Entity representation (replaces GraphNoun)
+ */
+export interface Entity<T = any> {
+    id: string;
+    vector: Vector;
+    type: NounType;
+    data?: any;
+    metadata?: T;
+    service?: string;
+    createdAt: number;
+    updatedAt?: number;
+    createdBy?: string;
+}
+/**
+ * Relation representation (replaces GraphVerb)
+ */
+export interface Relation<T = any> {
+    id: string;
+    from: string;
+    to: string;
+    type: VerbType;
+    weight?: number;
+    metadata?: T;
+    service?: string;
+    createdAt: number;
+    updatedAt?: number;
+}
+/**
+ * Search result with similarity score
+ */
+export interface Result<T = any> {
+    id: string;
+    score: number;
+    entity: Entity<T>;
+    explanation?: ScoreExplanation;
+}
+/**
+ * Score explanation for transparency
+ */
+export interface ScoreExplanation {
+    vectorScore?: number;
+    metadataScore?: number;
+    graphScore?: number;
+    boosts?: Record<string, number>;
+    penalties?: Record<string, number>;
+}
+/**
+ * Parameters for adding entities
+ */
+export interface AddParams<T = any> {
+    data: any | Vector;
+    type: NounType;
+    metadata?: T;
+    id?: string;
+    vector?: Vector;
+    service?: string;
+}
+/**
+ * Parameters for updating entities
+ */
+export interface UpdateParams<T = any> {
+    id: string;
+    data?: any;
+    type?: NounType;
+    metadata?: Partial<T>;
+    merge?: boolean;
+    vector?: Vector;
+}
+/**
+ * Parameters for creating relationships
+ */
+export interface RelateParams<T = any> {
+    from: string;
+    to: string;
+    type: VerbType;
+    weight?: number;
+    metadata?: T;
+    bidirectional?: boolean;
+    service?: string;
+}
+/**
+ * Parameters for updating relationships
+ */
+export interface UpdateRelationParams<T = any> {
+    id: string;
+    weight?: number;
+    metadata?: Partial<T>;
+    merge?: boolean;
+}
+/**
+ * Unified find parameters - Triple Intelligence
+ */
+export interface FindParams<T = any> {
+    query?: string;
+    vector?: Vector;
+    type?: NounType | NounType[];
+    where?: Partial<T>;
+    connected?: GraphConstraints;
+    near?: {
+        id: string;
+        threshold?: number;
+    };
+    limit?: number;
+    offset?: number;
+    cursor?: string;
+    mode?: SearchMode;
+    explain?: boolean;
+    includeRelations?: boolean;
+    service?: string;
+    fusion?: {
+        strategy?: 'adaptive' | 'weighted' | 'progressive';
+        weights?: {
+            vector?: number;
+            graph?: number;
+            field?: number;
+        };
+    };
+    writeOnly?: boolean;
+}
+/**
+ * Graph constraints for search
+ */
+export interface GraphConstraints {
+    to?: string;
+    from?: string;
+    via?: VerbType | VerbType[];
+    type?: VerbType | VerbType[];
+    depth?: number;
+    direction?: 'in' | 'out' | 'both';
+    bidirectional?: boolean;
+}
+/**
+ * Search modes
+ */
+export type SearchMode = 'auto' | 'vector' | 'metadata' | 'graph' | 'hybrid';
+/**
+ * Parameters for similarity search
+ */
+export interface SimilarParams<T = any> {
+    to: string | Entity<T> | Vector;
+    limit?: number;
+    threshold?: number;
+    type?: NounType | NounType[];
+    where?: Partial<T>;
+    service?: string;
+}
+/**
+ * Parameters for getting relationships
+ */
+export interface GetRelationsParams {
+    from?: string;
+    to?: string;
+    type?: VerbType | VerbType[];
+    limit?: number;
+    offset?: number;
+    cursor?: string;
+    service?: string;
+}
+/**
+ * Batch add parameters
+ */
+export interface AddManyParams<T = any> {
+    items: AddParams<T>[];
+    parallel?: boolean;
+    chunkSize?: number;
+    onProgress?: (done: number, total: number) => void;
+    continueOnError?: boolean;
+}
+/**
+ * Batch update parameters
+ */
+export interface UpdateManyParams<T = any> {
+    items: UpdateParams<T>[];
+    parallel?: boolean;
+    chunkSize?: number;
+    onProgress?: (done: number, total: number) => void;
+    continueOnError?: boolean;
+}
+/**
+ * Batch delete parameters
+ */
+export interface DeleteManyParams {
+    ids?: string[];
+    type?: NounType;
+    where?: any;
+    limit?: number;
+    onProgress?: (done: number, total: number) => void;
+}
+/**
+ * Batch relate parameters
+ */
+export interface RelateManyParams<T = any> {
+    items: RelateParams<T>[];
+    parallel?: boolean;
+    chunkSize?: number;
+    onProgress?: (done: number, total: number) => void;
+    continueOnError?: boolean;
+}
+/**
+ * Batch result
+ */
+export interface BatchResult<T = any> {
+    successful: T[];
+    failed: Array<{
+        item: any;
+        error: string;
+    }>;
+    total: number;
+    duration: number;
+}
+/**
+ * Graph traversal parameters
+ */
+export interface TraverseParams {
+    from: string | string[];
+    direction?: 'out' | 'in' | 'both';
+    types?: VerbType[];
+    depth?: number;
+    strategy?: 'bfs' | 'dfs';
+    filter?: (entity: Entity, depth: number, path: string[]) => boolean;
+    limit?: number;
+}
+/**
+ * Aggregation parameters
+ */
+export interface AggregateParams<T = any> {
+    query?: FindParams<T>;
+    groupBy: string | string[];
+    metrics: AggregateMetric[];
+    having?: any;
+    orderBy?: string;
+    limit?: number;
+}
+/**
+ * Aggregate metrics
+ */
+export type AggregateMetric = 'count' | 'sum' | 'avg' | 'min' | 'max' | 'stddev' | {
+    custom: string;
+    field: string;
+};
+/**
+ * Brainy configuration
+ */
+export interface BrainyConfig {
+    storage?: {
+        type: 'memory' | 'filesystem' | 's3' | 'r2' | 'opfs';
+        options?: any;
+    };
+    model?: {
+        type: 'fast' | 'accurate' | 'balanced' | 'custom';
+        name?: string;
+        precision?: 'q8';
+    };
+    index?: {
+        m?: number;
+        efConstruction?: number;
+        efSearch?: number;
+    };
+    cache?: boolean | {
+        maxSize?: number;
+        ttl?: number;
+    };
+    augmentations?: Record<string, any>;
+    warmup?: boolean;
+    realtime?: boolean;
+    multiTenancy?: boolean;
+    telemetry?: boolean;
+}
+/**
+ * Neural similarity parameters
+ */
+export interface NeuralSimilarityParams {
+    between?: [any, any];
+    items?: any[];
+    explain?: boolean;
+}
+/**
+ * Neural clustering parameters
+ */
+export interface NeuralClusterParams {
+    items?: string[] | Entity[];
+    algorithm?: 'hierarchical' | 'kmeans' | 'dbscan' | 'spectral';
+    params?: {
+        k?: number;
+        threshold?: number;
+        epsilon?: number;
+        minPoints?: number;
+    };
+    visualize?: boolean;
+}
+/**
+ * Neural anomaly detection parameters
+ */
+export interface NeuralAnomalyParams {
+    threshold?: number;
+    type?: NounType;
+    method?: 'isolation' | 'lof' | 'statistical' | 'autoencoder';
+    returnScores?: boolean;
+}
+export * from './graphTypes.js';

package/dist/types/brainy.types.js

@@ -0,0 +1,8 @@
+/**
+ * 🧠 Brainy 3.0 Type Definitions
+ *
+ * Beautiful, consistent, type-safe interfaces for the future of neural databases
+ */
+// ============= Export all types =============
+export * from './graphTypes.js'; // Re-export NounType, VerbType, etc.
+//# sourceMappingURL=brainy.types.js.map

package/dist/types/brainyDataInterface.d.ts

@@ -1,11 +1,11 @@
 /**
- * BrainyDataInterface
+ * BrainyInterface
  *
- * This interface defines the methods from BrainyData that are used by serverSearchAugmentations.ts.
+ * This interface defines the methods from Brainy that are used by serverSearchAugmentations.ts.
  * It's used to break the circular dependency between brainyData.ts and serverSearchAugmentations.ts.
  */
 import { Vector } from '../coreTypes.js';
-export interface BrainyDataInterface<T = unknown> {
+export interface BrainyInterface<T = unknown> {
     /**
      * Initialize the database
      */
@@ -18,14 +18,11 @@ export interface BrainyDataInterface<T = unknown> {
     /**
      * Add a noun (entity with vector and metadata) to the database
      * @param data Text string or vector representation (will auto-embed strings)
+     * @param nounType Required noun type (one of 31 types)
      * @param metadata Optional metadata to associate with the noun
-     * @param options Optional configuration including custom ID
      * @returns The ID of the added noun
      */
-    addNoun(data: string | Vector, metadata?: T, options?: {
-        id?: string;
-        [key: string]: any;
-    }): Promise<string>;
+    addNoun(data: string | Vector, nounType: string, metadata?: T): Promise<string>;
     /**
      * Search for text in the database
      * @param text The text to search for

package/dist/types/brainyDataInterface.js

@@ -1,7 +1,7 @@
 /**
- * BrainyDataInterface
+ * BrainyInterface
  *
- * This interface defines the methods from BrainyData that are used by serverSearchAugmentations.ts.
+ * This interface defines the methods from Brainy that are used by serverSearchAugmentations.ts.
  * It's used to break the circular dependency between brainyData.ts and serverSearchAugmentations.ts.
  */
 export {};

package/dist/types/graphTypes.js

@@ -169,7 +169,7 @@ export const NounType = {
     Person: 'person', // Human entities
     Organization: 'organization', // Formal organizations (companies, institutions, etc.)
     Location: 'location', // Geographic locations (merges previous Place and Location)
-    Thing: 'thing', // Physical objects
+    Thing: 'thing', // Physical objects (generic items/entities should use this)
     Concept: 'concept', // Abstract ideas, concepts, and intangible entities
     Event: 'event', // Occurrences with time and place
     // Digital/Content Types
@@ -181,7 +181,7 @@ export const NounType = {
     // Collection Types
     Collection: 'collection', // Generic grouping of items (merges Group, List, and Category)
     Dataset: 'dataset', // Structured collections of data
-    // Business/Application Types
+    // Business/Application Types  
     Product: 'product', // Commercial products and offerings
     Service: 'service', // Services and offerings
     User: 'user', // User accounts and profiles