@soulcraft/brainy 0.51.1 → 0.52.0

package/README.md

@@ -129,6 +129,26 @@ const results = await brainy.search("wireless headphones", 10, {
 - ✅ **5x Fewer Dependencies**: Clean tree, no peer dependency issues
 - ✅ **Same API**: Drop-in replacement, existing code works unchanged
 
+### 🚀 Why Developers Love Brainy
+
+- **🧠 Zero-to-Smart™** - No config files, no tuning parameters, no DevOps headaches. Brainy auto-detects your environment and optimizes itself
+- **🌍 True Write-Once, Run-Anywhere** - Same code runs in Angular, React, Vue, Node.js, Deno, Bun, serverless, edge workers, and web workers with automatic environment detection
+- **⚡ Scary Fast** - Handles millions of vectors with sub-millisecond search. GPU acceleration for embeddings, optimized CPU for distance calculations
+- **🎯 Self-Learning** - Like having a database that goes to the gym. Gets faster and smarter the more you use it
+- **🔮 AI-First Design** - Built for the age of embeddings, RAG, and semantic search. Your LLMs will thank you
+- **🎮 Actually Fun to Use** - Clean API, great DX, and it does the heavy lifting so you can build cool stuff
+
+### 🚀 NEW: Ultra-Fast Search Performance + Auto-Configuration
+
+**Your searches just got 100x faster AND Brainy now configures itself!** Advanced performance with zero setup:
+
+- **🤖 Intelligent Auto-Configuration** - Detects environment and usage patterns, optimizes automatically
+- **⚡ Smart Result Caching** - Repeated queries return in <1ms with automatic cache invalidation
+- **📄 Cursor-Based Pagination** - Navigate millions of results with constant O(k) performance
+- **🔄 Real-Time Data Sync** - Cache automatically updates when data changes, even in distributed scenarios
+- **📊 Performance Monitoring** - Built-in hit rate and memory usage tracking with adaptive optimization
+- **🎯 Zero Breaking Changes** - All existing code works unchanged, just faster and smarter
+
 ## 🏆 Why Brainy Wins
 
 - 🧠 **Triple Search Power** - Vector + Graph + Faceted filtering in one query
@@ -349,6 +369,62 @@ const health = reader.getHealthStatus()
 console.log(`Instance ${health.instanceId}: ${health.status}`)
 ```
 
+### 🐳 NEW: Zero-Config Docker Deployment
+
+**Deploy to any cloud with embedded models - no runtime downloads needed!**
+
+```dockerfile
+# One line extracts models automatically during build
+RUN npm run download-models
+
+# Deploy anywhere: Google Cloud, AWS, Azure, Cloudflare, etc.
+```
+
+- **⚡ 7x Faster Cold Starts** - Models embedded in container, no downloads
+- **🌐 Universal Cloud Support** - Same Dockerfile works everywhere  
+- **🔒 Offline Ready** - No external dependencies at runtime
+- **📦 Zero Configuration** - Automatic model detection and loading
+
+```javascript
+// Zero configuration - everything optimized automatically!
+const brainy = new BrainyData()  // Auto-detects environment & optimizes
+await brainy.init()
+
+// Caching happens automatically - no setup needed!
+const results1 = await brainy.search('query', 10)  // ~50ms first time
+const results2 = await brainy.search('query', 10)  // <1ms cached hit!
+
+// Advanced pagination works instantly
+const page1 = await brainy.searchWithCursor('query', 100)
+const page2 = await brainy.searchWithCursor('query', 100, {
+  cursor: page1.cursor  // Constant time, no matter how deep!
+})
+
+// Monitor auto-optimized performance
+const stats = brainy.getCacheStats()
+console.log(`Auto-tuned cache hit rate: ${(stats.search.hitRate * 100).toFixed(1)}%`)
+```
+
+## 🎭 Key Features
+
+### Core Capabilities
+
+- **Vector Search** - Find semantically similar content using embeddings
+- **MongoDB-Style Metadata Filtering** 🆕 - Advanced filtering with `$gt`, `$in`, `$regex`, `$and`, `$or` operators
+- **Graph Relationships** - Connect data with meaningful relationships
+- **JSON Document Search** - Search within specific fields with prioritization
+- **Distributed Mode** - Scale horizontally with automatic coordination between instances
+- **Real-Time Syncing** - WebSocket and WebRTC for distributed instances
+- **Streaming Pipeline** - Process data in real-time as it flows through
+- **Model Control Protocol** - Let AI models access your data
+
+### Developer Experience
+
+- **TypeScript Support** - Fully typed API with generics
+- **Extensible Augmentations** - Customize and extend functionality
+- **REST API** - Web service wrapper for HTTP endpoints
+- **Auto-Complete** - IntelliSense for all APIs and types
+
 ## 🆚 Why Not Just Use...?
 
 ### vs. Multiple Databases
@@ -488,6 +564,92 @@ Deploy to: Google Cloud Run, AWS Lambda/ECS, Azure Container Instances, Cloudfla
 
 </details>
 
+## 🚀 Getting Started in 30 Seconds
+
+**The same Brainy code works everywhere - React, Vue, Angular, Node.js, Serverless, Edge Workers.**
+
+```javascript
+// This EXACT code works in ALL environments
+import { BrainyData } from '@soulcraft/brainy'
+
+const brainy = new BrainyData()
+await brainy.init()
+
+// Add nouns (entities)
+const openai = await brainy.add("OpenAI", { type: "company" })
+const gpt4 = await brainy.add("GPT-4", { type: "product" })
+
+// Add verbs (relationships)
+await brainy.relate(openai, gpt4, "develops")
+
+// Vector search + Graph traversal
+const similar = await brainy.search("AI companies", 5)
+const products = await brainy.getVerbsBySource(openai)
+```
+
+<details>
+<summary>🔍 <strong>See Framework Examples</strong></summary>
+
+### React
+
+```jsx
+function App() {
+  const [brainy] = useState(() => new BrainyData())
+  useEffect(() => brainy.init(), [])
+
+  const search = async (query) => {
+    return await brainy.search(query, 10)
+  }
+  // Same API as above
+}
+```
+
+### Vue 3
+
+```vue
+<script setup>
+  const brainy = new BrainyData()
+  await brainy.init()
+  // Same API as above
+</script>
+```
+
+### Angular
+
+```typescript
+@Component({})
+export class AppComponent {
+  brainy = new BrainyData()
+
+  async ngOnInit() {
+    await this.brainy.init()
+    // Same API as above
+  }
+}
+```
+
+### Node.js / Deno / Bun
+
+```javascript
+const brainy = new BrainyData()
+await brainy.init()
+// Same API as above
+```
+
+</details>
+
+### 🌍 Framework-First, Runs Everywhere
+
+**Brainy automatically detects your environment and optimizes everything:**
+
+| Environment     | Storage         | Optimization               |
+|-----------------|-----------------|----------------------------|
+| 🌐 Browser      | OPFS            | Web Workers, Memory Cache  |
+| 🟢 Node.js      | FileSystem / S3 | Worker Threads, Clustering |
+| ⚡ Serverless    | S3 / Memory     | Cold Start Optimization    |
+| 🔥 Edge Workers | Memory / KV     | Minimal Footprint          |
+| 🦕 Deno/Bun     | FileSystem / S3 | Native Performance         |
+
 ## 📚 Documentation & Resources
 
 - **[🚀 Quick Start Guide](docs/getting-started/)** - Get up and running in minutes

package/dist/augmentations/intelligentVerbScoring.d.ts

@@ -0,0 +1,158 @@
+import { ICognitionAugmentation, AugmentationResponse } from '../types/augmentations.js';
+/**
+ * Configuration options for the Intelligent Verb Scoring augmentation
+ */
+export interface IVerbScoringConfig {
+    /** Enable semantic proximity scoring based on entity embeddings */
+    enableSemanticScoring: boolean;
+    /** Enable frequency-based weight amplification */
+    enableFrequencyAmplification: boolean;
+    /** Enable temporal decay for weights */
+    enableTemporalDecay: boolean;
+    /** Decay rate per day for temporal scoring (0-1) */
+    temporalDecayRate: number;
+    /** Minimum weight threshold */
+    minWeight: number;
+    /** Maximum weight threshold */
+    maxWeight: number;
+    /** Base confidence score for new relationships */
+    baseConfidence: number;
+    /** Learning rate for adaptive scoring (0-1) */
+    learningRate: number;
+}
+/**
+ * Default configuration for the Intelligent Verb Scoring augmentation
+ */
+export declare const DEFAULT_VERB_SCORING_CONFIG: IVerbScoringConfig;
+/**
+ * Relationship statistics for learning and adaptation
+ */
+interface RelationshipStats {
+    count: number;
+    totalWeight: number;
+    averageWeight: number;
+    lastSeen: Date;
+    firstSeen: Date;
+    semanticSimilarity?: number;
+}
+/**
+ * Intelligent Verb Scoring Cognition Augmentation
+ *
+ * Automatically generates intelligent weight and confidence scores for verb relationships
+ * using semantic analysis, frequency patterns, and temporal factors.
+ */
+export declare class IntelligentVerbScoring implements ICognitionAugmentation {
+    readonly name = "intelligent-verb-scoring";
+    readonly description = "Automatically generates intelligent weight and confidence scores for verb relationships";
+    enabled: boolean;
+    private config;
+    private relationshipStats;
+    private brainyInstance;
+    private isInitialized;
+    constructor(config?: Partial<IVerbScoringConfig>);
+    initialize(): Promise<void>;
+    shutDown(): Promise<void>;
+    getStatus(): Promise<'active' | 'inactive' | 'error'>;
+    /**
+     * Set reference to the BrainyData instance for accessing graph data
+     */
+    setBrainyInstance(instance: any): void;
+    /**
+     * Main reasoning method for generating intelligent verb scores
+     */
+    reason(query: string, context?: Record<string, unknown>): AugmentationResponse<{
+        inference: string;
+        confidence: number;
+    }>;
+    infer(dataSubset: Record<string, unknown>): AugmentationResponse<Record<string, unknown>>;
+    executeLogic(ruleId: string, input: Record<string, unknown>): AugmentationResponse<boolean>;
+    /**
+     * Generate intelligent weight and confidence scores for a verb relationship
+     *
+     * @param sourceId - ID of the source entity
+     * @param targetId - ID of the target entity
+     * @param verbType - Type of the relationship
+     * @param existingWeight - Existing weight if any
+     * @param metadata - Additional metadata about the relationship
+     * @returns Computed weight and confidence scores
+     */
+    computeVerbScores(sourceId: string, targetId: string, verbType: string, existingWeight?: number, metadata?: any): Promise<{
+        weight: number;
+        confidence: number;
+        reasoning: string[];
+    }>;
+    /**
+     * Calculate semantic similarity between two entities using their embeddings
+     */
+    private calculateSemanticScore;
+    /**
+     * Calculate frequency-based boost for repeated relationships
+     */
+    private calculateFrequencyBoost;
+    /**
+     * Calculate temporal decay factor based on recency
+     */
+    private calculateTemporalFactor;
+    /**
+     * Calculate learning-based adjustment using historical patterns
+     */
+    private calculateLearningAdjustment;
+    /**
+     * Update relationship statistics for learning
+     */
+    private updateRelationshipStats;
+    /**
+     * Blend two scores using a weighted average
+     */
+    private blendScores;
+    /**
+     * Get current configuration
+     */
+    getConfig(): IVerbScoringConfig;
+    /**
+     * Update configuration
+     */
+    updateConfig(newConfig: Partial<IVerbScoringConfig>): void;
+    /**
+     * Get relationship statistics (for debugging/monitoring)
+     */
+    getRelationshipStats(): Map<string, RelationshipStats>;
+    /**
+     * Clear relationship statistics
+     */
+    clearStats(): void;
+    /**
+     * Provide feedback to improve future scoring
+     * This allows the system to learn from user corrections or validation
+     *
+     * @param sourceId - Source entity ID
+     * @param targetId - Target entity ID
+     * @param verbType - Relationship type
+     * @param feedbackWeight - The corrected/validated weight (0-1)
+     * @param feedbackConfidence - The corrected/validated confidence (0-1)
+     * @param feedbackType - Type of feedback ('correction', 'validation', 'enhancement')
+     */
+    provideFeedback(sourceId: string, targetId: string, verbType: string, feedbackWeight: number, feedbackConfidence?: number, feedbackType?: 'correction' | 'validation' | 'enhancement'): Promise<void>;
+    /**
+     * Get learning statistics for monitoring and debugging
+     */
+    getLearningStats(): {
+        totalRelationships: number;
+        averageConfidence: number;
+        feedbackCount: number;
+        topRelationships: Array<{
+            relationship: string;
+            count: number;
+            averageWeight: number;
+        }>;
+    };
+    /**
+     * Export learning data for backup or analysis
+     */
+    exportLearningData(): string;
+    /**
+     * Import learning data from backup
+     */
+    importLearningData(jsonData: string): void;
+}
+export {};