> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aiagentshouse.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Performance Optimization

> Optimize AI Agents House SDK performance for high-throughput and low-latency scenarios

The AI Agents House SDK is designed for high performance out of the box, but there are many configuration options and patterns to optimize for your specific use case. This guide covers performance tuning, monitoring, and optimization strategies.

## Performance Overview

### Default Performance Characteristics

* **Throughput**: 10,000+ events/minute with default batching
* **Latency**: \< 2ms overhead per tracked interaction
* **Memory**: \~1KB per event in buffer, \~2MB base overhead
* **CPU**: Minimal impact with async processing

### Performance Bottlenecks

Common performance bottlenecks and their solutions:

<Tabs>
  <Tab title="Network I/O">
    **Symptoms**: High latency, timeout errors
    **Solutions**: Optimize batch size, adjust flush intervals, use regional endpoints
  </Tab>

  <Tab title="Memory Usage">
    **Symptoms**: High memory consumption, OOM errors
    **Solutions**: Reduce batch size, increase flush frequency, disable verbose logging
  </Tab>

  <Tab title="Compliance Processing">
    **Symptoms**: High CPU usage, slow response tracking
    **Solutions**: Optimize compliance rules, use selective compliance checking
  </Tab>

  <Tab title="Event Serialization">
    **Symptoms**: High CPU, slow batching
    **Solutions**: Reduce metadata size, optimize event structure
  </Tab>
</Tabs>

## Batch Configuration Optimization

### High-Throughput Configuration

For maximum throughput in high-volume scenarios:

```javascript theme={null}
const highThroughputConfig = {
  apiKey: 'your-api-key',
  organizationId: 'your-org-id',

  // Optimize for throughput
  batchSize: 1000, // Maximum batch size
  flushInterval: 30000, // 30 seconds

  // Reduce overhead
  enableLogging: false,
  enableComplianceChecks: false, // Disable if not needed

  // Network optimization
  retryAttempts: 3,
  retryDelay: 5000,
  httpTimeout: 60000
};

const monitor = new AgentMonitor(highThroughputConfig);
```

### Low-Latency Configuration

For real-time applications requiring immediate event delivery:

```javascript theme={null}
const lowLatencyConfig = {
  apiKey: 'your-api-key',
  organizationId: 'your-org-id',

  // Optimize for latency
  batchSize: 1, // Send immediately
  flushInterval: 100, // Minimal delay

  // Fast failure
  retryAttempts: 1,
  retryDelay: 100,
  httpTimeout: 5000,

  // Minimal processing
  enableLogging: false,
  logLevel: 'error'
};

const monitor = new AgentMonitor(lowLatencyConfig);
```

### Balanced Configuration

For most production scenarios:

```javascript theme={null}
const balancedConfig = {
  apiKey: 'your-api-key',
  organizationId: 'your-org-id',

  // Balanced settings
  batchSize: 250,
  flushInterval: 5000, // 5 seconds

  // Reasonable retry policy
  retryAttempts: 3,
  retryDelay: 1000,

  // Essential features only
  enableLogging: false,
  enableComplianceChecks: true,
  logLevel: 'warn'
};

const monitor = new AgentMonitor(balancedConfig);
```

## Memory Optimization

### Memory-Efficient Event Tracking

```javascript theme={null}
class MemoryEfficientTracker {
  constructor(monitor, options = {}) {
    this.monitor = monitor;
    this.options = {
      maxMetadataSize: 1024, // 1KB max metadata
      enableSampling: true,
      samplingRate: 0.1, // 10% sampling for low-priority events
      ...options
    };
  }

  trackEvent(agentId, event, priority = 'normal') {
    // Sample low-priority events
    if (priority === 'low' && this.options.enableSampling) {
      if (Math.random() > this.options.samplingRate) {
        return; // Skip this event
      }
    }

    // Optimize metadata size
    if (event.metadata) {
      event.metadata = this.optimizeMetadata(event.metadata);
    }

    this.monitor.track(agentId, event);
  }

  optimizeMetadata(metadata) {
    const optimized = {};
    const metadataStr = JSON.stringify(metadata);

    if (metadataStr.length <= this.options.maxMetadataSize) {
      return metadata;
    }

    // Prioritize important fields
    const importantFields = [
      'llmLatency', 'tokensUsed', 'cost', 'riskScore',
      'complianceFlags', 'errorType', 'severity'
    ];

    for (const field of importantFields) {
      if (metadata[field] !== undefined) {
        optimized[field] = metadata[field];
      }
    }

    // Add truncation indicator
    optimized._truncated = true;

    return optimized;
  }
}

// Usage
const efficientTracker = new MemoryEfficientTracker(monitor, {
  maxMetadataSize: 512,
  samplingRate: 0.05 // 5% sampling
});

efficientTracker.trackEvent('agent-id', event, 'low');
```

### Memory Pool Pattern

```javascript theme={null}
class EventPool {
  constructor(poolSize = 1000) {
    this.pool = [];
    this.poolSize = poolSize;
    this.initializePool();
  }

  initializePool() {
    for (let i = 0; i < this.poolSize; i++) {
      this.pool.push(this.createEmptyEvent());
    }
  }

  createEmptyEvent() {
    return {
      eventId: '',
      timestamp: 0,
      sessionId: '',
      agentId: '',
      interactionType: '',
      content: '',
      metadata: {}
    };
  }

  getEvent() {
    if (this.pool.length > 0) {
      return this.pool.pop();
    }
    return this.createEmptyEvent();
  }

  returnEvent(event) {
    if (this.pool.length < this.poolSize) {
      // Reset event
      Object.keys(event).forEach(key => {
        if (typeof event[key] === 'object' && event[key] !== null) {
          if (Array.isArray(event[key])) {
            event[key].length = 0;
          } else {
            Object.keys(event[key]).forEach(subKey => delete event[key][subKey]);
          }
        } else {
          event[key] = typeof event[key] === 'string' ? '' : 0;
        }
      });
      this.pool.push(event);
    }
  }
}

// Usage with monitor
const eventPool = new EventPool(500);

class PooledAgentMonitor extends AgentMonitor {
  track(agentId, eventData) {
    const event = eventPool.getEvent();
    Object.assign(event, eventData);
    event.agentId = agentId;
    event.timestamp = Date.now();
    event.eventId = `evt_${Date.now()}_${Math.random().toString(36).slice(2)}`;
    super.track(agentId, event);
    setTimeout(() => eventPool.returnEvent(event), 1000);
  }
}
```

## CPU Optimization

### Async Processing Patterns

```javascript theme={null}
class AsyncEventProcessor {
  constructor(monitor, options = {}) {
    this.monitor = monitor;
    this.options = {
      workerCount: require('os').cpus().length,
      queueSize: 10000,
      ...options
    };
    this.eventQueue = [];
    this.processing = true;
    this.workers = [];
    this.startWorkers();
  }

  startWorkers() {
    for (let i = 0; i < this.options.workerCount; i++) {
      this.workers.push(this.createWorker());
    }
  }

  createWorker() {
    return setImmediate(async () => {
      while (this.processing || this.eventQueue.length > 0) {
        const events = this.eventQueue.splice(0, 100);
        if (events.length) await this.processEventBatch(events);
        else await new Promise(r => setTimeout(r, 10));
      }
    });
  }

  async processEventBatch(events) {
    try {
      await Promise.all(events.map(e => this.processEvent(e)));
    } catch (err) { console.error('Batch processing error:', err); }
  }

  async processEvent({agentId, data}) {
    this.monitor.track(agentId, data);
  }

  enqueueEvent(agentId, eventData) {
    if (this.eventQueue.length < this.options.queueSize) {
      this.eventQueue.push({agentId, data: eventData});
    } else console.warn('Event queue full, dropping event');
  }

  async shutdown() {
    this.processing = false;
    await Promise.all(this.workers);
    await this.monitor.shutdown();
  }
}
```

## Compliance Rule Optimization

