@soulcraft/brainy 0.9.5

package/dist/augmentations/conduitAugmentations.d.ts

@@ -0,0 +1,173 @@
+import { AugmentationType, IConduitAugmentation, IWebSocketSupport, AugmentationResponse, WebSocketConnection } from '../types/augmentations.js';
+/**
+ * Base class for conduit augmentations that provide data synchronization between Brainy instances
+ */
+declare abstract class BaseConduitAugmentation implements IConduitAugmentation {
+    readonly name: string;
+    readonly description: string;
+    enabled: boolean;
+    protected isInitialized: boolean;
+    protected connections: Map<string, any>;
+    constructor(name: string);
+    initialize(): Promise<void>;
+    shutDown(): Promise<void>;
+    getStatus(): Promise<'active' | 'inactive' | 'error'>;
+    abstract establishConnection(targetSystemId: string, config: Record<string, unknown>): Promise<AugmentationResponse<WebSocketConnection>>;
+    abstract readData(query: Record<string, unknown>, options?: Record<string, unknown>): Promise<AugmentationResponse<unknown>>;
+    abstract writeData(data: Record<string, unknown>, options?: Record<string, unknown>): Promise<AugmentationResponse<unknown>>;
+    abstract monitorStream(streamId: string, callback: (data: unknown) => void): Promise<void>;
+    protected ensureInitialized(): Promise<void>;
+}
+/**
+ * WebSocket conduit augmentation for syncing Brainy instances using WebSockets
+ *
+ * This conduit is for syncing between browsers and servers, or between servers.
+ * WebSockets cannot be used for direct browser-to-browser communication without a server in the middle.
+ */
+export declare class WebSocketConduitAugmentation extends BaseConduitAugmentation implements IWebSocketSupport {
+    readonly description = "Conduit augmentation that syncs Brainy instances using WebSockets";
+    private webSocketConnections;
+    private messageCallbacks;
+    constructor(name?: string);
+    getType(): AugmentationType;
+    /**
+     * Establishes a connection to another Brainy instance
+     * @param targetSystemId The URL or identifier of the target system
+     * @param config Configuration options for the connection
+     */
+    establishConnection(targetSystemId: string, config: Record<string, unknown>): Promise<AugmentationResponse<WebSocketConnection>>;
+    /**
+     * Reads data from a connected Brainy instance
+     * @param query Query parameters for reading data
+     * @param options Additional options
+     */
+    readData(query: Record<string, unknown>, options?: Record<string, unknown>): Promise<AugmentationResponse<unknown>>;
+    /**
+     * Writes data to a connected Brainy instance
+     * @param data The data to write
+     * @param options Additional options
+     */
+    writeData(data: Record<string, unknown>, options?: Record<string, unknown>): Promise<AugmentationResponse<unknown>>;
+    /**
+     * Monitors a data stream from a connected Brainy instance
+     * @param streamId The ID of the stream to monitor (usually a connection ID)
+     * @param callback Function to call when new data is received
+     */
+    monitorStream(streamId: string, callback: (data: unknown) => void): Promise<void>;
+    /**
+     * Establishes a WebSocket connection
+     * @param url The WebSocket server URL to connect to
+     * @param protocols Optional subprotocols
+     */
+    connectWebSocket(url: string, protocols?: string | string[]): Promise<WebSocketConnection>;
+    /**
+     * Sends data through an established WebSocket connection
+     * @param connectionId The identifier of the established connection
+     * @param data The data to send (will be serialized if not a string)
+     */
+    sendWebSocketMessage(connectionId: string, data: unknown): Promise<void>;
+    /**
+     * Registers a callback for incoming WebSocket messages
+     * @param connectionId The identifier of the established connection
+     * @param callback The function to call when a message is received
+     */
+    onWebSocketMessage(connectionId: string, callback: (data: unknown) => void): Promise<void>;
+    /**
+     * Removes a callback for incoming WebSocket messages
+     * @param connectionId The identifier of the established connection
+     * @param callback The function to remove from the callbacks
+     */
+    offWebSocketMessage(connectionId: string, callback: (data: unknown) => void): Promise<void>;
+    /**
+     * Closes an established WebSocket connection
+     * @param connectionId The identifier of the established connection
+     * @param code Optional close code
+     * @param reason Optional close reason
+     */
+    closeWebSocket(connectionId: string, code?: number, reason?: string): Promise<void>;
+}
+/**
+ * WebRTC conduit augmentation for syncing Brainy instances using WebRTC
+ *
+ * This conduit is for direct peer-to-peer syncing between browsers.
+ * It is the recommended approach for browser-to-browser communication.
+ */
+export declare class WebRTCConduitAugmentation extends BaseConduitAugmentation implements IWebSocketSupport {
+    readonly description = "Conduit augmentation that syncs Brainy instances using WebRTC";
+    private peerConnections;
+    private dataChannels;
+    private webSocketConnections;
+    private messageCallbacks;
+    private signalServer;
+    constructor(name?: string);
+    getType(): AugmentationType;
+    initialize(): Promise<void>;
+    /**
+     * Establishes a connection to another Brainy instance using WebRTC
+     * @param targetSystemId The peer ID or signal server URL
+     * @param config Configuration options for the connection
+     */
+    establishConnection(targetSystemId: string, config: Record<string, unknown>): Promise<AugmentationResponse<WebSocketConnection>>;
+    /**
+     * Handles an incoming WebRTC offer
+     * @param peerId The ID of the peer sending the offer
+     * @param offer The SDP offer
+     * @param config Configuration options
+     */
+    private handleOffer;
+    /**
+     * Reads data from a connected Brainy instance
+     * @param query Query parameters for reading data
+     * @param options Additional options
+     */
+    readData(query: Record<string, unknown>, options?: Record<string, unknown>): Promise<AugmentationResponse<unknown>>;
+    /**
+     * Writes data to a connected Brainy instance
+     * @param data The data to write
+     * @param options Additional options
+     */
+    writeData(data: Record<string, unknown>, options?: Record<string, unknown>): Promise<AugmentationResponse<unknown>>;
+    /**
+     * Monitors a data stream from a connected Brainy instance
+     * @param streamId The ID of the stream to monitor (usually a connection ID)
+     * @param callback Function to call when new data is received
+     */
+    monitorStream(streamId: string, callback: (data: unknown) => void): Promise<void>;
+    /**
+     * Establishes a WebSocket connection (used for signaling in WebRTC)
+     * @param url The WebSocket server URL to connect to
+     * @param protocols Optional subprotocols
+     */
+    connectWebSocket(url: string, protocols?: string | string[]): Promise<WebSocketConnection>;
+    /**
+     * Sends data through an established WebSocket or WebRTC connection
+     * @param connectionId The identifier of the established connection
+     * @param data The data to send (will be serialized if not a string)
+     */
+    sendWebSocketMessage(connectionId: string, data: unknown): Promise<void>;
+    /**
+     * Registers a callback for incoming WebSocket or WebRTC messages
+     * @param connectionId The identifier of the established connection
+     * @param callback The function to call when a message is received
+     */
+    onWebSocketMessage(connectionId: string, callback: (data: unknown) => void): Promise<void>;
+    /**
+     * Removes a callback for incoming WebSocket or WebRTC messages
+     * @param connectionId The identifier of the established connection
+     * @param callback The function to remove from the callbacks
+     */
+    offWebSocketMessage(connectionId: string, callback: (data: unknown) => void): Promise<void>;
+    /**
+     * Closes an established WebSocket or WebRTC connection
+     * @param connectionId The identifier of the established connection
+     * @param code Optional close code
+     * @param reason Optional close reason
+     */
+    closeWebSocket(connectionId: string, code?: number, reason?: string): Promise<void>;
+}
+/**
+ * Factory function to create the appropriate conduit augmentation based on the type
+ */
+export declare function createConduitAugmentation(type: 'websocket' | 'webrtc', name?: string, options?: Record<string, unknown>): Promise<IConduitAugmentation & IWebSocketSupport>;
+export {};
+//# sourceMappingURL=conduitAugmentations.d.ts.map

