soulcraft/brainy
2
0
Fork 0
Code Issues 1 Pull requests Projects Releases 335 Packages Wiki Activity Actions

**docs(readme): improve readability through line wrapping and formatting adjustments**

Browse source 
### Changes:
- Reformatted `README.md` for enhanced readability:
  - Applied line wrapping to long paragraphs and bullet points.
  - Adjusted spacing and indentation for consistent formatting.
  - Resolved issues with inconsistent code snippet alignments and metadata formatting.

### Purpose:
Improved the readability and maintainability of the README by standardizing formatting and wrapping long lines. These changes ensure better clarity for users exploring the documentation.
This commit is contained in:
David Snelling 2025-06-20 14:15:53 -07:00
parent baf5e41877
commit 0fec77057a
2 changed files with 181 additions and 160 deletions
Download patch file Download diff file Expand all files Collapse all files

2
.github/workflows/github-pages.yml vendored
View file

@ -24,7 +24,7 @@ jobs:
uses: actions/configure-pages@v4 uses: actions/configure-pages@v4
- name: Upload artifact - name: Upload artifact
uses: actions/upload-pages-artifact@v4 uses: actions/upload-pages-artifact@v3
with: with:
path: './examples' # Upload the examples directory path: './examples' # Upload the examples directory

55
README.md
View file