```javascript theme={null}
class OptimizedComplianceEngine {
  constructor(monitor) {
    this.monitor = monitor;
    this.ruleCache = new Map();
    this.compiledRules = new Map();
    this.compileRules();
  }

  compileRules() {
    const rules = this.monitor.complianceEngine?.getAllRules() || [];
    rules.forEach(rule => {
      if (rule.category === 'privacy') {
        this.compiledRules.set(rule.id, { ...rule, compiledPatterns: this.compilePIIPatterns(rule) });
      } else if (rule.category === 'fair_lending') {
        this.compiledRules.set(rule.id, { ...rule, compiledKeywords: this.compileKeywordPatterns(rule) });
      }
    });
  }

  compilePIIPatterns() {
    return {
      ssn: /\b\d{3}[- ]?\d{2}[- ]?\d{4}\b/g,
      phone: /\b(?:\+?1\s*-?)?(?:\(\d{3}\)|\d{3})[\s.-]?\d{3}[\s.-]?\d{4}\b/g,
      email: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b/gi
    };
  }

  compileKeywordPatterns() {
    const keywords = ['people like you', 'your kind', 'typical for'];
    return new RegExp(keywords.join('|'), 'i');
  }

  async evaluateCompliance(context) {
    const key = this.generateCacheKey(context);
    if (this.ruleCache.has(key)) return this.ruleCache.get(key);
    const result = await this.runOptimizedCheck(context);
    this.ruleCache.set(key, result);
    setTimeout(() => this.ruleCache.delete(key), 60000);
    return result;
  }

  generateCacheKey(context) {
    const str = `${context.agentId}-${context.agentResponse?.length}-${context.userMessage?.length}`;
    return require('crypto').createHash('md5').update(str).digest('hex');
  }

  async runOptimizedCheck(context) {
    const violations = [];
    let score = 0;
    for (const [id, rule] of this.compiledRules) {
      if (!rule.isActive) continue;
      const res = await this.evaluateCompiledRule(rule, context);
      violations.push(...res.violations);
      score += res.riskScore;
    }
    return { isCompliant: violations.length===0, violations, riskScore: Math.min(score,100), requiresReview: score>50 };
  }
}
```

## Network Optimization

### Connection Pooling

```javascript theme={null}
import https from 'https';
class OptimizedHTTPClient {
  constructor(baseURL, opts={}) {
    this.baseURL = baseURL;
    this.agent = new https.Agent({ keepAlive:true, maxSockets: opts.maxSockets||50, maxFreeSockets: opts.maxFreeSockets||10, timeout: opts.timeout||30000, freeSocketTimeout: opts.freeSocketTimeout||4000 });
  }
  async makeRequest(path, options) {
    return fetch(this.baseURL+path, {...options, agent:this.agent});
  }
}
```

### Request Compression

```javascript theme={null}
import zlib from 'zlib';
class CompressedEventBatcher {
  constructor(monitor) {
    this.monitor = monitor;
    this.zlib = zlib;
  }
  async sendCompressedBatch(events) {
    const payload = JSON.stringify({events});
    if (payload.length>10240) {
      const compressed = await this.compressData(payload);
      return this.monitor.makeRequest('/api/events/batch',{method:'POST',headers:{'Content-Type':'application/json','Content-Encoding':'gzip'},body:compressed});
    }
    return this.monitor.makeRequest('/api/events/batch',{method:'POST',headers:{'Content-Type':'application/json'},body:payload});
  }
  compressData(data){return new Promise((res,rej)=>this.zlib.gzip(data,(e,c)=>e?rej(e):res(c)));}
}
```

### Regional Endpoints

```javascript theme={null}
class RegionalEndpointManager {
  constructor(primary, fallbacks=[]) { this.endpoints=[primary,...fallbacks]; this.current=0; this.health=new Map(); this.startHealthChecking(); }
  getCurrentEndpoint(){return this.endpoints[this.current];}
  async makeRequest(path,options,retries=3){
    for(let i=0;i<retries;i++){const ep=this.getCurrentEndpoint();
      try{const res=await fetch(ep+path,options);
        if(res.ok){this.health.set(ep,{healthy:true,lastCheck:Date.now()});return res;}throw new Error(`HTTP ${res.status}`);
      }catch(err){this.health.set(ep,{healthy:false,lastCheck:Date.now()}); if(i<retries-1){this.current=(this.current+1)%this.endpoints.length;await this.delay(2**i*1000);}else throw err;}
    }
  }
  delay(ms){return new Promise(r=>setTimeout(r,ms));}
  startHealthChecking(){setInterval(()=>this.endpoints.forEach(async ep=>{try{await fetch(ep+'/health',{method:'HEAD',timeout:5000});this.health.set(ep,{healthy:true,lastCheck:Date.now()});}catch{this.health.set(ep,{healthy:false,lastCheck:Date.now()});}}),60000);}
}
```