package/dist/augmentations/memoryAugmentations.d.ts

@@ -0,0 +1,71 @@
+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;
+    constructor(name: string, rootDirectory?: string);
+    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 {};
+//# sourceMappingURL=memoryAugmentations.d.ts.map

package/dist/augmentations/serverSearchAugmentations.d.ts

@@ -0,0 +1,168 @@
+/**
+ * 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 { AugmentationType, IActivationAugmentation, AugmentationResponse, WebSocketConnection } from '../types/augmentations.js';
+import { WebSocketConduitAugmentation } from './conduitAugmentations.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 WebSocketConduitAugmentation {
+    private localDb;
+    constructor(name?: string);
+    /**
+     * Initialize the augmentation
+     */
+    initialize(): Promise<void>;
+    /**
+     * Set the local Brainy instance
+     * @param db The Brainy instance to use for local storage
+     */
+    setLocalDb(db: BrainyDataInterface): void;
+    /**
+     * Get the local Brainy instance
+     * @returns The local Brainy instance
+     */
+    getLocalDb(): BrainyDataInterface | null;
+    /**
+     * 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>>;
+}
+/**
+ * ServerSearchActivationAugmentation
+ *
+ * An activation augmentation that provides actions for server search functionality.
+ */
+export declare class ServerSearchActivationAugmentation implements IActivationAugmentation {
+    readonly name: string;
+    readonly description: string;
+    enabled: boolean;
+    private isInitialized;
+    private conduitAugmentation;
+    private connections;
+    constructor(name?: string);
+    getType(): AugmentationType;
+    /**
+     * Initialize the augmentation
+     */
+    initialize(): Promise<void>;
+    /**
+     * Shut down the augmentation
+     */
+    shutDown(): Promise<void>;
+    /**
+     * Get the status of the augmentation
+     */
+    getStatus(): Promise<'active' | 'inactive' | 'error'>;
+    /**
+     * 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;
+}>;
+//# sourceMappingURL=serverSearchAugmentations.d.ts.map