@ -14,9 +14,13 @@
## ✨ Overview ## ✨ Overview
Brainy combines the power of vector search with graph relationships in a lightweight, cross-platform database. 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. Brainy combines the power of vector search with graph relationships in a lightweight, cross-platform database. 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 your environment! 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 your environment! 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
@ -31,7 +35,8 @@ What makes Brainy special? It intelligently adapts to your environment! Brainy a
- **Persistent Storage** - Data persists across sessions and scales to any size - **Persistent Storage** - Data persists across sessions and scales to any size
- **TypeScript Support** - Fully typed API with generics - **TypeScript Support** - Fully typed API with generics
- **CLI Tools** - Powerful command-line interface for data management - **CLI Tools** - Powerful command-line interface for data management
- **Model Control Protocol (MCP)** - Allow external AI models to access Brainy data and use augmentation pipeline as tools - **Model Control Protocol (MCP)** - Allow external AI models to access Brainy data and use augmentation pipeline as
tools
## 📊 What Can You Build? ## 📊 What Can You Build?
@ -50,7 +55,8 @@ What makes Brainy special? It intelligently adapts to your environment! Brainy a
npm install @soulcraft/brainy npm install @soulcraft/brainy
``` ```
TensorFlow.js packages are included as required dependencies and will be automatically installed. If you encounter dependency conflicts, you may need to use the `--legacy-peer-deps` flag: TensorFlow.js packages are included as required dependencies and will be automatically installed. If you encounter
dependency conflicts, you may need to use the `--legacy-peer-deps` flag:
```bash ```bash
npm install @soulcraft/brainy --legacy-peer-deps npm install @soulcraft/brainy --legacy-peer-deps
@ -102,6 +108,7 @@ import { BrainyData } from '@soulcraft/brainy/min'
### Browser Usage ### Browser Usage
```html ```html
<script type="module"> <script type="module">
// Use the CDN to load the unified build // Use the CDN to load the unified build
import { BrainyData } from 'https://cdn.jsdelivr.net/npm/@soulcraft/brainy/dist/unified.js' import { BrainyData } from 'https://cdn.jsdelivr.net/npm/@soulcraft/brainy/dist/unified.js'
@ -144,7 +151,8 @@ Brainy's data processing pipeline transforms raw data into searchable, connected
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 more about your usage patterns and environment, making future operations faster and more relevant. Each time data flows through this pipeline, Brainy learns more about your usage patterns and environment, making future
operations faster and more relevant.
### Pipeline Stages ### Pipeline Stages
@ -460,7 +468,6 @@ npm run cli generate-random-graph --noun-count 20 --verb-count 40
- `-t, --data-type <type>` - Type of data to process (default: 'text') - `-t, --data-type <type>` - Type of data to process (default: 'text')
- `-v, --verbose` - Show detailed output - `-v, --verbose` - Show detailed output
## API Reference ## API Reference
### Database Management ### Database Management
@ -539,7 +546,6 @@ const verb = await db.getVerb(verbId)
await db.deleteVerb(verbId) await db.deleteVerb(verbId)
``` ```
## Advanced Configuration ## Advanced Configuration
### Embedding ### Embedding
@ -596,7 +602,8 @@ const db = new BrainyData({
### Optimized HNSW for Large Datasets ### Optimized HNSW for Large Datasets
Brainy includes an optimized HNSW index implementation for large datasets that may not fit entirely in memory, using a hybrid approach: Brainy includes an optimized HNSW index implementation for large datasets that may not fit entirely in memory, using a
hybrid approach:
1. **Product Quantization** - Reduces vector dimensionality while preserving similarity relationships 1. **Product Quantization** - Reduces vector dimensionality while preserving similarity relationships
2. **Disk-Based Storage** - Offloads vectors to disk when memory usage exceeds a threshold 2. **Disk-Based Storage** - Offloads vectors to disk when memory usage exceeds a threshold
@ -653,6 +660,7 @@ console.log(status.details.index)
## Backup and Restore ## Backup and Restore
Brainy provides backup and restore capabilities that allow you to: Brainy provides backup and restore capabilities that allow you to:
- Back up your data - Back up your data
- Transfer data between Brainy instances - Transfer data between Brainy instances
- Restore existing data into Brainy for vectorization and indexing - Restore existing data into Brainy for vectorization and indexing
@ -673,12 +681,14 @@ const backupData = await db.backup()
// Save the backup data to a file (Node.js environment) // Save the backup data to a file (Node.js environment)
import fs from 'fs' import fs from 'fs'
fs.writeFileSync('brainy-backup.json', JSON.stringify(backupData, null, 2)) fs.writeFileSync('brainy-backup.json', JSON.stringify(backupData, null, 2))
``` ```
### Restoring Data ### Restoring Data
Brainy's restore functionality can handle: Brainy's restore functionality can handle:
1. Complete backups with vectors and index data 1. Complete backups with vectors and index data
2. Sparse data without vectors (vectors will be created during restore) 2. Sparse data without vectors (vectors will be created during restore)
3. Data without HNSW index (index will be reconstructed if needed) 3. Data without HNSW index (index will be reconstructed if needed)
@ -742,7 +752,8 @@ Brainy includes an augmentation system for extending functionality:
### Simplified Augmentation System ### Simplified Augmentation System
Brainy provides a simplified factory system for creating, importing, and executing augmentations with minimal boilerplate: Brainy provides a simplified factory system for creating, importing, and executing augmentations with minimal
boilerplate:
```typescript ```typescript
import { import {
@ -849,7 +860,8 @@ For a complete example, see [examples/simplified-augmentations.js](examples/simp
### Model Control Protocol (MCP) ### Model Control Protocol (MCP)
Brainy includes a Model Control Protocol (MCP) implementation that allows external models to access Brainy data and use the augmentation pipeline as tools: Brainy includes a Model Control Protocol (MCP) implementation that allows external models to access Brainy data and use
the augmentation pipeline as tools:
- **BrainyMCPAdapter**: Provides access to Brainy data through MCP - **BrainyMCPAdapter**: Provides access to Brainy data through MCP
- **MCPAugmentationToolset**: Exposes the augmentation pipeline as tools - **MCPAugmentationToolset**: Exposes the augmentation pipeline as tools
@ -858,13 +870,16 @@ Brainy includes a Model Control Protocol (MCP) implementation that allows extern
Environment compatibility: Environment compatibility:
- **BrainyMCPAdapter** and **MCPAugmentationToolset** can run in any environment (browser, Node.js, server) - **BrainyMCPAdapter** and **MCPAugmentationToolset** can run in any environment (browser, Node.js, server)
- **BrainyMCPService** core functionality works in any environment, but server functionality (WebSocket/REST) is in the cloud-wrapper project - **BrainyMCPService** core functionality works in any environment, but server functionality (WebSocket/REST) is in the
cloud-wrapper project
For detailed documentation and usage examples, see the [MCP documentation](src/mcp/README.md). For detailed documentation and usage examples, see the [MCP documentation](src/mcp/README.md).
## Cross-Environment Compatibility ## Cross-Environment Compatibility
Brainy is designed to run seamlessly in any environment, from browsers to Node.js to serverless functions and containers. All Brainy data, functions, and augmentations are environment-agnostic, allowing you to use the same code everywhere. Brainy is designed to run seamlessly in any environment, from browsers to Node.js to serverless functions and
containers. All Brainy data, functions, and augmentations are environment-agnostic, allowing you to use the same code
everywhere.
### Environment Detection ### Environment Detection
@ -892,7 +907,8 @@ Storage adapters are automatically selected based on the environment:
### Dynamic Imports ### Dynamic Imports
Brainy uses dynamic imports to load environment-specific dependencies only when needed, keeping the bundle size small and ensuring compatibility across environments. Brainy uses dynamic imports to load environment-specific dependencies only when needed, keeping the bundle size small
and ensuring compatibility across environments.
### Browser Support ### Browser Support
@ -943,7 +959,8 @@ npm run deploy:cloud:cloudflare
npm run deploy:cloud npm run deploy:cloud
``` ```
Before deploying, make sure to configure the appropriate environment variables in the `cloud-wrapper/.env` file. See the [Cloud Wrapper README](cloud-wrapper/README.md) for detailed configuration instructions and API documentation. Before deploying, make sure to configure the appropriate environment variables in the `cloud-wrapper/.env` file. See
the [Cloud Wrapper README](cloud-wrapper/README.md) for detailed configuration instructions and API documentation.
## Related Projects ## Related Projects
@ -955,10 +972,12 @@ Before deploying, make sure to configure the appropriate environment variables i
The repository includes a comprehensive demo that showcases Brainy's main features: The repository includes a comprehensive demo that showcases Brainy's main features:
- `examples/demo.html` - A single demo page with animations demonstrating Brainy's features. - `examples/demo.html` - A single demo page with animations demonstrating Brainy's features.
- **[Try the live demo](https://soulcraft.github.io/brainy/examples/demo.html)** - Check out the interactive demo on GitHub Pages - **[Try the live demo](https://soulcraft.github.io/brainy/examples/demo.html)** - Check out the interactive demo on
GitHub Pages
- Or run it locally with `npm run demo` (see [demo instructions](README.demo.md) for details) - Or run it locally with `npm run demo` (see [demo instructions](README.demo.md) for details)
The demo showcases: The demo showcases:
- How Brainy runs in different environments (browser, Node.js, server, cloud) - How Brainy runs in different environments (browser, Node.js, server, cloud)
- How the noun-verb data model works - How the noun-verb data model works
- How HNSW search works - How HNSW search works
@ -967,8 +986,10 @@ The demo showcases:
You can use the conduit augmentations to sync Brainy instances: You can use the conduit augmentations to sync Brainy instances:
- **WebSocket iConduit**: 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. - **WebSocket iConduit**: For syncing between browsers and servers, or between servers. WebSockets cannot be used for
- **WebRTC iConduit**: For direct peer-to-peer syncing between browsers. This is the recommended approach for browser-to-browser communication. direct browser-to-browser communication without a server in the middle.
- **WebRTC iConduit**: For direct peer-to-peer syncing between browsers. This is the recommended approach for
browser-to-browser communication.
#### WebSocket Sync Example #### WebSocket Sync Example