chore: update README.md and docs with Brainy logo and enhanced formatting
Standardized documentation by adding a centered Brainy logo across README files, examples, and guides. Adjusted text formatting for consistency, improved alignment, and readability of feature descriptions and examples.
This commit is contained in:
parent
21ae491913
commit
0b7b3f947b
11 changed files with 739 additions and 655 deletions
|
|
@ -1,11 +1,17 @@
|
|||
<div align="center">
|
||||
<img src="brainy.png" alt="Brainy Logo" width="200"/>
|
||||
|
||||
# Contributing to Soulcraft Brainy
|
||||
|
||||
</div>
|
||||
|
||||
Thank you for your interest in contributing to Soulcraft Brainy! This document provides guidelines and instructions for
|
||||
contributing to the project.
|
||||
|
||||
## Commit Message Guidelines
|
||||
|
||||
When contributing to this project, please write clear and descriptive commit messages that explain the purpose of your changes. Good commit messages help maintainers understand your contributions and make the review process smoother.
|
||||
When contributing to this project, please write clear and descriptive commit messages that explain the purpose of your
|
||||
changes. Good commit messages help maintainers understand your contributions and make the review process smoother.
|
||||
|
||||
### Best Practices
|
||||
|
||||
|
|
|
|||
54
README.md
54
README.md
|
|
@ -1,14 +1,11 @@
|
|||
<div align="center">
|
||||
|
||||
# 🧠 Brainy
|
||||
<img src="brainy.png" alt="Brainy Logo" width="200"/>
|
||||
|
||||
[](LICENSE)
|
||||
[](https://nodejs.org/)
|
||||
[](https://www.typescriptlang.org/)
|
||||
[](https://www.npmjs.com/package/@soulcraft/brainy)
|
||||
[](CONTRIBUTING.md)
|
||||
[](https://github.com/prettier/prettier)
|
||||
[](https://www.tensorflow.org/)
|
||||
[](https://github.com/sodal-project/cartographer)
|
||||
|
||||
**A powerful, lightweight vector & graph database for browsers and Node.js**
|
||||
|
|
@ -35,7 +32,8 @@ and connections.
|
|||
- **Extensible Augmentations** - Customize and extend functionality with pluggable components (LEGO blocks for your
|
||||
data!)
|
||||
- **Built-in Conduits** - Sync and scale across instances with WebSocket and WebRTC (your data's teleportation system!)
|
||||
- **LLM Creation & Training** - Build, train, and deploy language models from your graph data (your own personal AI factory!)
|
||||
- **LLM Creation & Training** - Build, train, and deploy language models from your graph data (your own personal AI
|
||||
factory!)
|
||||
- **Adaptive Intelligence** - Automatically optimizes for your environment and usage patterns
|
||||
- **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
|
||||
|
|
@ -188,8 +186,10 @@ Brainy uses a powerful augmentation system to extend functionality. Augmentation
|
|||
- Establishes high-bandwidth channels for structured data exchange
|
||||
- Connects with external systems and syncs between Brainy instances
|
||||
- Two built-in iConduit augmentations for scaling out and syncing:
|
||||
- **WebSocket iConduit** - Syncs data between browsers and servers (like a digital postal service with superpowers!)
|
||||
- **WebRTC iConduit** - Direct peer-to-peer syncing between browsers (like telepathy for your data, no middleman required!)
|
||||
- **WebSocket iConduit** - Syncs data between browsers and servers (like a digital postal service with
|
||||
superpowers!)
|
||||
- **WebRTC iConduit** - Direct peer-to-peer syncing between browsers (like telepathy for your data, no middleman
|
||||
required!)
|
||||
- Examples:
|
||||
- Integrating with third-party APIs
|
||||
- Syncing Brainy instances between browsers using WebSockets
|
||||
|
|
@ -524,10 +524,10 @@ await db.deleteVerb(verbId)
|
|||
### Working with LLM Models
|
||||
|
||||
```typescript
|
||||
import { createLLMAugmentations } from '@soulcraft/brainy'
|
||||
import {createLLMAugmentations} from '@soulcraft/brainy'
|
||||
|
||||
// Create LLM augmentations
|
||||
const { cognition, activation } = await createLLMAugmentations()
|
||||
const {cognition, activation} = await createLLMAugmentations()
|
||||
|
||||
// Create a new LLM model
|
||||
const createResult = await cognition.createModel({
|
||||
|
|
@ -682,9 +682,11 @@ Brainy can be deployed as a standalone web service on various cloud platforms us
|
|||
- **Google Cloud Run**: Deploy as a containerized service
|
||||
- **Cloudflare Workers**: Deploy as a serverless function on the edge
|
||||
|
||||
The cloud wrapper provides both RESTful and WebSocket APIs for all Brainy operations, enabling both request-response and real-time communication patterns. It supports multiple storage backends and can be configured via environment variables.
|
||||
The cloud wrapper provides both RESTful and WebSocket APIs for all Brainy operations, enabling both request-response and
|
||||
real-time communication patterns. It supports multiple storage backends and can be configured via environment variables.
|
||||
|
||||
Key features of the cloud wrapper:
|
||||
|
||||
- RESTful API for standard CRUD operations
|
||||
- WebSocket API for real-time updates and subscriptions
|
||||
- Support for multiple storage backends (Memory, FileSystem, S3)
|
||||
|
|
@ -695,7 +697,8 @@ To get started with cloud deployment, see the [Cloud Wrapper README](cloud-wrapp
|
|||
|
||||
## 🔗 Related Projects
|
||||
|
||||
- **[sodal-project cartographer](https://github.com/sodal-project/cartographer)** - The defacto standard for interacting with Brainy
|
||||
- **[sodal-project cartographer](https://github.com/sodal-project/cartographer)** - The defacto standard for interacting
|
||||
with Brainy
|
||||
|
||||
## 📚 Examples
|
||||
|
||||
|
|
@ -712,8 +715,11 @@ The repository includes several examples:
|
|||
|
||||
You can use the conduit augmentations to sync Brainy instances:
|
||||
|
||||
- **WebSocket iConduit**: For syncing between browsers and servers, or between servers (like a digital postal service with superpowers!). WebSockets cannot be used for direct browser-to-browser communication without a server in the middle.
|
||||
- **WebRTC iConduit**: For direct peer-to-peer syncing between browsers (like telepathy for your data, no middleman required!). This is the recommended approach for browser-to-browser communication.
|
||||
- **WebSocket iConduit**: For syncing between browsers and servers, or between servers (like a digital postal service
|
||||
with superpowers!). WebSockets cannot be used for direct browser-to-browser communication without a server in the
|
||||
middle.
|
||||
- **WebRTC iConduit**: For direct peer-to-peer syncing between browsers (like telepathy for your data, no middleman
|
||||
required!). This is the recommended approach for browser-to-browser communication.
|
||||
|
||||
#### WebSocket Sync Example
|
||||
|
||||
|
|
@ -737,7 +743,7 @@ augmentationPipeline.register(wsConduit)
|
|||
// Connect to another Brainy instance (server or browser)
|
||||
const connectionResult = await augmentationPipeline.executeConduitPipeline(
|
||||
'establishConnection',
|
||||
['wss://your-websocket-server.com/brainy-sync', { protocols: 'brainy-sync' }]
|
||||
['wss://your-websocket-server.com/brainy-sync', {protocols: 'brainy-sync'}]
|
||||
)
|
||||
|
||||
if (connectionResult[0] && (await connectionResult[0]).success) {
|
||||
|
|
@ -746,7 +752,7 @@ if (connectionResult[0] && (await connectionResult[0]).success) {
|
|||
// Read data from the remote instance
|
||||
const readResult = await augmentationPipeline.executeConduitPipeline(
|
||||
'readData',
|
||||
[{ connectionId: connection.connectionId, query: { type: 'getAllNouns' } }]
|
||||
[{connectionId: connection.connectionId, query: {type: 'getAllNouns'}}]
|
||||
)
|
||||
|
||||
// Process and add the received data to the local instance
|
||||
|
|
@ -796,7 +802,7 @@ const connectionResult = await augmentationPipeline.executeConduitPipeline(
|
|||
{
|
||||
signalServerUrl: 'wss://your-signal-server.com',
|
||||
localPeerId: 'my-peer-id',
|
||||
iceServers: [{ urls: 'stun:stun.l.google.com:19302' }]
|
||||
iceServers: [{urls: 'stun:stun.l.google.com:19302'}]
|
||||
}
|
||||
]
|
||||
)
|
||||
|
|
@ -815,7 +821,7 @@ if (connectionResult[0] && (await connectionResult[0]).success) {
|
|||
})
|
||||
|
||||
// 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
|
||||
await augmentationPipeline.executeConduitPipeline(
|
||||
|
|
@ -837,10 +843,11 @@ if (connectionResult[0] && (await connectionResult[0]).success) {
|
|||
|
||||
#### Browser-Server Search Example
|
||||
|
||||
Brainy supports searching a server-hosted instance from a browser, storing results locally, and performing further searches against the local instance:
|
||||
Brainy supports searching a server-hosted instance from a browser, storing results locally, and performing further
|
||||
searches against the local instance:
|
||||
|
||||
```typescript
|
||||
import { BrainyData } from '@soulcraft/brainy'
|
||||
import {BrainyData} from '@soulcraft/brainy'
|
||||
|
||||
// Create and initialize the database with remote server configuration
|
||||
const db = new BrainyData({
|
||||
|
|
@ -858,13 +865,13 @@ if (!db.isConnectedToRemoteServer()) {
|
|||
}
|
||||
|
||||
// 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)
|
||||
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)
|
||||
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
|
||||
const id = await db.addToBoth('Deep learning is a subset of machine learning', {
|
||||
|
|
@ -934,7 +941,8 @@ Brainy follows a specific code style to maintain consistency throughout the code
|
|||
- Reference issues and pull requests where appropriate
|
||||
- Provide detailed explanations in the commit body when necessary
|
||||
|
||||
When contributing to the project, please ensure your code follows these guidelines. The project's CI/CD pipeline will automatically check for style violations.
|
||||
When contributing to the project, please ensure your code follows these guidelines. The project's CI/CD pipeline will
|
||||
automatically check for style violations.
|
||||
|
||||
### Development Workflow
|
||||
|
||||
|
|
|
|||
BIN
brainy.png
Normal file
BIN
brainy.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 2.4 MiB |
|
|
@ -1,4 +1,8 @@
|
|||
<div align="center">
|
||||
<img src="../brainy.png" alt="Brainy Logo" width="200"/>
|
||||
|
||||
# Brainy Cloud Wrapper
|
||||
</div>
|
||||
|
||||
A standalone web service wrapper for the [Brainy](https://github.com/soulcraft/brainy) vector graph database. This wrapper allows you to deploy Brainy as a RESTful API service on various cloud platforms including AWS, Google Cloud, and Cloudflare.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,4 +1,8 @@
|
|||
<div align="center">
|
||||
<img src="../brainy.png" alt="Brainy Logo" width="200"/>
|
||||
|
||||
# Build-Time Augmentation Registration
|
||||
</div>
|
||||
|
||||
This document explains how to register custom augmentations at build time using the Brainy library's augmentation
|
||||
registry system.
|
||||
|
|
|
|||
|
|
@ -1,4 +1,8 @@
|
|||
<div align="center">
|
||||
<img src="../brainy.png" alt="Brainy Logo" width="200"/>
|
||||
|
||||
# LLM Augmentation for Brainy
|
||||
</div>
|
||||
|
||||
This document describes the LLM (Language Learning Model) augmentation for Brainy, which enables creating, training, testing, exporting, and deploying language models from the data in Brainy's graph database.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,4 +1,8 @@
|
|||
<div align="center">
|
||||
<img src="../brainy.png" alt="Brainy Logo" width="200"/>
|
||||
|
||||
# Brainy Examples
|
||||
</div>
|
||||
|
||||
This directory contains examples demonstrating various features and use cases of the Brainy vector graph database.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,4 +1,8 @@
|
|||
<div align="center">
|
||||
<img src="../../brainy.png" alt="Brainy Logo" width="200"/>
|
||||
|
||||
# Brainy Browser-Server Search Example
|
||||
</div>
|
||||
|
||||
This example demonstrates how to use Brainy in a browser, call a server-hosted version for search, store the results locally, and then perform further searches against the local instance.
|
||||
|
||||
|
|
|
|||
|
|
@ -59,7 +59,10 @@
|
|||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<div style="display: flex; align-items: center; margin-bottom: 20px;">
|
||||
<img src="../../brainy.png" alt="Brainy Logo" width="100" style="margin-right: 20px;"/>
|
||||
<h1>Brainy Browser-Server Search Example</h1>
|
||||
</div>
|
||||
|
||||
<p>
|
||||
This example demonstrates how to use Brainy in a browser, call a server-hosted version for search,
|
||||
|
|
|
|||
|
|
@ -12,9 +12,11 @@
|
|||
padding: 20px;
|
||||
line-height: 1.6;
|
||||
}
|
||||
|
||||
h1, h2 {
|
||||
color: #4361ee;
|
||||
}
|
||||
|
||||
button {
|
||||
background-color: #4361ee;
|
||||
color: white;
|
||||
|
|
@ -24,34 +26,41 @@
|
|||
cursor: pointer;
|
||||
margin: 5px 0;
|
||||
}
|
||||
|
||||
button:hover {
|
||||
background-color: #3a56d4;
|
||||
}
|
||||
|
||||
button:disabled {
|
||||
background-color: #cccccc;
|
||||
cursor: not-allowed;
|
||||
}
|
||||
|
||||
pre {
|
||||
background-color: #f5f5f5;
|
||||
padding: 10px;
|
||||
border-radius: 4px;
|
||||
overflow-x: auto;
|
||||
}
|
||||
|
||||
.container {
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
gap: 20px;
|
||||
}
|
||||
|
||||
.panel {
|
||||
border: 1px solid #ddd;
|
||||
border-radius: 4px;
|
||||
padding: 15px;
|
||||
}
|
||||
|
||||
.search-container {
|
||||
display: flex;
|
||||
gap: 10px;
|
||||
margin-bottom: 10px;
|
||||
}
|
||||
|
||||
input, select {
|
||||
padding: 8px;
|
||||
border: 1px solid #ddd;
|
||||
|
|
@ -60,10 +69,14 @@
|
|||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<div style="display: flex; align-items: center; margin-bottom: 20px;">
|
||||
<img src="../brainy.png" alt="Brainy Logo" width="100" style="margin-right: 20px;"/>
|
||||
<h1>Brainy - Vector and Graph Database Demo</h1>
|
||||
<p>This demo shows how to use Brainy as both a vector database (with embeddings and similarity search) and a graph database (with GraphNoun nodes and GraphVerb relationships).</p>
|
||||
</div>
|
||||
<p>This demo shows how to use Brainy as both a vector database (with embeddings and similarity search) and a graph
|
||||
database (with GraphNoun nodes and GraphVerb relationships).</p>
|
||||
|
||||
<div class="container">
|
||||
<div class="container">
|
||||
<div class="panel">
|
||||
<h2>1. Initialize Database</h2>
|
||||
<button id="initBtn">Initialize BrainyData</button>
|
||||
|
|
@ -117,9 +130,9 @@
|
|||
<h2>Console Output</h2>
|
||||
<pre id="output">// Output will appear here</pre>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<script type="importmap">
|
||||
<script type="importmap">
|
||||
{
|
||||
"imports": {
|
||||
"uuid": "https://cdn.jsdelivr.net/npm/uuid@9.0.0/dist/esm-browser/index.js",
|
||||
|
|
@ -130,9 +143,9 @@
|
|||
"@tensorflow/tfjs-backend-cpu": "https://cdn.jsdelivr.net/npm/@tensorflow/tfjs-backend-cpu/dist/tf-backend-cpu.esm.js"
|
||||
}
|
||||
}
|
||||
</script>
|
||||
</script>
|
||||
|
||||
<script type="module">
|
||||
<script type="module">
|
||||
// Import the necessary components from Brainy
|
||||
import {
|
||||
BrainyData,
|
||||
|
|
@ -326,7 +339,7 @@
|
|||
// Example memory augmentation
|
||||
{
|
||||
plugin: 'memory-augmentation',
|
||||
config: { storageType: 'persistent' },
|
||||
config: {storageType: 'persistent'},
|
||||
type: AugmentationType.MEMORY
|
||||
}
|
||||
], {
|
||||
|
|
@ -466,12 +479,42 @@
|
|||
|
||||
// Define relationships to create
|
||||
const relationships = [
|
||||
{ source: 'cat', target: 'dog', type: VerbType.Controls, metadata: { description: 'Cats often dominate dogs in households' } },
|
||||
{ source: 'tiger', target: 'cat', type: 'relatedTo', metadata: { description: 'Tigers are related to domestic cats' } },
|
||||
{ source: 'lion', target: 'tiger', type: VerbType.Controls, metadata: { description: 'Lions are often dominant over tigers in shared territories' } },
|
||||
{ source: 'shark', target: 'fish', type: VerbType.Controls, metadata: { description: 'Sharks are predators of many fish species' } },
|
||||
{ source: 'eagle', target: 'bird', type: 'relatedTo', metadata: { description: 'Eagles are a type of bird' } },
|
||||
{ source: 'eagle', target: 'fish', type: VerbType.Controls, metadata: { description: 'Eagles hunt and eat fish' } }
|
||||
{
|
||||
source: 'cat',
|
||||
target: 'dog',
|
||||
type: VerbType.Controls,
|
||||
metadata: {description: 'Cats often dominate dogs in households'}
|
||||
},
|
||||
{
|
||||
source: 'tiger',
|
||||
target: 'cat',
|
||||
type: 'relatedTo',
|
||||
metadata: {description: 'Tigers are related to domestic cats'}
|
||||
},
|
||||
{
|
||||
source: 'lion',
|
||||
target: 'tiger',
|
||||
type: VerbType.Controls,
|
||||
metadata: {description: 'Lions are often dominant over tigers in shared territories'}
|
||||
},
|
||||
{
|
||||
source: 'shark',
|
||||
target: 'fish',
|
||||
type: VerbType.Controls,
|
||||
metadata: {description: 'Sharks are predators of many fish species'}
|
||||
},
|
||||
{
|
||||
source: 'eagle',
|
||||
target: 'bird',
|
||||
type: 'relatedTo',
|
||||
metadata: {description: 'Eagles are a type of bird'}
|
||||
},
|
||||
{
|
||||
source: 'eagle',
|
||||
target: 'fish',
|
||||
type: VerbType.Controls,
|
||||
metadata: {description: 'Eagles hunt and eat fish'}
|
||||
}
|
||||
];
|
||||
|
||||
// Create each relationship
|
||||
|
|
@ -544,6 +587,6 @@
|
|||
|
||||
// Initial log message
|
||||
log('Welcome to the Brainy Vector Search Demo!\nClick "Initialize BrainyData" to begin.');
|
||||
</script>
|
||||
</script>
|
||||
</body>
|
||||
</html>
|
||||
|
|
|
|||
|
|
@ -1,4 +1,8 @@
|
|||
<div align="center">
|
||||
<img src="../../brainy.png" alt="Brainy Logo" width="200"/>
|
||||
|
||||
# Brainy Augmentations
|
||||
</div>
|
||||
|
||||
This directory contains the augmentation implementations for Brainy. Augmentations are pluggable components that extend Brainy's functionality in various ways.
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue