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

81
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
@ -292,13 +300,13 @@ The pipeline runs automatically when you:
```typescript ```typescript
// Add data (runs embedding → indexing → storage) // Add data (runs embedding → indexing → storage)
const id = await db.add("Your text data here", {metadata}) const id = await db.add("Your text data here", { metadata })
// Search (runs embedding → similarity search) // Search (runs embedding → similarity search)
const results = await db.searchText("Your query here", 5) const results = await db.searchText("Your query here", 5)
// Connect entities (runs graph construction → storage) // Connect entities (runs graph construction → storage)
await db.addVerb(sourceId, targetId, {verb: VerbType.RelatedTo}) await db.addVerb(sourceId, targetId, { verb: VerbType.RelatedTo })
``` ```
Using the CLI: Using the CLI:
@ -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,20 +972,24 @@ 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 the noun-verb data model works - How Brainy runs in different environments (browser, Node.js, server, cloud)
- How HNSW search works - How the noun-verb data model works
- How HNSW search works
## Syncing Brainy Instances ## Syncing Brainy Instances
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
@ -993,7 +1014,7 @@ pipeline.register(wsConduit)
// Replace the example URL below with your actual WebSocket server URL // Replace the example URL below with your actual WebSocket server URL
const connectionResult = await pipeline.executeConduitPipeline( const connectionResult = await pipeline.executeConduitPipeline(
'establishConnection', 'establishConnection',
['wss://example-websocket-server.com/brainy-sync', {protocols: 'brainy-sync'}] ['wss://example-websocket-server.com/brainy-sync', { protocols: 'brainy-sync' }]
) )
if (connectionResult[0] && (await connectionResult[0]).success) { if (connectionResult[0] && (await connectionResult[0]).success) {
@ -1002,7 +1023,7 @@ if (connectionResult[0] && (await connectionResult[0]).success) {
// Read data from the remote instance // Read data from the remote instance
const readResult = await pipeline.executeConduitPipeline( const readResult = await pipeline.executeConduitPipeline(
'readData', 'readData',
[{connectionId: connection.connectionId, query: {type: 'getAllNouns'}}] [{ connectionId: connection.connectionId, query: { type: 'getAllNouns' } }]
) )
// Process and add the received data to the local instance // Process and add the received data to the local instance
@ -1053,7 +1074,7 @@ const connectionResult = await pipeline.executeConduitPipeline(
{ {
signalServerUrl: 'wss://example-signal-server.com', // Replace with your signal server signalServerUrl: 'wss://example-signal-server.com', // Replace with your signal server
localPeerId: 'my-local-peer-id', // Replace with your local peer ID localPeerId: 'my-local-peer-id', // Replace with your local peer ID
iceServers: [{urls: 'stun:stun.l.google.com:19302'}] // Public STUN server iceServers: [{ urls: 'stun:stun.l.google.com:19302' }] // Public STUN server
} }
] ]
) )
@ -1072,7 +1093,7 @@ if (connectionResult[0] && (await connectionResult[0]).success) {
}) })
// When adding new data locally, also send to the peer // When adding new data locally, also send to the peer
const nounId = await db.add("New data to sync", {noun: "Thing"}) const nounId = await db.add("New data to sync", { noun: "Thing" })
// Send the new noun to the peer // Send the new noun to the peer
await pipeline.executeConduitPipeline( await pipeline.executeConduitPipeline(
@ -1098,7 +1119,7 @@ Brainy supports searching a server-hosted instance from a browser, storing resul
searches against the local instance: searches against the local instance:
```typescript ```typescript
import {BrainyData} from '@soulcraft/brainy' import { BrainyData } from '@soulcraft/brainy'
// Create and initialize the database with remote server configuration // Create and initialize the database with remote server configuration
// Replace the example URL below with your actual Brainy server URL // Replace the example URL below with your actual Brainy server URL
@ -1118,13 +1139,13 @@ if (!db.isConnectedToRemoteServer()) {
} }
// Search the remote server (results are stored locally) // Search the remote server (results are stored locally)
const remoteResults = await db.searchText('machine learning', 5, {searchMode: 'remote'}) const remoteResults = await db.searchText('machine learning', 5, { searchMode: 'remote' })
// Search the local database (includes previously stored results) // Search the local database (includes previously stored results)
const localResults = await db.searchText('machine learning', 5, {searchMode: 'local'}) const localResults = await db.searchText('machine learning', 5, { searchMode: 'local' })
// Perform a combined search (local first, then remote if needed) // Perform a combined search (local first, then remote if needed)
const combinedResults = await db.searchText('neural networks', 5, {searchMode: 'combined'}) const combinedResults = await db.searchText('neural networks', 5, { searchMode: 'combined' })
// Add data to both local and remote instances // Add data to both local and remote instances
const id = await db.addToBoth('Deep learning is a subset of machine learning', { const id = await db.addToBoth('Deep learning is a subset of machine learning', {