docs: simplify README.md and rebrand to "Brainy"

Rebranded from "Soulcraft Brainy" to "Brainy" throughout `README.md`. Improved readability by reformatting long paragraphs and restructuring lists for better clarity.
This commit is contained in:
David Snelling 2025-06-06 08:10:55 -07:00
parent 4c0922cb94
commit 783b40083f

View file

@ -1,6 +1,6 @@
<div align="center"> <div align="center">
# 🧠 Soulcraft Brainy # 🧠 Brainy
[![Version](https://img.shields.io/badge/version-0.7.4-blue.svg)](https://www.npmjs.com/package/@soulcraft/brainy) [![Version](https://img.shields.io/badge/version-0.7.4-blue.svg)](https://www.npmjs.com/package/@soulcraft/brainy)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE) [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
@ -12,29 +12,39 @@
## ✨ Overview ## ✨ Overview
Say hello to Brainy, your new favorite data sidekick! 🎉 Brainy combines the power of vector search with graph relationships in a lightweight, cross-platform database that's as smart as it is fun to use. Whether you're building AI applications, recommendation systems, or knowledge graphs, Brainy provides the tools you need to store, connect, and retrieve your data intelligently. Say hello to Brainy, your new favorite data sidekick! 🎉 Brainy combines the power of vector search with graph
relationships in a lightweight, cross-platform database that's as smart as it is fun to use. Whether you're building AI
applications, recommendation systems, or knowledge graphs, Brainy provides the tools you need to store, connect, and
retrieve your data intelligently.
What makes Brainy special? It intelligently adapts to you and your environment! Like a chameleon with a PhD, Brainy automatically detects your platform, adjusts its storage strategy, and optimizes performance based on your usage patterns. The more you use it, the smarter it gets - learning from your data to provide increasingly relevant results and connections. What makes Brainy special? It intelligently adapts to you and your environment! Like a chameleon with a PhD, Brainy
automatically detects your platform, adjusts its storage strategy, and optimizes performance based on your usage
patterns. The more you use it, the smarter it gets - learning from your data to provide increasingly relevant results
and connections.
### 🚀 Key Features ### 🚀 Key Features
- **Vector Search** - Find semantically similar content using embeddings (like having ESP for your data!) - **Vector Search** - Find semantically similar content using embeddings (like having ESP for your data!)
- **Graph Relationships** - Connect data with meaningful relationships (your data's social network) - **Graph Relationships** - Connect data with meaningful relationships (your data's social network)
- **Streaming Pipeline** - Process data in real-time as it flows through the system (like a data waterslide!) - **Streaming Pipeline** - Process data in real-time as it flows through the system (like a data waterslide!)
- **Extensible Augmentations** - Customize and extend functionality with pluggable components (LEGO blocks for your data!) - **Extensible Augmentations** - Customize and extend functionality with pluggable components (LEGO blocks for your
data!)
- **Adaptive Intelligence** - Automatically optimizes for your environment and usage patterns - **Adaptive Intelligence** - Automatically optimizes for your environment and usage patterns
- **Cross-Platform** - Works everywhere you do: browsers, Node.js, and server environments - **Cross-Platform** - Works everywhere you do: browsers, Node.js, and server environments
- **Persistent Storage** - Data persists across sessions and scales to any size (no memory loss here, even for elephant-sized data!) - **Persistent Storage** - Data persists across sessions and scales to any size (no memory loss here, even for
elephant-sized data!)
- **TypeScript Support** - Fully typed API with generics (for those who like their code tidy) - **TypeScript Support** - Fully typed API with generics (for those who like their code tidy)
- **CLI Tools** - Powerful command-line interface for data management (command line wizardry) - **CLI Tools** - Powerful command-line interface for data management (command line wizardry)
## 📊 What Can You Build? (The Fun Stuff!) ## 📊 What Can You Build? (The Fun Stuff!)
- **Semantic Search Engines** - Find content based on meaning, not just keywords (mind-reading for your data!) - **Semantic Search Engines** - Find content based on meaning, not just keywords (mind-reading for your data!)
- **Recommendation Systems** - Suggest similar items based on vector similarity (like a friend who really gets your taste) - **Recommendation Systems** - Suggest similar items based on vector similarity (like a friend who really gets your
taste)
- **Knowledge Graphs** - Build connected data structures with relationships (your data's family tree) - **Knowledge Graphs** - Build connected data structures with relationships (your data's family tree)
- **AI Applications** - Store and retrieve embeddings for machine learning models (brain food for your AI) - **AI Applications** - Store and retrieve embeddings for machine learning models (brain food for your AI)
- **Data Organization Tools** - Automatically categorize and connect related information (like having a librarian in your code) - **Data Organization Tools** - Automatically categorize and connect related information (like having a librarian in
your code)
- **Adaptive Experiences** - Create applications that learn and evolve with your users (digital chameleons!) - **Adaptive Experiences** - Create applications that learn and evolve with your users (digital chameleons!)
## 🔧 Installation ## 🔧 Installation
@ -81,13 +91,16 @@ await db.addVerb(catId, dogId, {
Brainy combines four key technologies to create its adaptive intelligence: Brainy combines four key technologies to create its adaptive intelligence:
1. **Vector Embeddings** - Converts data (text, images, etc.) into numerical vectors that capture semantic meaning (translating your data into brain-speak!) 1. **Vector Embeddings** - Converts data (text, images, etc.) into numerical vectors that capture semantic meaning (
2. **HNSW Algorithm** - Enables fast similarity search through a hierarchical graph structure (like a super-efficient treasure map for your data) translating your data into brain-speak!)
2. **HNSW Algorithm** - Enables fast similarity search through a hierarchical graph structure (like a super-efficient
treasure map for your data)
3. **Adaptive Environment Detection** - Automatically senses your platform and optimizes accordingly: 3. **Adaptive Environment Detection** - Automatically senses your platform and optimizes accordingly:
- Adjusts performance parameters based on available resources - Adjusts performance parameters based on available resources
- Learns from query patterns to optimize future searches - Learns from query patterns to optimize future searches
- Tunes itself for your specific use cases the more you use it - Tunes itself for your specific use cases the more you use it
4. **Intelligent Storage Selection** - Uses the best available storage option for your environment, scaling effortlessly to any data size (from bytes to petabytes!): 4. **Intelligent Storage Selection** - Uses the best available storage option for your environment, scaling effortlessly
to any data size (from bytes to petabytes!):
- Browser: Origin Private File System (OPFS) - Browser: Origin Private File System (OPFS)
- Node.js: File system - Node.js: File system
- Server: S3-compatible storage (optional) - Server: S3-compatible storage (optional)
@ -96,13 +109,15 @@ Brainy combines four key technologies to create its adaptive intelligence:
## 🚀 The Brainy Pipeline (Data's Wild Ride!) ## 🚀 The Brainy Pipeline (Data's Wild Ride!)
Brainy's data processing pipeline transforms raw data into searchable, connected knowledge that gets smarter over time. Here's how the magic happens: Brainy's data processing pipeline transforms raw data into searchable, connected knowledge that gets smarter over time.
Here's how the magic happens:
``` ```
Raw Data → Embedding → Vector Storage → Graph Connections → Adaptive Learning → Query & Retrieval Raw Data → Embedding → Vector Storage → Graph Connections → Adaptive Learning → Query & Retrieval
``` ```
Each time data flows through this pipeline, Brainy learns a little more about your usage patterns and environment, making future operations even faster and more relevant! Each time data flows through this pipeline, Brainy learns a little more about your usage patterns and environment,
making future operations even faster and more relevant!
### 🔄 Pipeline Stages (The Journey of Your Data) ### 🔄 Pipeline Stages (The Journey of Your Data)
@ -135,7 +150,8 @@ Each time data flows through this pipeline, Brainy learns a little more about yo
- Data is saved using the optimal storage for your environment (finds the coziest home for your data) - Data is saved using the optimal storage for your environment (finds the coziest home for your data)
- Automatic selection between OPFS, filesystem, S3, or memory (no manual configuration needed!) - Automatic selection between OPFS, filesystem, S3, or memory (no manual configuration needed!)
- Migrates between storage types as your application's needs evolve (moves houses without you noticing) - Migrates between storage types as your application's needs evolve (moves houses without you noticing)
- Scales effortlessly from tiny datasets to massive data collections (from ant-sized to elephant-sized data, no problem!) - Scales effortlessly from tiny datasets to massive data collections (from ant-sized to elephant-sized data, no
problem!)
- Configurable storage adapters for custom persistence needs (design your own dream data home) - Configurable storage adapters for custom persistence needs (design your own dream data home)
### 🧩 Augmentation Types ### 🧩 Augmentation Types
@ -299,6 +315,7 @@ Brainy uses a graph-based data model with two primary concepts:
### Nouns (Entities) ### Nouns (Entities)
The main entities in your data (nodes in the graph): The main entities in your data (nodes in the graph):
- Each noun has a unique ID, vector representation, and metadata - Each noun has a unique ID, vector representation, and metadata
- Nouns can be categorized by type (Person, Place, Thing, Event, Concept, etc.) - Nouns can be categorized by type (Person, Place, Thing, Event, Concept, etc.)
- Nouns are automatically vectorized for similarity search - Nouns are automatically vectorized for similarity search
@ -306,6 +323,7 @@ The main entities in your data (nodes in the graph):
### Verbs (Relationships) ### Verbs (Relationships)
Connections between nouns (edges in the graph): Connections between nouns (edges in the graph):
- Each verb connects a source noun to a target noun - Each verb connects a source noun to a target noun
- Verbs have types that define the relationship (RelatedTo, Controls, Contains, etc.) - Verbs have types that define the relationship (RelatedTo, Controls, Contains, etc.)
- Verbs can have their own metadata to describe the relationship - Verbs can have their own metadata to describe the relationship
@ -349,6 +367,7 @@ npm run cli generate-random-graph --noun-count 20 --verb-count 40
### 🔍 Available Commands ### 🔍 Available Commands
#### Basic Database Operations: #### Basic Database Operations:
- `init` - Initialize a new database - `init` - Initialize a new database
- `add <text> [metadata]` - Add a new noun with text and optional metadata - `add <text> [metadata]` - Add a new noun with text and optional metadata
- `search <query> [limit]` - Search for nouns similar to the query - `search <query> [limit]` - Search for nouns similar to the query
@ -363,6 +382,7 @@ npm run cli generate-random-graph --noun-count 20 --verb-count 40
- `completion-setup` - Setup shell autocomplete - `completion-setup` - Setup shell autocomplete
#### Pipeline and Augmentation Commands: #### Pipeline and Augmentation Commands:
- `list-augmentations` - List all available augmentation types and registered augmentations - `list-augmentations` - List all available augmentation types and registered augmentations
- `augmentation-info <type>` - Get detailed information about a specific augmentation type - `augmentation-info <type>` - Get detailed information about a specific augmentation type
- `test-pipeline [text]` - Test the sequential pipeline with sample data - `test-pipeline [text]` - Test the sequential pipeline with sample data