@soulcraft/brainy 3.20.2 → 3.20.3

package/dist/augmentations/memoryAugmentations.d.ts

@@ -1,72 +0,0 @@
-import { AugmentationType, IMemoryAugmentation, AugmentationResponse } from '../types/augmentations.js';
-import { StorageAdapter } from '../coreTypes.js';
-/**
- * Base class for memory augmentations that wrap a StorageAdapter
- */
-declare abstract class BaseMemoryAugmentation implements IMemoryAugmentation {
-    readonly name: string;
-    readonly description: string;
-    enabled: boolean;
-    protected storage: StorageAdapter;
-    protected isInitialized: boolean;
-    constructor(name: string, storage: StorageAdapter);
-    initialize(): Promise<void>;
-    shutDown(): Promise<void>;
-    getStatus(): Promise<'active' | 'inactive' | 'error'>;
-    storeData(key: string, data: unknown, options?: Record<string, unknown>): Promise<AugmentationResponse<boolean>>;
-    retrieveData(key: string, options?: Record<string, unknown>): Promise<AugmentationResponse<unknown>>;
-    updateData(key: string, data: unknown, options?: Record<string, unknown>): Promise<AugmentationResponse<boolean>>;
-    deleteData(key: string, options?: Record<string, unknown>): Promise<AugmentationResponse<boolean>>;
-    listDataKeys(pattern?: string, options?: Record<string, unknown>): Promise<AugmentationResponse<string[]>>;
-    /**
-     * Searches for data in the storage using vector similarity.
-     * Implements the findNearest functionality by calculating distances client-side.
-     * @param query The query vector or data to search for
-     * @param k Number of results to return (default: 10)
-     * @param options Optional search options
-     */
-    search(query: unknown, k?: number, options?: Record<string, unknown>): Promise<AugmentationResponse<Array<{
-        id: string;
-        score: number;
-        data: unknown;
-    }>>>;
-    protected ensureInitialized(): Promise<void>;
-}
-/**
- * Memory augmentation that uses in-memory storage
- */
-export declare class MemoryStorageAugmentation extends BaseMemoryAugmentation {
-    readonly description = "Memory augmentation that stores data in memory";
-    enabled: boolean;
-    constructor(name: string);
-    getType(): AugmentationType;
-}
-/**
- * Memory augmentation that uses file system storage
- */
-export declare class FileSystemStorageAugmentation extends BaseMemoryAugmentation {
-    readonly description = "Memory augmentation that stores data in the file system";
-    enabled: boolean;
-    private rootDirectory;
-    constructor(name: string, rootDirectory?: string);
-    initialize(): Promise<void>;
-    getType(): AugmentationType;
-}
-/**
- * Memory augmentation that uses OPFS (Origin Private File System) storage
- */
-export declare class OPFSStorageAugmentation extends BaseMemoryAugmentation {
-    readonly description = "Memory augmentation that stores data in the Origin Private File System";
-    enabled: boolean;
-    constructor(name: string);
-    getType(): AugmentationType;
-}
-/**
- * Factory function to create the appropriate memory augmentation based on the environment
- */
-export declare function createMemoryAugmentation(name: string, options?: {
-    storageType?: 'memory' | 'filesystem' | 'opfs';
-    rootDirectory?: string;
-    requestPersistentStorage?: boolean;
-}): Promise<IMemoryAugmentation>;
-export {};

package/dist/augmentations/memoryAugmentations.js

