proffesor-for-testing__agentic-qe/v2/docs/implementation/stream-d-quick-reference.md

SwarmOptimizer Quick Reference

Import

import { SwarmOptimizer, Task, Agent } from './core/optimization';
import type {
  OptimizationConfig,
  WorkloadProfile,
  TopologyRecommendation,
  AgentAllocation,
  PerformanceMetrics,
  Bottleneck,
  OptimizationResult
} from './core/optimization';

Initialization

const optimizer = new SwarmOptimizer(memoryStore, eventBus);
await optimizer.initialize();

Core Methods

1. Recommend Topology

const workload: WorkloadProfile = {
  taskCount: 50,
  taskTypes: new Map([['test-generation', 30]]),
  averageComplexity: 0.6,      // 0-1
  parallelizability: 0.8,      // 0-1
  resourceIntensity: 0.5,      // 0-1
  interdependencies: 0.3       // 0-1
};

const recommendation = await optimizer.recommendTopology(workload);
console.log(recommendation.topology);        // 'mesh' | 'hierarchical' | 'ring' | 'star'
console.log(recommendation.expectedSpeedup); // e.g., 3.2
console.log(recommendation.confidence);      // 0-1

2. Allocate Agents

const tasks: Task[] = [{
  id: 'task-1',
  type: 'test-generation',
  complexity: 0.7,
  estimatedDuration: 120000,
  dependencies: [],
  priority: 'critical',
  requiredCapabilities: ['jest']
}];

const agents: Agent[] = [{
  id: 'agent-1',
  type: 'qe-test-generator',
  capabilities: ['jest', 'typescript'],
  currentLoad: 0.2,
  performanceScore: 0.85,
  isAvailable: true
}];

const allocation = await optimizer.allocateAgents(tasks, agents);
console.log(allocation.loadBalance);        // 0-1 (1 = perfect)
console.log(allocation.expectedDuration);   // milliseconds

3. Detect Bottlenecks

const metrics: PerformanceMetrics[] = [{
  taskThroughput: 3.2,         // tasks/second
  averageLatency: 2500,        // milliseconds
  resourceUtilization: 0.88,   // 0-1
  bottlenecks: [],
  timestamp: new Date()
}];

const bottlenecks = await optimizer.detectBottlenecks(metrics);
for (const b of bottlenecks) {
  console.log(b.type);          // 'agent' | 'memory' | 'coordination' | 'io'
  console.log(b.severity);      // 0-1
  console.log(b.recommendation);
}

4. Optimize

const config: OptimizationConfig = {
  targetSpeedup: 3.0,
  maxAgents: 10,
  enableAutoTuning: true,
  enableBottleneckDetection: true,
  enableAdaptiveScaling: true
};

const result = await optimizer.optimize(config);
if (result.success) {
  console.log(result.improvements.get('throughput'));  // % improvement
  console.log(result.improvements.get('latency'));
  console.log(result.improvements.get('overall'));
}

Helper Methods

// Register components
optimizer.registerPerformanceTracker(agentId, tracker);
optimizer.registerLearningEngine(agentId, engine);

// Query state
const history = optimizer.getOptimizationHistory();
const topology = optimizer.getCurrentTopology();

// Cleanup
await optimizer.shutdown();

Topology Decision Matrix

Workload	Recommended	Why
High parallelizability (>0.7)	mesh	Best parallel execution
High interdependencies (>0.6)	hierarchical	Better coordination
Small swarm (<10 agents)	star	Simple coordination
Medium complexity	ring	Balanced approach

Bottleneck Thresholds

Type	Trigger	Severity Calculation
Agent	Utilization > 85%	(util - 0.85) / 0.15
Memory	Util > 75% AND Latency > 1s	latency / 5000
Coordination	Latency variance > 50% avg	variance / (avgLatency * 2)
IO	Throughput < 5 AND Util < 50%	(0.5 - util) * 2

Performance Scoring

Composite Score =
  normalizedThroughput * 0.4 +
  normalizedLatency * 0.3 +
  normalizedUtilization * 0.3

Where:
  normalizedThroughput = min(1, throughput / 10)
  normalizedLatency = max(0, 1 - (latency / 5000))
  normalizedUtilization = utilization

Memory Keys

optimization/topology/latest         - Latest recommendation
optimization/allocation/latest       - Latest allocation
optimization/bottlenecks/latest      - Latest bottlenecks
optimization/results/{timestamp}     - Results (30d TTL)
optimization/metrics/current         - Current metrics
optimization/workload/profile        - Workload analysis
optimization/tasks/pending           - Pending tasks
optimization/agents/active           - Active agents

Event Integration

// Subscribe to events
eventBus.subscribe('agent:completed', async (event) => {
  // Optimizer handles automatically if registered
});

// Manual trigger
await eventBus.emitAsync('optimization:needed', {
  reason: 'bottleneck-detected'
});

Common Patterns

Auto-Optimization Loop

setInterval(async () => {
  const metrics = await collectMetrics();
  const bottlenecks = await optimizer.detectBottlenecks(metrics);

  if (bottlenecks.some(b => b.severity > 0.5)) {
    await optimizer.optimize(config);
  }
}, 60000); // every minute

Workload-Based Initialization

async function initializeSwarm(taskQueue: Task[]) {
  const workload = analyzeTaskQueue(taskQueue);
  const topology = await optimizer.recommendTopology(workload);

  // Initialize swarm with recommended topology
  await swarm.init(topology.topology);

  const agents = await swarm.getAgents();
  const allocation = await optimizer.allocateAgents(taskQueue, agents);

  // Assign tasks based on allocation
  for (const [agentId, taskIds] of allocation.allocations) {
    await swarm.assignTasks(agentId, taskIds);
  }
}

Real-time Bottleneck Monitoring

async function monitorBottlenecks() {
  const metrics: PerformanceMetrics[] = [];

  eventBus.subscribe('test:completed', (event) => {
    metrics.push({
      taskThroughput: event.passed / event.duration,
      averageLatency: event.duration,
      resourceUtilization: getCurrentUtilization(),
      bottlenecks: [],
      timestamp: new Date()
    });
  });

  setInterval(async () => {
    if (metrics.length > 10) {
      const bottlenecks = await optimizer.detectBottlenecks(metrics);
      if (bottlenecks.length > 0) {
        console.warn('Bottlenecks detected:', bottlenecks);
      }
      metrics.length = 0; // reset
    }
  }, 30000);
}

Best Practices

1. Run topology recommendation before swarm initialization
2. Update allocations when task queue changes significantly
3. Monitor bottlenecks continuously during execution
4. Store optimization results for later analysis
5. Register performance trackers for accurate metrics
6. Use adaptive scaling for dynamic workloads
7. Enable auto-tuning for production deployments

Error Handling

try {
  const result = await optimizer.optimize(config);
  if (!result.success) {
    console.error('Optimization failed');
    // Fallback to default configuration
  }
} catch (error) {
  console.error('Optimizer error:', error);
  // Use previous optimization or defaults
}