Initial commit of Brainy vector database v0.1.0

src/types/augmentations.ts

@@ -0,0 +1,283 @@
+/** Common types for augmentation system */
+type WebSocketConnection = {
+  connectionId: string
+  url: string
+  status: 'connected' | 'disconnected' | 'error'
+}
+
+type DataCallback<T> = (data: T) => void
+type AugmentationResponse<T> = Promise<{
+  success: boolean
+  data: T
+  error?: string
+}>
+
+/**
+ * Base interface for all Brainy augmentations.
+ * All augmentations must implement these core properties.
+ */
+interface IAugmentation {
+  /** A unique identifier for the augmentation (e.g., "my-reasoner-v1") */
+  readonly name: string
+  /** A human-readable description of the augmentation's purpose */
+  readonly description: string
+
+  /**
+   * Initializes the augmentation. This method is called when Brainy starts up.
+   * @returns A Promise that resolves when initialization is complete
+   */
+  initialize(): Promise<void>
+
+  shutDown(): Promise<void>
+
+  getStatus(): Promise<'active' | 'inactive' | 'error'>
+}
+
+/**
+ * Interface for WebSocket support.
+ * Augmentations that implement this interface can communicate via WebSockets.
+ */
+interface IWebSocketSupport {
+  /**
+   * Establishes a WebSocket connection.
+   * @param url The WebSocket server URL to connect to
+   * @param protocols Optional subprotocols
+   * @returns A Promise resolving to a connection handle or status
+   */
+  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: DataCallback<unknown>): 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>
+}
+
+namespace BrainyAugmentations {
+  /**
+   * Interface for Cognitions augmentations.
+   * These augmentations enable advanced reasoning, inference, and logical operations.
+   */
+  export interface ICognitionAugmentation extends IAugmentation {
+    /**
+     * Performs a reasoning operation based on current knowledge.
+     * @param query The specific reasoning task or question
+     * @param context Optional additional context for the reasoning
+     */
+    reason(query: string, context?: Record<string, unknown>): AugmentationResponse<{
+      inference: string
+      confidence: number
+    }>
+
+    /**
+     * Infers relationships or new facts from existing data.
+     * @param dataSubset A subset of data to infer from
+     */
+    infer(dataSubset: Record<string, unknown>): AugmentationResponse<Record<string, unknown>>
+
+    /**
+     * Executes a logical operation or rule set.
+     * @param ruleId The identifier of the rule or logic to apply
+     * @param input Data to apply the logic to
+     */
+    executeLogic(ruleId: string, input: Record<string, unknown>): AugmentationResponse<boolean>
+  }
+
+  /**
+   * Interface for Senses augmentations.
+   * These augmentations ingest and process raw, unstructured data into nouns and verbs.
+   */
+  export interface ISenseAugmentation extends IAugmentation {
+    /**
+     * Processes raw input data into structured nouns and verbs.
+     * @param rawData The raw, unstructured data (e.g., text, image buffer, audio stream)
+     * @param dataType The type of raw data (e.g., 'text', 'image', 'audio')
+     */
+    processRawData(rawData: Buffer | string, dataType: string): AugmentationResponse<{
+      nouns: string[]
+      verbs: string[]
+    }>
+
+    /**
+     * Registers a listener for real-time data feeds.
+     * @param feedUrl The URL or identifier of the real-time feed
+     * @param callback A function to call with processed data
+     */
+    listenToFeed(
+      feedUrl: string,
+      callback: DataCallback<{ nouns: string[]; verbs: string[] }>
+    ): Promise<void>
+  }
+
+  /**
+   * Interface for Perceptions augmentations.
+   * These augmentations interpret, contextualize, and visualize identified nouns and verbs.
+   */
+  export interface IPerceptionAugmentation extends IAugmentation {
+    /**
+     * Interprets and contextualizes processed nouns and verbs.
+     * @param nouns The list of identified nouns
+     * @param verbs The list of identified verbs
+     * @param context Optional additional context for interpretation
+     */
+    interpret(
+      nouns: string[],
+      verbs: string[],
+      context?: Record<string, unknown>
+    ): AugmentationResponse<Record<string, unknown>>
+
+    /**
+     * Organizes and filters information.
+     * @param data The data to organize (e.g., interpreted perceptions)
+     * @param criteria Optional criteria for filtering/prioritization
+     */
+    organize(
+      data: Record<string, unknown>,
+      criteria?: Record<string, unknown>
+    ): AugmentationResponse<Record<string, unknown>>
+
+    /**
+     * Generates a visualization based on the provided data.
+     * @param data The data to visualize (e.g., interpreted patterns)
+     * @param visualizationType The desired type of visualization (e.g., 'graph', 'chart')
+     */
+    generateVisualization(
+      data: Record<string, unknown>,
+      visualizationType: string
+    ): AugmentationResponse<string | Buffer | Record<string, unknown>>
+  }
+
+  /**
+   * Interface for Activations augmentations.
+   * These augmentations dictate how Brainy initiates actions, responses, or data manipulations.
+   */
+  export interface IActivationAugmentation extends IAugmentation {
+    /**
+     * Triggers 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>
+
+    /**
+     * 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>
+  }
+
+  /**
+   * Interface for Dialogs augmentations.
+   * These augmentations facilitate natural language understanding and generation for conversational interaction.
+   */
+  export interface IDialogAugmentation extends IAugmentation {
+    /**
+     * Processes a user's natural language input (query).
+     * @param naturalLanguageQuery The raw text query from the user
+     * @param sessionId An optional session ID for conversational context
+     */
+    processUserInput(naturalLanguageQuery: string, sessionId?: string): AugmentationResponse<{
+      intent: string
+      nouns: string[]
+      verbs: string[]
+      context: Record<string, unknown>
+    }>
+
+    /**
+     * Generates a natural language response based on Brainy's knowledge and interpreted input.
+     * @param interpretedInput The output from `processUserInput` or similar
+     * @param knowledgeContext Relevant knowledge retrieved from Brainy
+     * @param sessionId An optional session ID for conversational context
+     */
+    generateResponse(
+      interpretedInput: Record<string, unknown>,
+      knowledgeContext: Record<string, unknown>,
+      sessionId?: string
+    ): AugmentationResponse<string>
+
+    /**
+     * Manages and updates conversational context.
+     * @param sessionId The session ID
+     * @param contextUpdate The data to update the context with
+     */
+    manageContext(sessionId: string, contextUpdate: Record<string, unknown>): Promise<void>
+  }
+
+  /**
+   * Interface for Conduits augmentations.
+   * These augmentations establish and manage high-bandwidth, dedicated channels for structured, programmatic two-way data exchange.
+   */
+  export interface IConduitAugmentation extends IAugmentation {
+    /**
+     * Establishes a connection for programmatic data exchange.
+     * @param targetSystemId The identifier of the external system to connect to
+     * @param config Configuration details for the connection (e.g., API keys, endpoints)
+     */
+    establishConnection(
+      targetSystemId: string,
+      config: Record<string, unknown>
+    ): AugmentationResponse<WebSocketConnection>
+
+    /**
+     * Reads structured data directly from Brainy's knowledge graph.
+     * @param query A structured query (e.g., graph query language, object path)
+     * @param options Optional query options (e.g., depth, filters)
+     */
+    readData(
+      query: Record<string, unknown>,
+      options?: Record<string, unknown>
+    ): AugmentationResponse<unknown>
+
+    /**
+     * Writes or updates structured data directly into Brainy's knowledge graph.
+     * @param data The structured data to write/update
+     * @param options Optional write options (e.g., merge, overwrite)
+     */
+    writeData(
+      data: Record<string, unknown>,
+      options?: Record<string, unknown>
+    ): AugmentationResponse<unknown>
+
+    /**
+     * Monitors a specific data stream or event within Brainy for external systems.
+     * @param streamId The identifier of the data stream or event
+     * @param callback A function to call when new data/events occur
+     */
+    monitorStream(streamId: string, callback: DataCallback<unknown>): Promise<void>
+  }
+}
+
+/** WebSocket-enabled augmentation interfaces */
+type IWebSocketCognitionAugmentation = BrainyAugmentations.ICognitionAugmentation & IWebSocketSupport
+type IWebSocketSenseAugmentation = BrainyAugmentations.ISenseAugmentation & IWebSocketSupport
+type IWebSocketPerceptionAugmentation = BrainyAugmentations.IPerceptionAugmentation & IWebSocketSupport
+type IWebSocketActivationAugmentation = BrainyAugmentations.IActivationAugmentation & IWebSocketSupport
+type IWebSocketDialogAugmentation = BrainyAugmentations.IDialogAugmentation & IWebSocketSupport
+type IWebSocketConduitAugmentation = BrainyAugmentations.IConduitAugmentation & IWebSocketSupport

src/types/fileSystemTypes.ts

@@ -0,0 +1,12 @@
+/**
+ * Type declarations for the File System Access API
+ * Extends the FileSystemDirectoryHandle interface to include the [Symbol.asyncIterator] method
+ */
+
+// Extend the FileSystemDirectoryHandle interface
+interface FileSystemDirectoryHandle {
+  [Symbol.asyncIterator](): AsyncIterableIterator<[string, FileSystemHandle]>;
+}
+
+// Export something to make this a module
+export const fileSystemTypesLoaded = true;

src/types/graphTypes.ts

@@ -0,0 +1,129 @@
+// Common metadata types
+/**
+ * Represents a high-precision timestamp with seconds and nanoseconds
+ * Used for tracking creation and update times of graph elements
+ */
+interface Timestamp {
+  seconds: number
+  nanoseconds: number
+}
+
+/**
+ * Metadata about the creator/source of a graph noun
+ * Tracks which augmentation and model created the element
+ */
+interface CreatorMetadata {
+  augmentation: string    // Name of the augmentation that created this element
+  version: string   // Version of the augmentation
+  model: string     // Model identifier used in creation
+  modelVersion: string  // Version of the model
+}
+
+/**
+ * Base interface for nodes (nouns) in the graph
+ * Represents entities like people, places, things, etc.
+ */
+export interface GraphNoun {
+  id: string                            // Unique identifier for the noun
+  createdBy: CreatorMetadata           // Information about what created this noun
+  noun: NounType                       // Type classification of the noun
+  createdAt: Timestamp                 // When the noun was created
+  updatedAt: Timestamp                 // When the noun was last updated
+  data?: Record<string, unknown>       // Additional flexible data storage
+  embedding?: number[]                 // Vector representation of the noun
+}
+
+/**
+ * Base interface for edges (verbs) in the graph
+ * Represents relationships between nouns
+ */
+export interface GraphVerb {
+  id: string                           // Unique identifier for the verb
+  source: string                       // ID of the source noun
+  target: string                       // ID of the target noun
+  label?: string                       // Optional descriptive label
+  verb: VerbType                       // Type of relationship
+  createdAt: Timestamp                // When the verb was created
+  updatedAt: Timestamp                // When the verb was last updated
+  data?: Record<string, unknown>      // Additional flexible data storage
+  embedding?: number[]                // Vector representation of the relationship
+  confidence?: number                 // Confidence score (0-1)
+  weight?: number                     // Strength/importance of the relationship
+}
+
+/**
+ * Version of GraphVerb for embedded relationships
+ * Used when the source is implicit from the parent document
+ */
+export type EmbeddedGraphVerb = Omit<GraphVerb, 'source'>
+
+// Proper Noun interfaces - extend GraphNoun with specific noun types
+
+/**
+ * Represents a person entity in the graph
+ */
+export interface Person extends GraphNoun {
+  noun: typeof NounType.Person
+}
+
+/**
+ * Represents a physical location in the graph
+ */
+export interface Place extends GraphNoun {
+  noun: typeof NounType.Place
+}
+
+/**
+ * Represents a physical or virtual object in the graph
+ */
+export interface Thing extends GraphNoun {
+  noun: typeof NounType.Thing
+}
+
+/**
+ * Represents an event or occurrence in the graph
+ */
+export interface Event extends GraphNoun {
+  noun: typeof NounType.Event
+}
+
+/**
+ * Represents an abstract concept or idea in the graph
+ */
+export interface Concept extends GraphNoun {
+  noun: typeof NounType.Concept
+}
+
+/**
+ * Represents content (text, media, etc.) in the graph
+ */
+export interface Content extends GraphNoun {
+  noun: typeof NounType.Content
+}
+
+/**
+ * Defines valid noun types for graph entities
+ * Used for categorizing different types of nodes
+ */
+export const NounType = {
+  Person: 'person',    // Person entities
+  Place: 'place',     // Physical locations
+  Thing: 'thing',     // Physical or virtual objects
+  Event: 'event',     // Events or occurrences
+  Concept: 'concept',  // Abstract concepts or ideas
+  Content: 'content'  // Content items
+} as const
+export type NounType = (typeof NounType)[keyof typeof NounType]
+
+/**
+ * Defines valid verb types for relationships
+ * Used for categorizing different types of connections
+ */
+export const VerbType = {
+  AttributedTo: 'attributedTo',  // Indicates attribution or authorship
+  Controls: 'controls',          // Indicates control or ownership
+  Created: 'created',           // Indicates creation or authorship
+  Earned: 'earned',             // Indicates achievement or acquisition
+  Owns: 'owns'                  // Indicates ownership
+} as const
+export type VerbType = (typeof VerbType)[keyof typeof VerbType]

src/types/tensorflowTypes.ts

@@ -0,0 +1,14 @@
+// Type declarations for TensorFlow.js models
+
+// This file is a placeholder for TensorFlow.js model types
+// We're using type assertions in the code instead of module declarations
+
+// Define some basic types that might be useful
+export interface TensorflowModel {
+  load(): Promise<any>;
+  embed(data: string[]): any;
+  dispose(): void;
+}
+
+// Export a dummy constant to make this a proper module
+export const tensorflowModelsLoaded = true;