@@ -1,280 +0,0 @@
-import { AugmentationType } from '../types/augmentations.js';
-import { MemoryStorage, OPFSStorage } from '../storage/storageFactory.js';
-// FileSystemStorage will be dynamically imported when needed to avoid fs imports in browser
-import { cosineDistance } from '../utils/distance.js';
-/**
- * Base class for memory augmentations that wrap a StorageAdapter
- */
-class BaseMemoryAugmentation {
-    constructor(name, storage) {
-        this.description = 'Base memory augmentation';
-        this.enabled = true;
-        this.isInitialized = false;
-        this.name = name;
-        this.storage = storage;
-    }
-    async initialize() {
-        if (this.isInitialized) {
-            return;
-        }
-        try {
-            await this.storage.init();
-            this.isInitialized = true;
-        }
-        catch (error) {
-            console.error(`Failed to initialize ${this.name}:`, error);
-            throw new Error(`Failed to initialize ${this.name}: ${error}`);
-        }
-    }
-    async shutDown() {
-        this.isInitialized = false;
-    }
-    async getStatus() {
-        return this.isInitialized ? 'active' : 'inactive';
-    }
-    async storeData(key, data, options) {
-        await this.ensureInitialized();
-        try {
-            await this.storage.saveMetadata(key, data);
-            return { success: true, data: true };
-        }
-        catch (error) {
-            console.error(`Failed to store data for key ${key}:`, error);
-            return {
-                success: false,
-                data: false,
-                error: `Failed to store data: ${error}`
-            };
-        }
-    }
-    async retrieveData(key, options) {
-        await this.ensureInitialized();
-        try {
-            const data = await this.storage.getMetadata(key);
-            return {
-                success: true,
-                data
-            };
-        }
-        catch (error) {
-            console.error(`Failed to retrieve data for key ${key}:`, error);
-            return {
-                success: false,
-                data: null,
-                error: `Failed to retrieve data: ${error}`
-            };
-        }
-    }
-    async updateData(key, data, options) {
-        await this.ensureInitialized();
-        try {
-            await this.storage.saveMetadata(key, data);
-            return { success: true, data: true };
-        }
-        catch (error) {
-            console.error(`Failed to update data for key ${key}:`, error);
-            return {
-                success: false,
-                data: false,
-                error: `Failed to update data: ${error}`
-            };
-        }
-    }
-    async deleteData(key, options) {
-        await this.ensureInitialized();
-        try {
-            // There's no direct deleteMetadata method, so we save null
-            await this.storage.saveMetadata(key, null);
-            return { success: true, data: true };
-        }
-        catch (error) {
-            console.error(`Failed to delete data for key ${key}:`, error);
-            return {
-                success: false,
-                data: false,
-                error: `Failed to delete data: ${error}`
-            };
-        }
-    }
-    async listDataKeys(pattern, options) {
-        // This is a limitation of the current StorageAdapter interface
-        // It doesn't provide a way to list all metadata keys
-        // We could implement this in the future by extending the StorageAdapter interface
-        return {
-            success: false,
-            data: [],
-            error: 'listDataKeys is not supported by this storage adapter'
-        };
-    }
-    /**
-     * Searches for data in the storage using vector similarity.
-     * Implements the findNearest functionality by calculating distances client-side.
-     * @param query The query vector or data to search for
-     * @param k Number of results to return (default: 10)
-     * @param options Optional search options
-     */
-    async search(query, k = 10, options) {
-        await this.ensureInitialized();
-        try {
-            // Check if query is a vector
-            let queryVector;
-            if (Array.isArray(query) && query.every(item => typeof item === 'number')) {
-                queryVector = query;
-            }
-            else {
-                // If query is not a vector, we can't perform vector search
-                return {
-                    success: false,
-                    data: [],
-                    error: 'Query must be a vector (array of numbers) for vector search'
-                };
-            }
-            // Process nodes in batches to avoid loading everything into memory
-            const allResults = [];
-            let hasMore = true;
-            let cursor;
-            while (hasMore) {
-                // Get a batch of nodes
-                const batchResult = await this.storage.getNouns({
-                    pagination: { limit: 100, cursor }
-                });
-                // Process this batch
-                for (const noun of batchResult.items) {
-                    // Skip nodes that don't have a vector
-                    if (!noun.vector || !Array.isArray(noun.vector)) {
-                        continue;
-                    }
-                    // Get metadata for the node
-                    const metadata = await this.storage.getMetadata(noun.id);
-                    // Calculate distance between query vector and node vector
-                    const distance = cosineDistance(queryVector, noun.vector);
-                    // Convert distance to similarity score (1 - distance for cosine)
-                    // This way higher scores are better (more similar)
-                    const score = 1 - distance;
-                    allResults.push({
-                        id: noun.id,
-                        score,
-                        data: metadata
-                    });
-                }
-                // Update pagination state
-                hasMore = batchResult.hasMore;
-                cursor = batchResult.nextCursor;
-            }
-            // Sort results by score (descending) and take top k
-            allResults.sort((a, b) => b.score - a.score);
-            const topResults = allResults.slice(0, k);
-            return {
-                success: true,
-                data: topResults
-            };
-        }
-        catch (error) {
-            console.error(`Failed to search in storage:`, error);
-            return {
-                success: false,
-                data: [],
-                error: `Failed to search in storage: ${error}`
-            };
-        }
-    }
-    async ensureInitialized() {
-        if (!this.isInitialized) {
-            await this.initialize();
-        }
-    }
-}
-/**
- * Memory augmentation that uses in-memory storage
- */
-export class MemoryStorageAugmentation extends BaseMemoryAugmentation {
-    constructor(name) {
-        super(name, new MemoryStorage());
-        this.description = 'Memory augmentation that stores data in memory';
-        this.enabled = true;
-    }
-    getType() {
-        return AugmentationType.MEMORY;
-    }
-}
-/**
- * Memory augmentation that uses file system storage
- */
-export class FileSystemStorageAugmentation extends BaseMemoryAugmentation {
-    constructor(name, rootDirectory) {
-        // Temporarily use MemoryStorage, will be replaced in initialize()
-        super(name, new MemoryStorage());
-        this.description = 'Memory augmentation that stores data in the file system';
-        this.enabled = true;
-        this.rootDirectory = rootDirectory || '.';
-    }
-    async initialize() {
-        try {
-            // Dynamically import FileSystemStorage
-            const { FileSystemStorage } = await import('../storage/adapters/fileSystemStorage.js');
-            this.storage = new FileSystemStorage(this.rootDirectory);
-            await super.initialize();
-        }
-        catch (error) {
-            console.error('Failed to load FileSystemStorage:', error);
-            throw new Error(`Failed to initialize FileSystemStorage: ${error}`);
-        }
-    }
-    getType() {
-        return AugmentationType.MEMORY;
-    }
-}
-/**
- * Memory augmentation that uses OPFS (Origin Private File System) storage
- */
-export class OPFSStorageAugmentation extends BaseMemoryAugmentation {
-    constructor(name) {
-        super(name, new OPFSStorage());
-        this.description = 'Memory augmentation that stores data in the Origin Private File System';
-        this.enabled = true;
-    }
-    getType() {
-        return AugmentationType.MEMORY;
-    }
-}
-/**
- * Factory function to create the appropriate memory augmentation based on the environment
- */
-export async function createMemoryAugmentation(name, options = {}) {
-    // If a specific storage type is requested, use that
-    if (options.storageType) {
-        switch (options.storageType) {
-            case 'memory':
-                return new MemoryStorageAugmentation(name);
-            case 'filesystem':
-                return new FileSystemStorageAugmentation(name, options.rootDirectory);
-            case 'opfs':
-                return new OPFSStorageAugmentation(name);
-        }
-    }
-    // Otherwise, select based on environment
-    // Use the global isNode variable from the environment detection
-    const isNodeEnv = globalThis.__ENV__?.isNode || (typeof process !== 'undefined' &&
-        process.versions != null &&
-        process.versions.node != null);
-    if (isNodeEnv) {
-        // In Node.js, use FileSystemStorage
-        return new FileSystemStorageAugmentation(name, options.rootDirectory);
-    }
-    else {
-        // In browser, try OPFS first
-        const opfsStorage = new OPFSStorage();
-        if (opfsStorage.isOPFSAvailable()) {
-            // Request persistent storage if specified
-            if (options.requestPersistentStorage) {
-                await opfsStorage.requestPersistentStorage();
-            }
-            return new OPFSStorageAugmentation(name);
-        }
-        else {
-            // Fall back to memory storage
-            return new MemoryStorageAugmentation(name);
-        }
-    }
-}
-//# sourceMappingURL=memoryAugmentations.js.map

