From a1d6754a21e96608dcbeb8466357a3ffe314ebcb Mon Sep 17 00:00:00 2001 From: David Snelling Date: Thu, 14 Aug 2025 12:13:10 -0700 Subject: [PATCH] docs: Update documentation index for 1.0 and create comprehensive CLI 1.0 reference - Update docs/README.md to prioritize Brainy 1.0 Quick Start guide - Add 1.0 migration guide and changelog to recently updated section - Create comprehensive brainy-cli-1.0.md reference guide: - Document all 9 unified CLI commands (down from 40+) - Show before/after comparison of command simplification - Cover smart defaults, encryption, neural import, chat mode - Include migration guide from 0.x CLI commands - Add production deployment examples and performance tips - Ready for users to discover and use the new unified CLI experience --- docs/README.md | 12 +- docs/brainy-cli-1.0.md | 337 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 344 insertions(+), 5 deletions(-) create mode 100644 docs/brainy-cli-1.0.md diff --git a/docs/README.md b/docs/README.md index f52b67f1..a9ad7cb2 100644 --- a/docs/README.md +++ b/docs/README.md @@ -7,7 +7,8 @@ Welcome to the comprehensive documentation for Brainy - the intelligent vector g ### 🚀 [Getting Started](getting-started/) Quick setup guides and first steps with Brainy. -- **[Quick Start Guide](getting-started/quick-start.md)** - Get up and running in minutes +- **[Brainy 1.0 Quick Start](getting-started/quick-start-1.0.md)** - Get up and running with the unified API ⭐ +- **[Legacy Quick Start (0.x)](getting-started/quick-start.md)** - For existing 0.x users - **[Installation Guide](getting-started/installation.md)** - Installation options and requirements - **[Environment Setup](getting-started/environment-setup.md)** - Configure your development environment - **[First Steps](getting-started/first-steps.md)** - Your first Brainy application @@ -104,12 +105,13 @@ Common issues and solutions. 2. **[Documentation Standards](development/DOCUMENTATION_STANDARDS.md)** - Writing docs 3. **[Testing Guide](development/testing.md)** - Testing practices -## 🔄 Recently Updated +## 🔄 Recently Updated (Brainy 1.0) -- **[S3 Migration Guide](optimization-guides/s3-migration-guide.md)** - NEW: Complete migration guide for shared S3 buckets +- **[Brainy 1.0 Quick Start](getting-started/quick-start-1.0.md)** - NEW: Unified API with 7 core methods ⭐ +- **[Migration Guide](../MIGRATION.md)** - NEW: Complete 0.x to 1.0 upgrade guide +- **[Changelog](../CHANGELOG.md)** - NEW: 1.0 release candidate details +- **[S3 Migration Guide](optimization-guides/s3-migration-guide.md)** - Complete migration guide for shared S3 buckets - **[Large-Scale Optimizations](optimization-guides/large-scale-optimizations.md)** - Complete rewrite with auto-configuration -- **[Quick Start Guide](getting-started/quick-start.md)** - Updated with zero-config setup -- **[API Reference](api-reference/)** - New auto-configuration APIs ## 📞 Getting Help diff --git a/docs/brainy-cli-1.0.md b/docs/brainy-cli-1.0.md new file mode 100644 index 00000000..fc2eb74c --- /dev/null +++ b/docs/brainy-cli-1.0.md @@ -0,0 +1,337 @@ +# Brainy CLI 1.0 - Unified Command Interface 🧠 + +> **One CLI, All the Power - Simplified from 40+ commands to 9** + +The Brainy 1.0 CLI provides a clean, unified interface to manage your intelligent database. Every command follows the same unified philosophy as the API. + +## 🎯 What's New in CLI 1.0 + +### **Before (0.x): Command Chaos** +```bash +brainy add-smart "data" +brainy add-vector --literal "text" +brainy search-similar "query" +brainy neural-import data.csv +# ... 40+ different commands +``` + +### **After (1.0): Unified Simplicity** +```bash +brainy add "data" # Smart by default +brainy search "query" # Unified search +brainy import data.csv # Neural import built-in +# Just 9 core commands total +``` + +## ⚡ Quick Start + +### Installation +```bash +npm install @soulcraft/brainy@rc +``` + +### Initialize Your Brain +```bash +brainy init + +# Interactive setup prompts: +# ✓ Storage type (memory, filesystem, S3) +# ✓ Encryption (recommended for sensitive data) +# ✓ Performance tier (small, medium, large, enterprise) +``` + +## 🧠 The 7 Core Data Commands + +### 1. `brainy add` - Smart Data Addition +```bash +# Smart mode (auto-detects and processes) +brainy add "Elon Musk founded SpaceX in 2002" + +# With metadata +brainy add "Customer feedback" --metadata '{"rating": 5, "source": "survey"}' + +# Encrypted storage +brainy add "Sensitive data" --encrypt + +# Literal mode (bypass AI processing) +brainy add "Raw text data" --literal +``` + +### 2. `brainy search` - Unified Search +```bash +# Semantic search +brainy search "companies founded by Elon" + +# With filters +brainy search "customer feedback" --filter '{"rating": {"$gte": 4}}' + +# Limit results +brainy search "AI projects" --limit 5 + +# Include metadata in output +brainy search "projects" --include-metadata +``` + +### 3. `brainy import` - Bulk Data Import +```bash +# CSV with automatic structure detection +brainy import data.csv + +# JSON files +brainy import documents.json --batch-size 100 + +# With neural processing (detects entities and relationships) +brainy import data.csv --neural + +# Preview mode (analyze without importing) +brainy import data.csv --preview-only +``` + +### 4. `brainy update` - Smart Updates +```bash +# Update by ID +brainy update abc123 "Updated content" + +# Update with new metadata +brainy update abc123 --metadata '{"status": "processed"}' + +# Batch updates +brainy update --query "old content" --replace "new content" +``` + +### 5. `brainy delete` - Smart Deletion +```bash +# Soft delete (default - preserves indexes) +brainy delete abc123 + +# Hard delete (permanent removal) +brainy delete abc123 --hard + +# Delete by query +brainy delete --query "outdated content" --confirm +``` + +### 6. `brainy add-noun` - Create Typed Entities +```bash +# Create person entity +brainy add-noun "Sarah Thompson" --type Person + +# With rich metadata +brainy add-noun "Project Apollo" --type Project --metadata '{ + "status": "active", + "budget": "$500K", + "team_size": 12 +}' +``` + +### 7. `brainy add-verb` - Create Relationships +```bash +# Create relationship between entities +brainy add-verb person_sarah_123 project_apollo_456 --type WorksWith + +# With relationship metadata +brainy add-verb person_sarah_123 project_apollo_456 --type WorksWith --metadata '{ + "role": "Lead Designer", + "allocation": "75%", + "start_date": "2024-01-15" +}' +``` + +## 🎮 Interactive Commands + +### `brainy chat` - Talk to Your Data +```bash +# Start interactive chat session +brainy chat + +# Single question mode +brainy chat "What projects is Sarah working on?" + +# With specific AI provider +brainy chat --provider anthropic "Analyze customer sentiment trends" + +# Export conversation +brainy chat --export-session conversation.md +``` + +### `brainy status` - System Overview +```bash +# Complete system status +brainy status + +# Per-service breakdown +brainy status --detailed + +# Performance metrics +brainy status --metrics + +# Storage utilization +brainy status --storage +``` + +## ⚙️ Configuration & Management + +### `brainy config` - Configuration Management +```bash +# View current configuration +brainy config show + +# Set configuration values +brainy config set storage.type filesystem +brainy config set ai.provider openai + +# Encrypted configuration +brainy config set api_key "secret-key" --encrypt + +# Reset to defaults +brainy config reset +``` + +## 🔍 Advanced Examples + +### Entity and Relationship Management +```bash +# Create a complete knowledge graph +brainy add-noun "SoulCraft Labs" --type Organization +brainy add-noun "Brainy Database" --type Product +brainy add-noun "Sarah Johnson" --type Person + +# Connect them with relationships +brainy add-verb org_soulcraft_123 product_brainy_456 --type Creates +brainy add-verb person_sarah_789 org_soulcraft_123 --type WorksFor --metadata '{ + "position": "CTO", + "start_date": "2023-06-01" +}' + +# Query the graph +brainy search "SoulCraft team members" --include-relationships +``` + +### Bulk Operations +```bash +# Import and process a large dataset +brainy import customer-data.csv --neural --batch-size 500 --progress + +# Update all records matching criteria +brainy update --query '{"status": "pending"}' --set '{"status": "processed"}' --confirm + +# Export data with relationships +brainy export --format json --include-relationships --output backup.json +``` + +### Production Deployment +```bash +# Initialize for production with encryption +brainy init --storage s3 --encrypt --performance enterprise + +# Configure S3 storage +brainy config set storage.s3.bucket my-production-brain +brainy config set storage.s3.region us-east-1 + +# Health check for monitoring +brainy status --health-check --json +``` + +## 🔧 Environment Variables + +Configure Brainy using environment variables: + +```bash +# Storage Configuration +export BRAINY_STORAGE_TYPE=s3 +export BRAINY_S3_BUCKET=my-brainy-data +export BRAINY_S3_REGION=us-east-1 + +# AI Provider Configuration +export BRAINY_AI_PROVIDER=openai +export BRAINY_OPENAI_API_KEY=your-api-key + +# Performance Tuning +export BRAINY_PERFORMANCE_TIER=large +export BRAINY_CACHE_SIZE=1000000 + +# Security +export BRAINY_ENCRYPTION_KEY=your-32-char-encryption-key +``` + +## 📊 Output Formats + +All commands support multiple output formats: + +```bash +# JSON output +brainy search "projects" --format json + +# Table output (default) +brainy status --format table + +# CSV export +brainy search "customers" --format csv --output customers.csv + +# Markdown reports +brainy status --format markdown --output report.md +``` + +## 🚀 Performance Tips + +1. **Use batch operations** for large datasets: + ```bash + brainy import large-file.csv --batch-size 1000 + ``` + +2. **Enable caching** for repeated queries: + ```bash + brainy config set cache.enabled true + brainy config set cache.size 100000 + ``` + +3. **Use filters** to reduce result sets: + ```bash + brainy search "content" --filter '{"date": {"$gte": "2024-01-01"}}' + ``` + +4. **Monitor performance** with detailed status: + ```bash + brainy status --metrics --detailed + ``` + +## 🆘 Help & Troubleshooting + +```bash +# Get help for any command +brainy --help +brainy add --help +brainy search --help + +# Verbose output for debugging +brainy search "query" --verbose + +# Check system requirements +brainy status --system-info + +# Validate configuration +brainy config validate +``` + +## 🔄 Migration from 0.x CLI + +| Old Command (0.x) | New Command (1.0) | Notes | +|-------------------|-------------------|--------| +| `cortex init` | `brainy init` | Same functionality | +| `cortex add-smart "data"` | `brainy add "data"` | Smart by default | +| `cortex search-similar "q"` | `brainy search "q"` | Unified search | +| `cortex neural import file.csv` | `brainy import file.csv` | Neural processing built-in | +| `cortex chat "question"` | `brainy chat "question"` | Same interface | +| `cortex status --detailed` | `brainy status --detailed` | Enhanced metrics | + +## 💡 Pro Tips + +1. **Start with init**: Always run `brainy init` in new projects +2. **Use chat mode**: `brainy chat` is the fastest way to explore your data +3. **Enable encryption**: Use `--encrypt` for sensitive data +4. **Monitor status**: Regular `brainy status` checks keep you informed +5. **Batch operations**: Use `--batch-size` for large imports + +--- + +*For the complete API documentation, see [Brainy 1.0 Quick Start](getting-started/quick-start-1.0.md)* \ No newline at end of file