From 3860140c91e275d66d606a505a553920efded07d Mon Sep 17 00:00:00 2001 From: David Snelling Date: Fri, 20 Jun 2025 11:16:43 -0700 Subject: [PATCH] **docs: refine README for improved clarity and conciseness** ### Changes: - Updated the README to simplify descriptions and remove redundant details: - Reduced verbosity in feature highlights, focusing on core functionality. - Streamlined examples and usage sections for greater clarity. - Simplified installation and quick start instructions. - Removed overly casual or playful language to adopt a more professional tone. - Consolidated streaming, environment detection, and build system explanations. - Improved formatting consistency across sections: - Aligned headings, examples, and lists for readability. - Adjusted code indentation and structure in examples. ### Purpose: Enhanced the README to provide a concise, focused, and professional presentation of Brainy. These changes improve readability, simplify onboarding for new users, and ensure consistency with recent terminology and documentation standards. --- README.md | 359 ++++++++++++++++++++---------------------------------- 1 file changed, 135 insertions(+), 224 deletions(-) diff --git a/README.md b/README.md index 23689b7e..373dc338 100644 --- a/README.md +++ b/README.md @@ -14,44 +14,33 @@ ## ✨ 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. +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 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 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 -- **Run Everywhere** - Run Brainy in a browser, container, serverless cloud service or the terminal! -- **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) -- **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!) -- **Built-in Conduits** - Sync and scale across instances with WebSocket and WebRTC (your data's teleportation system!) -- **TensorFlow Integration** - Use TensorFlow.js for high-quality embeddings (included as a required dependency) +- **Run Everywhere** - Works in browsers, Node.js, serverless functions, and containers +- **Vector Search** - Find semantically similar content using embeddings +- **Graph Relationships** - Connect data with meaningful relationships +- **Streaming Pipeline** - Process data in real-time as it flows through the system +- **Extensible Augmentations** - Customize and extend functionality with pluggable components +- **Built-in Conduits** - Sync and scale across instances with WebSocket and WebRTC +- **TensorFlow Integration** - Use TensorFlow.js for high-quality embeddings - **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 - elephant-sized data!) -- **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) +- **Persistent Storage** - Data persists across sessions and scales to any size +- **TypeScript Support** - Fully typed API with generics +- **CLI Tools** - Powerful command-line interface for data management -## πŸ“Š What Can You Build? (The Fun Stuff!) +## πŸ“Š What Can You Build? -- **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) -- **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) +- **Semantic Search Engines** - Find content based on meaning, not just keywords +- **Recommendation Systems** - Suggest similar items based on vector similarity +- **Knowledge Graphs** - Build connected data structures with relationships +- **AI Applications** - Store and retrieve embeddings for machine learning models - **AI-Enhanced Applications** - Build applications that leverage vector embeddings for intelligent data processing -- **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!) +- **Data Organization Tools** - Automatically categorize and connect related information +- **Adaptive Experiences** - Create applications that learn and evolve with your users ## πŸ”§ Installation @@ -59,11 +48,7 @@ and connections. npm install @soulcraft/brainy ``` -### TensorFlow.js Support - -TensorFlow-based embeddings are now included as required dependencies. All necessary TensorFlow.js packages are automatically installed when you install Brainy. - -Note: If you encounter dependency conflicts with TensorFlow.js packages, 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 npm install @soulcraft/brainy --legacy-peer-deps @@ -71,13 +56,10 @@ npm install @soulcraft/brainy --legacy-peer-deps ## 🏁 Quick Start -Brainy now uses a unified build that automatically adapts to your environment (Node.js, browser, or serverless), so you can use the same code everywhere! +Brainy uses a unified build that automatically adapts to your environment (Node.js, browser, or serverless): ```typescript -import {BrainyData, NounType, VerbType, environment} from '@soulcraft/brainy' - -// Check which environment we're running in (optional) -console.log(`Running in ${environment.isBrowser ? 'browser' : environment.isNode ? 'Node.js' : 'serverless'} environment`) +import { BrainyData, NounType, VerbType } from '@soulcraft/brainy' // Create and initialize the database const db = new BrainyData() @@ -85,55 +67,46 @@ await db.init() // Add data (automatically converted to vectors) const catId = await db.add("Cats are independent pets", { - noun: NounType.Thing, - category: 'animal' + noun: NounType.Thing, + category: 'animal' }) const dogId = await db.add("Dogs are loyal companions", { - noun: NounType.Thing, - category: 'animal' + noun: NounType.Thing, + category: 'animal' }) // Search for similar items const results = await db.searchText("feline pets", 2) console.log(results) -// Returns items similar to "feline pets" with similarity scores // Add a relationship between items await db.addVerb(catId, dogId, { - verb: VerbType.RelatedTo, - description: 'Both are common household pets' + verb: VerbType.RelatedTo, + description: 'Both are common household pets' }) ``` -### Usage Options - -Brainy's unified build works in all environments, but you have several import options: +### Import Options ```typescript // Standard import - automatically adapts to any environment -import {BrainyData, NounType, VerbType, environment} from '@soulcraft/brainy' +import { BrainyData } from '@soulcraft/brainy' // Minified version for production -import {BrainyData, NounType, VerbType} from '@soulcraft/brainy/min' - -// Use the same API in any environment -const db = new BrainyData() -await db.init() -// ... +import { BrainyData } from '@soulcraft/brainy/min' ``` -#### Using a script tag in HTML +### Browser Usage ```html