package/dist/augmentations/serverSearchAugmentations.d.ts

@@ -1,190 +0,0 @@
-/**
- * Server Search Augmentations
- *
- * This file implements conduit and activation augmentations for browser-server search functionality.
- * It allows Brainy to search a server-hosted instance and store results locally.
- */
-import { AugmentationResponse, WebSocketConnection } from '../types/augmentations.js';
-import { BaseAugmentation } from '../augmentations/brainyAugmentation.js';
-import { BrainyDataInterface } from '../types/brainyDataInterface.js';
-/**
- * ServerSearchConduitAugmentation
- *
- * A specialized conduit augmentation that provides functionality for searching
- * a server-hosted Brainy instance and storing results locally.
- */
-export declare class ServerSearchConduitAugmentation extends BaseAugmentation {
-    readonly name = "server-search-conduit";
-    readonly timing: "after";
-    readonly metadata: "readonly";
-    operations: ("addNoun" | "delete" | "addVerb")[];
-    readonly priority = 20;
-    private localDb;
-    constructor(name?: string);
-    /**
-     * Initialize the augmentation
-     */
-    protected onInitialize(): Promise<void>;
-    /**
-     * Set the local Brainy instance
-     * @param db The Brainy instance to use for local storage
-     */
-    setLocalDb(db: BrainyDataInterface): void;
-    /**
-     * Stub method for performing search operations via WebSocket
-     * TODO: Implement proper WebSocket communication
-     */
-    private performSearch;
-    /**
-     * Stub method for performing write operations via WebSocket
-     * TODO: Implement proper WebSocket communication
-     */
-    private performWrite;
-    /**
-     * Get the local Brainy instance
-     * @returns The local Brainy instance
-     */
-    getLocalDb(): BrainyDataInterface | null;
-    /**
-     * Execute method - required by BaseAugmentation
-     */
-    execute<T = any>(operation: string, params: any, next: () => Promise<T>): Promise<T>;
-    /**
-     * Search the server-hosted Brainy instance and store results locally
-     * @param connectionId The ID of the established connection
-     * @param query The search query
-     * @param limit Maximum number of results to return
-     * @returns Search results
-     */
-    searchServer(connectionId: string, query: string, limit?: number): Promise<AugmentationResponse<unknown>>;
-    /**
-     * Search the local Brainy instance
-     * @param query The search query
-     * @param limit Maximum number of results to return
-     * @returns Search results
-     */
-    searchLocal(query: string, limit?: number): Promise<AugmentationResponse<unknown>>;
-    /**
-     * Search both server and local instances, combine results, and store server results locally
-     * @param connectionId The ID of the established connection
-     * @param query The search query
-     * @param limit Maximum number of results to return
-     * @returns Combined search results
-     */
-    searchCombined(connectionId: string, query: string, limit?: number): Promise<AugmentationResponse<unknown>>;
-    /**
-     * Add data to both local and server instances
-     * @param connectionId The ID of the established connection
-     * @param data Text or vector to add
-     * @param metadata Metadata for the data
-     * @returns ID of the added data
-     */
-    addToBoth(connectionId: string, data: string | any[], metadata?: any): Promise<AugmentationResponse<string>>;
-    /**
-     * Establish connection to remote server
-     * @param serverUrl Server URL to connect to
-     * @param options Connection options
-     * @returns Connection promise
-     */
-    establishConnection(serverUrl: string, options?: any): Promise<any>;
-    /**
-     * Close WebSocket connection
-     * @param connectionId Connection ID to close
-     * @returns Promise that resolves when connection is closed
-     */
-    closeWebSocket(connectionId: string): Promise<void>;
-}
-/**
- * ServerSearchActivationAugmentation
- *
- * An activation augmentation that provides actions for server search functionality.
- */
-export declare class ServerSearchActivationAugmentation extends BaseAugmentation {
-    readonly name = "server-search-activation";
-    readonly timing: "after";
-    readonly metadata: "readonly";
-    operations: ("search" | "addNoun")[];
-    readonly priority = 20;
-    private conduitAugmentation;
-    private connections;
-    constructor(name?: string);
-    protected onInitialize(): Promise<void>;
-    protected onShutdown(): Promise<void>;
-    execute<T = any>(operation: string, params: any, next: () => Promise<T>): Promise<T>;
-    /**
-     * Set the conduit augmentation to use for server search
-     * @param conduit The ServerSearchConduitAugmentation to use
-     */
-    setConduitAugmentation(conduit: ServerSearchConduitAugmentation): void;
-    /**
-     * Store a connection for later use
-     * @param connectionId The ID to use for the connection
-     * @param connection The WebSocket connection
-     */
-    storeConnection(connectionId: string, connection: WebSocketConnection): void;
-    /**
-     * Get a stored connection
-     * @param connectionId The ID of the connection to retrieve
-     * @returns The WebSocket connection
-     */
-    getConnection(connectionId: string): WebSocketConnection | undefined;
-    /**
-     * Trigger an action based on a processed command or internal state
-     * @param actionName The name of the action to trigger
-     * @param parameters Optional parameters for the action
-     */
-    triggerAction(actionName: string, parameters?: Record<string, unknown>): AugmentationResponse<unknown>;
-    /**
-     * Handle the connectToServer action
-     * @param parameters Action parameters
-     */
-    private handleConnectToServer;
-    /**
-     * Handle the searchServer action
-     * @param parameters Action parameters
-     */
-    private handleSearchServer;
-    /**
-     * Handle the searchLocal action
-     * @param parameters Action parameters
-     */
-    private handleSearchLocal;
-    /**
-     * Handle the searchCombined action
-     * @param parameters Action parameters
-     */
-    private handleSearchCombined;
-    /**
-     * Handle the addToBoth action
-     * @param parameters Action parameters
-     */
-    private handleAddToBoth;
-    /**
-     * Generates an expressive output or response from Brainy
-     * @param knowledgeId The identifier of the knowledge to express
-     * @param format The desired output format (e.g., 'text', 'json')
-     */
-    generateOutput(knowledgeId: string, format: string): AugmentationResponse<string | Record<string, unknown>>;
-    /**
-     * Interacts with an external system or API
-     * @param systemId The identifier of the external system
-     * @param payload The data to send to the external system
-     */
-    interactExternal(systemId: string, payload: Record<string, unknown>): AugmentationResponse<unknown>;
-}
-/**
- * Factory function to create server search augmentations
- * @param serverUrl The URL of the server to connect to
- * @param options Additional options
- * @returns An object containing the created augmentations
- */
-export declare function createServerSearchAugmentations(serverUrl: string, options?: {
-    conduitName?: string;
-    activationName?: string;
-    protocols?: string | string[];
-    localDb?: BrainyDataInterface;
-}): Promise<{
-    conduit: ServerSearchConduitAugmentation;
-    activation: ServerSearchActivationAugmentation;
-    connection: WebSocketConnection;
-}>;