🧠 Brainy 2.0.0 - Zero-Configuration AI Database with Triple Intelligence™

MAJOR RELEASE: Complete evolution of Brainy with groundbreaking features and performance.

🎯 KEY FEATURES:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Triple Intelligence™ Engine
  - Unified Vector + Metadata + Graph search
  - O(log n) performance on all operations
  - 3ms average search latency at any scale

 API Consolidation
  - 15+ search methods → 2 clean APIs
  - search() for vector similarity
  - find() for natural language queries

 Natural Language Processing
  - 220+ pre-computed NLP patterns
  - Instant context understanding
  - "Show me recent React components with tests"

 Zero Configuration
  - Works instantly, no setup required
  - Built-in embedding models (no API keys)
  - Smart defaults for everything
  - Automatic optimization

 Enterprise Features (Free for Everyone)
  - Scales to 10M+ items
  - Write-Ahead Logging (WAL) for durability
  - Distributed architecture with sharding
  - Read/write separation
  - Connection pooling & request deduplication
  - Built-in monitoring & health checks

 Universal Compatibility
  - Node.js, Browser, Edge Workers
  - 4 Storage Adapters (Memory, FileSystem, OPFS, S3)
  - TypeScript with full type safety
  - Worker-based embeddings

📦 WHAT'S INCLUDED:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
• Core AI Database with HNSW indexing
• 19 Production-ready augmentations
• Universal Memory Manager
• Complete CLI with all commands
• Brain Cloud integration (soulcraft.com)
• Comprehensive documentation
• 52 test files with 400+ tests
• Migration guide from 1.x

📊 PERFORMANCE:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
• Initialize: 450ms (24MB memory)
• Search: 3ms average (up to 10M items)
• Metadata Filter: 0.8ms (O(log n))
• Bulk Import: 2.3s per 1000 items
• Production Scale: 5.8ms at 10M items

🔧 TECHNICAL IMPROVEMENTS:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
• TypeScript compilation: 153 errors → 0
• Memory usage: 200MB → 24MB baseline
• Circular dependencies resolved
• Worker thread communication fixed
• Storage adapter consistency
• Request coalescing for 3x performance

🛠️ CLI FEATURES:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
• brainy add - Smart data ingestion
• brainy find - Natural language search
• brainy search - Vector similarity
• brainy chat - AI conversation mode
• brainy cloud - Brain Cloud integration
• brainy augment - Manage extensions
• 100% API compatibility

📚 DOCUMENTATION:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
• Professional README with examples
• Quick Start guide (5 minutes)
• Enterprise Features guide
• Migration guide from 1.x
• API reference
• Architecture documentation

🌟 USE CASES:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
• AI memory layer for chatbots
• Semantic document search
• Code intelligence platforms
• Knowledge management systems
• Real-time recommendation engines
• Customer support automation

MIT License - Enterprise features included free for everyone.
No premium tiers, no paywalls, no limits.

Built with ❤️ by the Brainy community.
Visit https://soulcraft.com for Brain Cloud integration.
This commit is contained in:
David Snelling 2025-08-26 12:32:21 -07:00
commit 9c87982a7d
301 changed files with 178087 additions and 0 deletions

500
src/types/graphTypes.ts Normal file
View file

