feat: implement always-adaptive caching with getCacheStats monitoring

Replaces lazy mode concept with always-adaptive caching strategy:

- Rename getLazyModeStats() → getCacheStats() with enhanced metrics
- Change lazyModeEnabled boolean → cachingStrategy enum ('preloaded' | 'on-demand')
- Update preloading threshold from 30% to 80% for better cache utilization
- Add comprehensive production monitoring and diagnostics
- Add memory detection for containers (Docker/K8s cgroups v1/v2)
- Add adaptive memory sizing from 2GB to 128GB+ systems

Breaking changes: None (backward compatible, deprecated lazy option ignored)

New APIs:
- getCacheStats(): Comprehensive cache performance statistics
- cachingStrategy field: Transparent strategy reporting
- Enhanced fairness metrics and memory pressure monitoring

Documentation:
- Add migration guide for v3.36.0
- Add operations/capacity-planning.md for enterprise deployments
- Update all examples and troubleshooting guides
- Rename monitor-lazy-mode.ts → monitor-cache-performance.ts
This commit is contained in:
David Snelling 2025-10-10 14:09:30 -07:00
parent 6037db3d85
commit 46c6af3f21
17 changed files with 2737 additions and 127 deletions

View file

@ -30,7 +30,7 @@ await brain.init()
#### Development
```typescript
const brain = new Brainy(PresetName.DEVELOPMENT)
// ✅ Memory storage for fast iteration
// ✅ Filesystem storage for persistence
// ✅ FP32 models for best quality
// ✅ Verbose logging
// ✅ All features enabled
@ -48,7 +48,7 @@ const brain = new Brainy(PresetName.PRODUCTION)
#### Minimal
```typescript
const brain = new Brainy(PresetName.MINIMAL)
// ✅ Memory storage
// ✅ Filesystem storage
// ✅ Q8 models for small size
// ✅ Core features only
// ✅ Minimal resource usage
@ -147,11 +147,10 @@ Brainy automatically detects the best storage option:
2. **Browser Storage**
- OPFS (if supported)
- Memory (fallback)
- Filesystem fallback
3. **Node.js Storage**
- Filesystem (`./brainy-data` or `~/.brainy/data`)
- Memory (for serverless)
### Manual Storage Control
@ -159,7 +158,6 @@ Brainy automatically detects the best storage option:
import { StorageOption } from '@soulcraft/brainy'
// Force specific storage with enum
const brain = new Brainy({ storage: StorageOption.MEMORY })
const brain = new Brainy({ storage: StorageOption.DISK })
const brain = new Brainy({ storage: StorageOption.CLOUD })
const brain = new Brainy({ storage: StorageOption.AUTO })
@ -254,7 +252,6 @@ enum ModelPrecision {
enum StorageOption {
AUTO = 'auto',
MEMORY = 'memory',
DISK = 'disk',
CLOUD = 'cloud'
}