## Performance Monitoring

### Metrics Collection

```javascript theme={null}
class PerformanceMonitor {
  constructor(monitor) {
    this.monitor = monitor;
    this.metrics = { eventThroughput:new Map(), latencyStats:[], errorRates:new Map(), batchEfficiency:[], memoryUsage:[] };
    this.startMetricsCollection();
  }

  startMetricsCollection() { setInterval(()=>this.collectMetrics(), 30000); }
  collectMetrics() {
    const now=Date.now(); this.collectThroughput(now); this.collectMemory(now); this.collectBatch(now); this.cleanup(now);
  }
  collectThroughput(ts) {
    const window=Math.floor(ts/60000);
    this.metrics.eventThroughput.set(window,(this.metrics.eventThroughput.get(window)||0)+1);
  }
  collectMemory(ts) { const u=process.memoryUsage(); this.metrics.memoryUsage.push({timestamp:ts,heapUsed:u.heapUsed,heapTotal:u.heapTotal,external:u.external,rss:u.rss}); }
  collectBatch(ts) { const size=this.monitor.eventBatcher?.getCurrentBatchSize()||0; const ratio=size/this.monitor.config.batchSize; this.metrics.batchEfficiency.push({timestamp:ts,batchSize:size,fillRatio:ratio,efficiency:ratio>0.8?'good':ratio>0.5?'medium':'poor'}); }
  recordLatency(op,lat){this.metrics.latencyStats.push({timestamp:Date.now(),operation:op,latency:lat});}
  recordError(type){const m=Math.floor(Date.now()/60000);const k=`${m}-${type}`;this.metrics.errorRates.set(k,(this.metrics.errorRates.get(k)||0)+1);}
  getPerformanceReport(){
    const now=Date.now();const lastHour=now-3600000;
    return { throughput:this.calculateThroughput(lastHour), latency:this.calculateLatency(lastHour), errorRate:this.calculateErrorRate(lastHour), memoryTrend:this.calculateMemoryTrend(lastHour), batchEfficiency:this.calculateBatchEfficiency(lastHour) };
  }
  calculateThroughput(since){ const windows=Array.from(this.metrics.eventThroughput.entries()).filter(([w])=>w*60000>=since); const total=windows.reduce((s,[,c])=>s+c,0); return {eventsPerSecond:total/((Date.now()-since)/1000), totalEvents:total}; }
  calculateLatency(since){ const arr=this.metrics.latencyStats.filter(s=>s.timestamp>=since).map(s=>s.latency).sort((a,b)=>a-b); if(!arr.length) return null; const get=(p)=>arr[Math.floor(arr.length*p)]; return {min:arr[0], max:arr[arr.length-1], median:get(0.5), p95:get(0.95), p99:get(0.99), average:arr.reduce((a,b)=>a+b,0)/arr.length}; }
  calculateErrorRate(since){ return Array.from(this.metrics.errorRates.values()).reduce((a,b)=>a+b,0)/((Date.now()-since)/60000)||0; }
  calculateMemoryTrend(since){ return this.metrics.memoryUsage.filter(m=>m.timestamp>=since); }
  calculateBatchEfficiency(since){ return this.metrics.batchEfficiency.filter(b=>b.timestamp>=since); }
  cleanup(now){ const hr=now-3600000; this.metrics.latencyStats=this.metrics.latencyStats.filter(s=>s.timestamp>=hr); this.metrics.memoryUsage=this.metrics.memoryUsage.filter(m=>m.timestamp>=hr); this.metrics.batchEfficiency=this.metrics.batchEfficiency.filter(b=>b.timestamp>=hr); }
}
```