brainy/docs/ADAPTIVE_PERFORMANCE.md

Adaptive Performance System

Brainy v0.53.1+ includes an automatic adaptive performance system that eliminates socket exhaustion and optimizes throughput without any configuration.

Zero Configuration Required

The adaptive performance system works automatically - no settings or tuning needed. Just use Brainy normally and it will optimize itself based on your workload.

How It Works

1. Adaptive Socket Management

The system automatically adjusts socket pools based on load:

• Starts conservative: 100 sockets initially
• Scales up under load: Up to 2000 sockets when needed
• Scales down when idle: Conserves resources automatically
• Smart keep-alive: Adjusts connection reuse based on patterns

2. Intelligent Backpressure

Prevents system overload with self-healing capabilities:

• Request flow control: Queues requests when system is busy
• Priority handling: Important operations get processed first
• Circuit breaker: Automatically recovers from overload conditions
• Predictive scaling: Anticipates load changes based on patterns

3. Performance Monitoring

Real-time metrics and optimization:

• Health scoring: 0-100 score of system health
• Trend analysis: Detects degrading performance
• Auto-optimization: Adjusts configuration automatically
• Smart recommendations: Suggests improvements when needed

Benefits

For High-Volume Scenarios

• No more socket exhaustion: Automatically scales sockets as needed
• Better throughput: Batch sizes optimize dynamically
• Automatic recovery: Self-heals from error conditions
• Resource efficiency: Uses only what's needed

For Variable Workloads

• Adapts to patterns: Learns your usage over time
• Handles spikes: Scales up quickly for burst traffic
• Efficient at rest: Scales down to save resources
• No manual tuning: Adjusts itself automatically

Usage Example

import { BrainyData } from '@soulcraft/brainy'

// Just create and use - no special configuration needed
const brainy = new BrainyData({
  storage: {
    type: 's3',
    s3Storage: {
      bucketName: 'my-bucket',
      region: 'us-east-1',
      accessKeyId: 'xxx',
      secretAccessKey: 'yyy'
    }
    // No socket or performance configuration needed!
  }
})

// Use normally - system adapts automatically
await brainy.addBatch(largeDataset)  // Handles any volume

Monitoring Performance (Optional)

While not required, you can monitor the adaptive system:

import { getGlobalPerformanceMonitor } from '@soulcraft/brainy'

const monitor = getGlobalPerformanceMonitor()

// Get current metrics
const report = monitor.getReport()
console.log('Health Score:', report.metrics.healthScore)
console.log('Operations/sec:', report.metrics.operationsPerSecond)
console.log('Current Socket Config:', report.socketConfig)

// Get optimization recommendations
if (report.recommendations.length > 0) {
  console.log('Suggestions:', report.recommendations)
}

How It Helps Your Application

Before (v0.53.0 and earlier)

• Fixed socket limits (500)
• Manual batch size configuration
• Socket exhaustion under high load
• Manual recovery required
• Required tuning for different workloads

After (v0.53.1+)

• Dynamic socket scaling (100-2000)
• Automatic batch optimization
• Self-preventing socket exhaustion
• Automatic error recovery
• Zero configuration needed

Technical Details

Socket Scaling Algorithm

The system uses multiple signals to determine optimal socket count:

• Current request rate
• Pending request queue depth
• Error rate trends
• Memory pressure
• Latency percentiles (P50, P95, P99)

Backpressure Management

Implements Little's Law for optimal concurrency:

L = λ × W
where:
  L = number of requests in system
  λ = arrival rate
  W = average time in system

Circuit Breaker States

• Closed: Normal operation
• Open: Rejecting requests to recover
• Half-Open: Testing if system recovered

Performance Metrics Tracked

• Total operations and success rate
• Latency percentiles (average, P95, P99)
• Throughput (ops/sec, bytes/sec)
• Resource usage (memory, CPU, sockets)
• Queue depth and utilization

Troubleshooting

System reports "overloaded"

This is the circuit breaker protecting your system. It will automatically recover in 30 seconds. To avoid:

• Reduce request rate temporarily
• The system will adapt and handle more load over time

Performance degrading over time

The system will detect this and adapt. You can check recommendations:

const report = monitor.getReport()
console.log(report.recommendations)

Want to disable auto-optimization

While not recommended, you can disable it:

const monitor = getGlobalPerformanceMonitor()
monitor.setAutoOptimize(false)

Migration Guide

From v0.52.x or earlier

No changes required! The adaptive system is automatically active and requires no configuration.

From v0.53.0

Update to v0.53.1+ to get automatic performance optimization.

Best Practices

1. Let it adapt: Give the system time to learn your patterns
2. Monitor initially: Check health score during first few runs
3. Trust the system: Avoid manual tuning unless necessary
4. Report issues: If you see consistent problems, please report them

Performance Benchmarks

Tested with real-world workloads:

Scenario	v0.53.0	v0.53.1	Improvement
10K operations burst	Socket exhaustion at 5K	Completed successfully	✅ No exhaustion
Sustained high load	500 ops/sec max	2000+ ops/sec	4x throughput
Error recovery	Manual intervention	Automatic recovery	✅ Self-healing
Memory efficiency	Fixed allocation	Dynamic scaling	50% less at idle

Further Reading

• Socket Management Details
• Backpressure Algorithm
• Performance Tuning Guide