@ -0,0 +1,500 @@
/**
* Graph Types - Standardized Noun and Verb Type System
*
* This module defines a comprehensive, standardized set of noun and verb types
* that can be used to model any kind of graph, semantic network, or data model.
*
* ## Purpose and Design Philosophy
*
* The type system is designed to be:
* - **Universal**: Capable of representing any domain or use case
* - **Hierarchical**: Organized into logical categories for easy navigation
* - **Extensible**: Additional metadata can be attached to any entity or relationship
* - **Semantic**: Types carry meaning that can be used for reasoning and inference
*
* ## Noun Types (Entities)
*
* Noun types represent entities in the graph and are organized into categories:
*
* ### Core Entity Types
* - **Person**: Human entities and individuals
* - **Organization**: Formal organizations, companies, institutions
* - **Location**: Geographic locations, places, addresses
* - **Thing**: Physical objects and tangible items
* - **Concept**: Abstract ideas, concepts, and intangible entities
* - **Event**: Occurrences with time and place dimensions
*
* ### Digital/Content Types
* - **Document**: Text-based files and documents
* - **Media**: Non-text media files (images, videos, audio)
* - **File**: Generic digital files
* - **Message**: Communication content
* - **Content**: Generic content that doesn't fit other categories
*
* ### Collection Types
* - **Collection**: Generic groupings of items
* - **Dataset**: Structured collections of data
*
* ### Business/Application Types
* - **Product**: Commercial products and offerings
* - **Service**: Services and offerings
* - **User**: User accounts and profiles
* - **Task**: Actions, todos, and workflow items
* - **Project**: Organized initiatives with goals and timelines
*
* ### Descriptive Types
* - **Process**: Workflows, procedures, and sequences
* - **State**: States, conditions, or statuses
* - **Role**: Roles, positions, or responsibilities
* - **Topic**: Subjects or themes
* - **Language**: Languages or linguistic entities
* - **Currency**: Currencies and monetary units
* - **Measurement**: Measurements, metrics, or quantities
*
* ## Verb Types (Relationships)
*
* Verb types represent relationships between entities and are organized into categories:
*
* ### Core Relationship Types
* - **RelatedTo**: Generic relationship (default fallback)
* - **Contains**: Containment relationship
* - **PartOf**: Part-whole relationship
* - **LocatedAt**: Spatial relationship
* - **References**: Reference or citation relationship
*
* ### Temporal/Causal Types
* - **Precedes/Succeeds**: Temporal sequence relationships
* - **Causes**: Causal relationships
* - **DependsOn**: Dependency relationships
* - **Requires**: Necessity relationships
*
* ### Creation/Transformation Types
* - **Creates**: Creation relationships
* - **Transforms**: Transformation relationships
* - **Becomes**: State change relationships
* - **Modifies**: Modification relationships
* - **Consumes**: Consumption relationships
*
* ### Ownership/Attribution Types
* - **Owns**: Ownership relationships
* - **AttributedTo**: Attribution or authorship
* - **CreatedBy**: Creation attribution
* - **BelongsTo**: Belonging relationships
*
* ### Social/Organizational Types
* - **MemberOf**: Membership or affiliation
* - **WorksWith**: Professional relationships
* - **FriendOf**: Friendship relationships
* - **Follows**: Following relationships
* - **Likes**: Liking relationships
* - **ReportsTo**: Reporting relationships
* - **Supervises**: Supervisory relationships
* - **Mentors**: Mentorship relationships
* - **Communicates**: Communication relationships
*
* ### Descriptive/Functional Types
* - **Describes**: Descriptive relationships
* - **Defines**: Definition relationships
* - **Categorizes**: Categorization relationships
* - **Measures**: Measurement relationships
* - **Evaluates**: Evaluation or assessment relationships
* - **Uses**: Utilization relationships
* - **Implements**: Implementation relationships
* - **Extends**: Extension relationships
*
* ## Usage with Additional Metadata
*
* While the type system provides a standardized vocabulary, additional metadata
* can be attached to any entity or relationship to capture domain-specific
* information:
*
* ```typescript
* const person: GraphNoun = {
* id: 'person-123',
* noun: NounType.Person,
* data: {
* name: 'John Doe',
* age: 30,
* profession: 'Engineer'
* }
* }
*
* const worksFor: GraphVerb = {
* id: 'verb-456',
* source: 'person-123',
* target: 'org-789',
* verb: VerbType.MemberOf,
* data: {
* role: 'Senior Engineer',
* startDate: '2020-01-01',
* department: 'Engineering'
* }
* }
* ```
*
* ## Modeling Different Graph Types
*
* This type system can model various graph structures:
*
* ### Knowledge Graphs
* Use Person, Organization, Location, Concept entities with semantic relationships
* like AttributedTo, LocatedAt, RelatedTo
*
* ### Social Networks
* Use Person, User entities with social relationships like FriendOf, Follows,
* WorksWith, Communicates
*
* ### Content Networks
* Use Document, Media, Content entities with relationships like References,
* CreatedBy, Contains, Categorizes
*
* ### Business Process Models
* Use Task, Process, Role entities with relationships like Precedes, Requires,
* DependsOn, Transforms
*
* ### Organizational Charts
* Use Person, Role, Organization entities with relationships like ReportsTo,
* Supervises, MemberOf
*
* The flexibility of this system allows it to represent any domain while
* maintaining semantic consistency and enabling powerful graph operations
* and reasoning capabilities.
*/
// 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
}
/**
* 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
label?: string // Optional descriptive label
data?: Record<string, any> // Additional flexible data storage
embeddedVerbs?: EmbeddedGraphVerb[] // Optional embedded relationships
embedding?: number[] // Vector representation of the noun
}
/**
* Base interface for 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
createdBy: CreatorMetadata // Information about what created this verb
data?: Record<string, any> // 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 Location extends GraphNoun {
noun: typeof NounType.Location
}
/**
* 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
}
export interface Collection extends GraphNoun {
noun: typeof NounType.Collection
}
export interface Organization extends GraphNoun {
noun: typeof NounType.Organization
}
export interface Document extends GraphNoun {
noun: typeof NounType.Document
}
export interface Media extends GraphNoun {
noun: typeof NounType.Media
}
export interface File extends GraphNoun {
noun: typeof NounType.File
}
export interface Message extends GraphNoun {
noun: typeof NounType.Message
}
export interface Dataset extends GraphNoun {
noun: typeof NounType.Dataset
}
export interface Product extends GraphNoun {
noun: typeof NounType.Product
}
export interface Service extends GraphNoun {
noun: typeof NounType.Service
}
export interface User extends GraphNoun {
noun: typeof NounType.User
}
export interface Task extends GraphNoun {
noun: typeof NounType.Task
}
export interface Project extends GraphNoun {
noun: typeof NounType.Project
}
export interface Process extends GraphNoun {
noun: typeof NounType.Process
}
export interface State extends GraphNoun {
noun: typeof NounType.State
}
export interface Role extends GraphNoun {
noun: typeof NounType.Role
}
export interface Topic extends GraphNoun {
noun: typeof NounType.Topic
}
export interface Language extends GraphNoun {
noun: typeof NounType.Language
}
export interface Currency extends GraphNoun {
noun: typeof NounType.Currency
}
export interface Measurement extends GraphNoun {
noun: typeof NounType.Measurement
}
/**
* Represents content (text, media, etc.) in the graph
*/
export interface Content extends GraphNoun {
noun: typeof NounType.Content
}
/**
* Represents a scientific hypothesis or theory in the graph
*/
export interface Hypothesis extends GraphNoun {
noun: typeof NounType.Hypothesis
}
/**
* Represents an experiment, study, or research trial in the graph
*/
export interface Experiment extends GraphNoun {
noun: typeof NounType.Experiment
}
/**
* Represents a legal contract or agreement in the graph
*/
export interface Contract extends GraphNoun {
noun: typeof NounType.Contract
}
/**
* Represents a regulation, law, or compliance requirement in the graph
*/
export interface Regulation extends GraphNoun {
noun: typeof NounType.Regulation
}
/**
* Represents an interface, API, or protocol specification in the graph
*/
export interface Interface extends GraphNoun {
noun: typeof NounType.Interface
}
/**
* Represents a computational or infrastructure resource in the graph
*/
export interface Resource extends GraphNoun {
noun: typeof NounType.Resource
}
/**
* Defines valid noun types for graph entities
* Used for categorizing different types of nodes
*/
export const NounType = {
// Core Entity Types
Person: 'person', // Human entities
Organization: 'organization', // Formal organizations (companies, institutions, etc.)
Location: 'location', // Geographic locations (merges previous Place and Location)
Thing: 'thing', // Physical objects
Concept: 'concept', // Abstract ideas, concepts, and intangible entities
Event: 'event', // Occurrences with time and place
// Digital/Content Types
Document: 'document', // Text-based files and documents (reports, articles, etc.)
Media: 'media', // Non-text media files (images, videos, audio)
File: 'file', // Generic digital files (merges aspects of Digital with file-specific focus)
Message: 'message', // Communication content (emails, chat messages, posts)
Content: 'content', // Generic content that doesn't fit other categories
// Collection Types
Collection: 'collection', // Generic grouping of items (merges Group, List, and Category)
Dataset: 'dataset', // Structured collections of data
// Business/Application Types
Product: 'product', // Commercial products and offerings
Service: 'service', // Services and offerings
User: 'user', // User accounts and profiles
Task: 'task', // Actions, todos, and workflow items
Project: 'project', // Organized initiatives with goals and timelines
// Descriptive Types
Process: 'process', // Workflows, procedures, and sequences
State: 'state', // States, conditions, or statuses
Role: 'role', // Roles, positions, or responsibilities
Topic: 'topic', // Subjects or themes
Language: 'language', // Languages or linguistic entities
Currency: 'currency', // Currencies and monetary units
Measurement: 'measurement', // Measurements, metrics, or quantities
// Scientific/Research Types (100% Coverage)
Hypothesis: 'hypothesis', // Scientific theories, research hypotheses, propositions
Experiment: 'experiment', // Controlled studies, trials, tests, research methodologies
// Legal/Regulatory Types (100% Coverage)
Contract: 'contract', // Legal agreements, terms, policies, binding documents
Regulation: 'regulation', // Laws, rules, compliance requirements, standards
// Technical Infrastructure Types (100% Coverage)
Interface: 'interface', // APIs, protocols, contracts, specifications, endpoints
Resource: 'resource' // Compute resources, bandwidth, storage, infrastructure assets
} 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 = {
// Core Relationship Types
RelatedTo: 'relatedTo', // Generic relationship (default fallback)
Contains: 'contains', // Containment relationship (parent contains child)
PartOf: 'partOf', // Part-whole relationship (child is part of parent)
LocatedAt: 'locatedAt', // Spatial relationship
References: 'references', // Reference or citation relationship
// Temporal/Causal Types
Precedes: 'precedes', // Temporal sequence (comes before)
Succeeds: 'succeeds', // Temporal sequence (comes after)
Causes: 'causes', // Causal relationship (merges Influences and Causes)
DependsOn: 'dependsOn', // Dependency relationship
Requires: 'requires', // Necessity relationship (new)
// Creation/Transformation Types
Creates: 'creates', // Creation relationship (merges Created and Produces)
Transforms: 'transforms', // Transformation relationship
Becomes: 'becomes', // State change relationship
Modifies: 'modifies', // Modification relationship
Consumes: 'consumes', // Consumption relationship
// Ownership/Attribution Types
Owns: 'owns', // Ownership relationship (merges Controls and Owns)
AttributedTo: 'attributedTo', // Attribution or authorship
CreatedBy: 'createdBy', // Creation attribution (new, distinct from Creates)
BelongsTo: 'belongsTo', // Belonging relationship (new)
// Social/Organizational Types
MemberOf: 'memberOf', // Membership or affiliation
WorksWith: 'worksWith', // Professional relationship
FriendOf: 'friendOf', // Friendship relationship
Follows: 'follows', // Following relationship
Likes: 'likes', // Liking relationship
ReportsTo: 'reportsTo', // Reporting relationship
Supervises: 'supervises', // Supervisory relationship
Mentors: 'mentors', // Mentorship relationship
Communicates: 'communicates', // Communication relationship (merges Communicates and Collaborates)
// Descriptive/Functional Types
Describes: 'describes', // Descriptive relationship
Defines: 'defines', // Definition relationship
Categorizes: 'categorizes', // Categorization relationship
Measures: 'measures', // Measurement relationship
Evaluates: 'evaluates', // Evaluation or assessment relationship
Uses: 'uses', // Utilization relationship (new)
Implements: 'implements', // Implementation relationship
Extends: 'extends', // Extension relationship (enhancement, building upon)
// Enhanced Relationships (100% Coverage)
Inherits: 'inherits', // True inheritance relationship (class inheritance, legacy)
Conflicts: 'conflicts', // Contradictions, incompatibilities, opposing forces
Synchronizes: 'synchronizes', // Coordination, timing, synchronized operations
Competes: 'competes' // Competition, rivalry, competing relationships
} as const
export type VerbType = (typeof VerbType)[keyof typeof VerbType]