From 8508cfc97dc252b45dd444b3d8236c89f22eec9f Mon Sep 17 00:00:00 2001 From: David Snelling Date: Mon, 22 Sep 2025 16:19:27 -0700 Subject: [PATCH] docs: update documentation for accurate v3.9.0 API examples and technical claims MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Fix all API examples to use proper enum syntax (NounType.Concept vs "concept") - Correct noun/verb type counts (31 noun types × 40 verb types = 1,240 combinations) - Update package references from 'brainy' to '@soulcraft/brainy' - Standardize version references to be version-agnostic - Ensure all examples match actual v3.9.0 implementation - Add proper TypeScript imports throughout documentation --- README.md | 54 +++++++++++++++---------------- docs/QUICK-START.md | 21 ++++++------ docs/features/v3-features.md | 4 +-- docs/guides/distributed-system.md | 2 +- docs/guides/getting-started.md | 4 +-- 5 files changed, 43 insertions(+), 42 deletions(-) diff --git a/README.md b/README.md index fbe4d203..c809ef6b 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) [![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](https://www.typescriptlang.org/) -**🧠 Brainy 3.0 - Universal Knowledge Protocol™** +**🧠 Brainy - Universal Knowledge Protocol™** **World's first Triple Intelligence™ database** unifying vector similarity, graph relationships, and document filtering in one magical API. **Framework-friendly design** works seamlessly with Next.js, React, Vue, Angular, and any modern JavaScript framework. @@ -17,7 +17,7 @@ **Framework-first design.** Built for modern web development with zero configuration and automatic framework compatibility. O(log n) performance, <10ms search latency, production-ready. -## 🎉 What's New in 3.0 +## 🎉 Key Features ### 🧠 **Triple Intelligence™ Engine** @@ -49,7 +49,7 @@ npm install @soulcraft/brainy ### 🎯 **True Zero Configuration** ```javascript -import {Brainy} from '@soulcraft/brainy' +import { Brainy, NounType } from '@soulcraft/brainy' // Just this - auto-detects everything! const brain = new Brainy() @@ -58,7 +58,7 @@ await brain.init() // Add entities with automatic embedding const jsId = await brain.add({ data: "JavaScript is a programming language", - type: "concept", + nounType: NounType.Concept, metadata: { type: "language", year: 1995, @@ -68,7 +68,7 @@ const jsId = await brain.add({ const nodeId = await brain.add({ data: "Node.js runtime environment", - type: "concept", + nounType: NounType.Concept, metadata: { type: "runtime", year: 2009, @@ -100,7 +100,7 @@ const filtered = await brain.find({ ## 🌐 Framework Integration -**Brainy 3.0 is framework-first!** Works seamlessly with any modern JavaScript framework: +**Brainy is framework-first!** Works seamlessly with any modern JavaScript framework: ### ⚛️ **React & Next.js** ```javascript @@ -194,7 +194,7 @@ If using nvm: `nvm use` (we provide a `.nvmrc` file) **Enabled by Triple Intelligence, standardized for everyone:** -- **24 Noun Types × 40 Verb Types**: 960 base combinations +- **31 Noun Types × 40 Verb Types**: 1,240 base combinations - **∞ Expressiveness**: Unlimited metadata = model ANY data - **One Language**: All tools, augmentations, AI models speak the same types - **Perfect Interoperability**: Move data between any Brainy instance @@ -211,10 +211,10 @@ await brain.find("Documentation about authentication from last month") ### 🎯 Zero Configuration Philosophy -Brainy 3.0 automatically configures **everything**: +Brainy automatically configures **everything**: ```javascript -import {Brainy} from '@soulcraft/brainy' +import { Brainy } from '@soulcraft/brainy' // 1. Pure zero-config - detects everything const brain = new Brainy() @@ -368,6 +368,8 @@ const brain = new Brainy({ ### Real-World Example: Social Media Firehose ```javascript +import { Brainy, NounType } from '@soulcraft/brainy' + // Ingestion nodes (optimized for writes) const ingestionNode = new Brainy({ storage: {type: 's3', options: {bucket: 'social-data'}}, @@ -378,7 +380,7 @@ const ingestionNode = new Brainy({ // Process Bluesky firehose blueskyStream.on('post', async (post) => { await ingestionNode.add(post, { - nounType: 'social-post', + nounType: NounType.Message, platform: 'bluesky', author: post.author, timestamp: post.createdAt @@ -417,21 +419,19 @@ const trending = await searchNode.find('trending AI topics', { ```javascript // Store documentation with rich relationships const apiGuide = await brain.add("REST API Guide", { - nounType: 'document', + nounType: NounType.Document, title: "API Guide", category: "documentation", version: "2.0" }) const author = await brain.add("Jane Developer", { - nounType: 'person', - type: "person", + nounType: NounType.Person, role: "tech-lead" }) const project = await brain.add("E-commerce Platform", { - nounType: 'project', - type: "project", + nounType: NounType.Project, status: "active" }) @@ -462,21 +462,18 @@ const similar = await brain.search(existingContent, { ```javascript // Store conversation with relationships const userId = await brain.add("User 123", { - nounType: 'user', - type: "user", + nounType: NounType.User, tier: "premium" }) const messageId = await brain.add(userMessage, { - nounType: 'message', - type: "message", + nounType: NounType.Message, timestamp: Date.now(), session: "abc" }) const topicId = await brain.add("Product Support", { - nounType: 'topic', - type: "topic", + nounType: NounType.Topic, category: "support" }) @@ -602,7 +599,7 @@ for (const cluster of feedbackClusters) { } // Find related documents -const docId = await brain.add("Machine learning guide", { nounType: 'document' }) +const docId = await brain.add("Machine learning guide", { nounType: NounType.Document }) const similar = await neural.neighbors(docId, 5) // Returns 5 most similar documents @@ -637,7 +634,7 @@ Brainy includes enterprise-grade capabilities at no extra cost. **No premium tie - **Built-in monitoring** with metrics and health checks - **Production ready** with circuit breakers and backpressure -📖 **Enterprise features coming in Brainy 3.1** - Stay tuned! +📖 **More enterprise features coming soon** - Stay tuned! ## 📊 Benchmarks @@ -651,13 +648,14 @@ Brainy includes enterprise-grade capabilities at no extra cost. **No premium tie | Bulk Import (1000 items) | 2.3s | +8MB | | **Production Scale (10M items)** | **5.8ms** | **12GB** | -## 🔄 Migration from 2.x +## 🔄 Migration from Previous Versions -Key changes for upgrading to 3.0: +Key changes in the latest version: - Search methods consolidated into `search()` and `find()` - Result format now includes full objects with metadata -- New natural language capabilities +- Enhanced natural language capabilities +- Distributed architecture support ## 🤝 Contributing @@ -678,10 +676,10 @@ We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. ### The Math of Infinite Expressiveness ``` -24 Nouns × 40 Verbs × ∞ Metadata × Triple Intelligence = Universal Protocol +31 Nouns × 40 Verbs × ∞ Metadata × Triple Intelligence = Universal Protocol ``` -- **960 base combinations** from standardized types +- **1,240 base combinations** from standardized types - **∞ domain specificity** via unlimited metadata - **∞ relationship depth** via graph traversal - **= Model ANYTHING**: From quantum physics to social networks diff --git a/docs/QUICK-START.md b/docs/QUICK-START.md index 8c739c15..3f7b6625 100644 --- a/docs/QUICK-START.md +++ b/docs/QUICK-START.md @@ -5,7 +5,7 @@ Get up and running with Brainy in 5 minutes! ## Installation ```bash -npm install brainy +npm install @soulcraft/brainy ``` Or install globally for CLI access: @@ -18,7 +18,7 @@ npm install -g brainy ### 1. Initialize Brainy ```javascript -import { BrainyData } from 'brainy' +import { BrainyData, NounType } from '@soulcraft/brainy' const brain = new BrainyData() await brain.init() @@ -34,11 +34,11 @@ That's it! No configuration needed. Brainy automatically: ```javascript // Add a simple string -await brain.add("JavaScript is a versatile programming language", { nounType: 'concept' }) +await brain.add("JavaScript is a versatile programming language", { nounType: NounType.Concept }) // Add with metadata await brain.add("React is a JavaScript library", { - nounType: 'concept', + nounType: NounType.Concept, type: "library", category: "frontend", popularity: "high" @@ -50,7 +50,7 @@ await brain.add({ content: "TypeScript adds static typing to JavaScript", author: "John Doe" }, { - nounType: 'document', + nounType: NounType.Document, type: "article", date: "2024-01-15" }) @@ -77,11 +77,11 @@ const libraries = await brain.search("JavaScript", { ### Example 1: Document Search System ```javascript -import { BrainyData } from 'brainy' +import { BrainyData, NounType } from '@soulcraft/brainy' import fs from 'fs' const brain = new BrainyData({ - storage: { + storage: { type: 'filesystem', path: './document-index' } @@ -97,6 +97,7 @@ const documents = [ for (const doc of documents) { await brain.add(doc.content, { + nounType: NounType.Document, filename: doc.file, type: 'documentation', indexed: new Date().toISOString() @@ -112,7 +113,7 @@ results.forEach(r => console.log(`- ${r.metadata.filename} (${(r.score * 100).to ### Example 2: AI Chat with Memory ```javascript -import { BrainyData } from 'brainy' +import { BrainyData, NounType } from '@soulcraft/brainy' const brain = new BrainyData() await brain.init() @@ -125,6 +126,7 @@ class ChatWithMemory { async addMessage(role, content) { await this.brain.add(content, { + nounType: NounType.Message, role, sessionId: this.sessionId, timestamp: Date.now() @@ -164,7 +166,7 @@ const response = await chat.chat("What did we discuss about JavaScript?") ### Example 3: Semantic Code Search ```javascript -import { BrainyData } from 'brainy' +import { BrainyData, NounType } from '@soulcraft/brainy' import { glob } from 'glob' import fs from 'fs' @@ -180,6 +182,7 @@ for (const file of files) { const functions = content.match(/function\s+(\w+)|const\s+(\w+)\s*=/g) || [] await brain.add(content, { + nounType: NounType.File, file, type: 'code', language: 'javascript', diff --git a/docs/features/v3-features.md b/docs/features/v3-features.md index b3e5d67e..f8bc9c96 100644 --- a/docs/features/v3-features.md +++ b/docs/features/v3-features.md @@ -1,4 +1,4 @@ -# 🚀 Brainy 3.0 - Production-Ready Features +# 🚀 Brainy - Production-Ready Features > **Status**: All features listed here are IMPLEMENTED and TESTED @@ -292,5 +292,5 @@ These features are documented but NOT yet implemented: --- -*Last Updated: Brainy 3.0.0* +*Last Updated: Latest Version* *All features listed above are production-ready and tested* \ No newline at end of file diff --git a/docs/guides/distributed-system.md b/docs/guides/distributed-system.md index 041f5288..d368ac5a 100644 --- a/docs/guides/distributed-system.md +++ b/docs/guides/distributed-system.md @@ -2,7 +2,7 @@ ## Overview -Brainy 3.0 introduces a groundbreaking **zero-configuration distributed system** that transforms how vector databases scale. Unlike traditional distributed databases that require complex setup (Consul, etcd, Zookeeper), Brainy uses your existing storage (S3, GCS, R2) as the coordination layer. +Brainy introduces a groundbreaking **zero-configuration distributed system** that transforms how vector databases scale. Unlike traditional distributed databases that require complex setup (Consul, etcd, Zookeeper), Brainy uses your existing storage (S3, GCS, R2) as the coordination layer. ## Key Innovation: Storage-Based Coordination diff --git a/docs/guides/getting-started.md b/docs/guides/getting-started.md index 7568ece8..b1b9d85c 100644 --- a/docs/guides/getting-started.md +++ b/docs/guides/getting-started.md @@ -5,7 +5,7 @@ This guide will help you get up and running with Brainy, the multi-dimensional A ## Installation ```bash -npm install brainy +npm install @soulcraft/brainy ``` ## Basic Setup @@ -13,7 +13,7 @@ npm install brainy ### Simple Initialization ```typescript -import { BrainyData } from 'brainy' +import { BrainyData } from '@soulcraft/brainy' // Create a new Brainy instance with defaults const brain = new BrainyData()