agentic-flow 2.0.7 → 3.0.0-alpha.2

package/.claude/agents/swarm/hierarchical-coordinator.md

@@ -142,460 +142,6 @@ WORKERS WORKERS WORKERS WORKERS
    - Lessons learned documentation
 ```
 
-## 🧠 Advanced Attention Mechanisms (v2.0.0-alpha)
-
-### Hyperbolic Attention for Hierarchical Coordination
-
-Hierarchical swarms use **hyperbolic attention** to model natural queen-worker relationships with topology-aware coordination:
-
-```typescript
-import { AttentionService } from 'agentdb';
-
-// Initialize attention service for hierarchical coordination
-const attentionService = new AttentionService({
-  embeddingDim: 384,
-  runtime: 'napi' // 2.49x-7.47x faster than standard attention
-});
-
-// Queen-worker hierarchical coordination with 1.5x influence weight
-class HierarchicalCoordinator {
-  constructor(
-    private attentionService: AttentionService,
-    private queenWeight: number = 1.5
-  ) {}
-
-  /**
-   * Coordinate using hyperbolic attention for hierarchical structures
-   * Queens have 1.5x influence weight over workers
-   */
-  async coordinateHierarchy(
-    queenOutputs: AgentOutput[],
-    workerOutputs: AgentOutput[],
-    curvature: number = -1.0 // Hyperbolic space curvature
-  ): Promise<CoordinationResult> {
-    // Convert outputs to embeddings
-    const queenEmbeddings = await this.outputsToEmbeddings(queenOutputs);
-    const workerEmbeddings = await this.outputsToEmbeddings(workerOutputs);
-
-    // Apply queen influence weight
-    const weightedQueenEmbeddings = queenEmbeddings.map(emb =>
-      emb.map(v => v * this.queenWeight)
-    );
-
-    // Combine queens and workers
-    const allEmbeddings = [...weightedQueenEmbeddings, ...workerEmbeddings];
-
-    // Use hyperbolic attention for hierarchy-aware coordination
-    const result = await this.attentionService.hyperbolicAttention(
-      allEmbeddings,
-      allEmbeddings,
-      allEmbeddings,
-      { curvature }
-    );
-
-    // Extract attention weights for each agent
-    const attentionWeights = this.extractAttentionWeights(result);
-
-    // Generate consensus with hierarchical influence
-    const consensus = this.generateConsensus(
-      [...queenOutputs, ...workerOutputs],
-      attentionWeights
-    );
-
-    return {
-      consensus,
-      attentionWeights,
-      topAgents: this.rankAgentsByInfluence(attentionWeights),
-      hierarchyDepth: this.calculateHierarchyDepth(attentionWeights),
-      executionTimeMs: result.executionTimeMs,
-      memoryUsage: result.memoryUsage
-    };
-  }
-
-  /**
-   * GraphRoPE: Topology-aware position embeddings
-   * Models hierarchical swarm structure as a graph
-   */
-  async topologyAwareCoordination(
-    agentOutputs: AgentOutput[],
-    topologyType: 'hierarchical' | 'tree' | 'star'
-  ): Promise<CoordinationResult> {
-    // Build graph representation of hierarchy
-    const graphContext = this.buildHierarchyGraph(agentOutputs, topologyType);
-
-    const embeddings = await this.outputsToEmbeddings(agentOutputs);
-
-    // Apply GraphRoPE for topology-aware position encoding
-    const positionEncodedEmbeddings = this.applyGraphRoPE(
-      embeddings,
-      graphContext
-    );
-
-    // Hyperbolic attention with topology awareness
-    const result = await this.attentionService.hyperbolicAttention(
-      positionEncodedEmbeddings,
-      positionEncodedEmbeddings,
-      positionEncodedEmbeddings,
-      { curvature: -1.0 }
-    );
-
-    return this.processCoordinationResult(result, agentOutputs);
-  }
-
-  /**
-   * Build hierarchical graph structure
-   */
-  private buildHierarchyGraph(
-    outputs: AgentOutput[],
-    topology: 'hierarchical' | 'tree' | 'star'
-  ): GraphContext {
-    const nodes = outputs.map((output, idx) => ({
-      id: idx,
-      label: output.agentType,
-      level: output.hierarchyLevel || 0
-    }));
-
-    const edges: [number, number][] = [];
-    const edgeWeights: number[] = [];
-
-    // Build edges based on topology
-    if (topology === 'hierarchical' || topology === 'tree') {
-      // Queens at level 0 connect to workers at level 1
-      const queens = nodes.filter(n => n.level === 0);
-      const workers = nodes.filter(n => n.level === 1);
-
-      queens.forEach(queen => {
-        workers.forEach(worker => {
-          edges.push([queen.id, worker.id]);
-          edgeWeights.push(this.queenWeight); // Queen influence
-        });
-      });
-    } else if (topology === 'star') {
-      // Central queen connects to all workers
-      const queen = nodes[0]; // First is queen
-      nodes.slice(1).forEach(worker => {
-        edges.push([queen.id, worker.id]);
-        edgeWeights.push(this.queenWeight);
-      });
-    }
-
-    return {
-      nodes: nodes.map(n => n.id),
-      edges,
-      edgeWeights,
-      nodeLabels: nodes.map(n => n.label)
-    };
-  }
-
-  /**
-   * Apply GraphRoPE position embeddings based on graph structure
-   */
-  private applyGraphRoPE(
-    embeddings: number[][],
-    graphContext: GraphContext
-  ): number[][] {
-    return embeddings.map((emb, idx) => {
-      // Find position in hierarchy
-      const depth = this.calculateNodeDepth(idx, graphContext);
-      const siblings = this.findSiblingCount(idx, graphContext);
-
-      // Position encoding based on depth and sibling position
-      const positionEncoding = this.generatePositionEncoding(
-        emb.length,
-        depth,
-        siblings
-      );
-
-      // Add position encoding to embedding
-      return emb.map((v, i) => v + positionEncoding[i] * 0.1);
-    });
-  }
-
-  private calculateNodeDepth(nodeId: number, graph: GraphContext): number {
-    // BFS to calculate depth from queens (level 0)
-    const visited = new Set<number>();
-    const queue: [number, number][] = [[nodeId, 0]];
-
-    while (queue.length > 0) {
-      const [current, depth] = queue.shift()!;
-      if (visited.has(current)) continue;
-      visited.add(current);
-
-      // Find parent edges (reverse direction)
-      graph.edges.forEach(([from, to], edgeIdx) => {
-        if (to === current && !visited.has(from)) {
-          queue.push([from, depth + 1]);
-        }
-      });
-    }
-
-    return visited.size;
-  }
-
-  private findSiblingCount(nodeId: number, graph: GraphContext): number {
-    // Find parent
-    const parent = graph.edges.find(([_, to]) => to === nodeId)?.[0];
-    if (parent === undefined) return 0;
-
-    // Count siblings (other nodes with same parent)
-    return graph.edges.filter(([from, to]) =>
-      from === parent && to !== nodeId
-    ).length;
-  }
-
-  private generatePositionEncoding(
-    dim: number,
-    depth: number,
-    siblings: number
-  ): number[] {
-    // Sinusoidal position encoding
-    return Array.from({ length: dim }, (_, i) => {
-      const freq = 1 / Math.pow(10000, i / dim);
-      return Math.sin(depth * freq) + Math.cos(siblings * freq);
-    });
-  }
-
-  private async outputsToEmbeddings(
-    outputs: AgentOutput[]
-  ): Promise<number[][]> {
-    // Convert agent outputs to embeddings (simplified)
-    // In production, use actual embedding model
-    return outputs.map(output =>
-      Array.from({ length: 384 }, () => Math.random())
-    );
-  }
-
-  private extractAttentionWeights(result: any): number[] {
-    // Extract attention weights from result
-    return Array.from(result.output.slice(0, result.output.length / 384))
-      .map((_, i) => result.output[i]);
-  }
-
-  private generateConsensus(
-    outputs: AgentOutput[],
-    weights: number[]
-  ): string {
-    // Weighted consensus based on attention scores
-    const weightedOutputs = outputs.map((output, idx) => ({
-      output: output.content,
-      weight: weights[idx]
-    }));
-
-    // Return highest weighted output
-    const best = weightedOutputs.reduce((max, curr) =>
-      curr.weight > max.weight ? curr : max
-    );
-
-    return best.output;
-  }
-
-  private rankAgentsByInfluence(weights: number[]): AgentRanking[] {
-    return weights
-      .map((weight, idx) => ({ agentId: idx, influence: weight }))
-      .sort((a, b) => b.influence - a.influence);
-  }
-
-  private calculateHierarchyDepth(weights: number[]): number {
-    // Estimate hierarchy depth from weight distribution
-    const queenWeights = weights.slice(0, Math.ceil(weights.length * 0.2));
-    const avgQueenWeight = queenWeights.reduce((a, b) => a + b, 0) / queenWeights.length;
-    const workerWeights = weights.slice(Math.ceil(weights.length * 0.2));
-    const avgWorkerWeight = workerWeights.reduce((a, b) => a + b, 0) / workerWeights.length;
-
-    return avgQueenWeight / avgWorkerWeight;
-  }
-
-  private processCoordinationResult(
-    result: any,
-    outputs: AgentOutput[]
-  ): CoordinationResult {
-    return {
-      consensus: this.generateConsensus(outputs, this.extractAttentionWeights(result)),
-      attentionWeights: this.extractAttentionWeights(result),
-      topAgents: this.rankAgentsByInfluence(this.extractAttentionWeights(result)),
-      executionTimeMs: result.executionTimeMs,
-      memoryUsage: result.memoryUsage
-    };
-  }
-}
-
-// Type definitions
-interface AgentOutput {
-  agentType: string;
-  content: string;
-  hierarchyLevel?: number;
-}
-
-interface GraphContext {
-  nodes: number[];
-  edges: [number, number][];
-  edgeWeights: number[];
-  nodeLabels: string[];
-}
-
-interface CoordinationResult {
-  consensus: string;
-  attentionWeights: number[];
-  topAgents: AgentRanking[];
-  hierarchyDepth?: number;
-  executionTimeMs: number;
-  memoryUsage?: number;
-}
-
-interface AgentRanking {
-  agentId: number;
-  influence: number;
-}
-```
-
-### Usage Example: Hierarchical Coordination
-
-```typescript
-// Initialize hierarchical coordinator
-const coordinator = new HierarchicalCoordinator(attentionService, 1.5);
-
-// Queen agents (strategic planning)
-const queenOutputs = [
-  {
-    agentType: 'planner',
-    content: 'Build authentication service with OAuth2 and JWT',
-    hierarchyLevel: 0
-  },
-  {
-    agentType: 'architect',
-    content: 'Use microservices architecture with API gateway',
-    hierarchyLevel: 0
-  }
-];
-
-// Worker agents (execution)
-const workerOutputs = [
-  {
-    agentType: 'coder',
-    content: 'Implement OAuth2 provider with Passport.js',
-    hierarchyLevel: 1
-  },
-  {
-    agentType: 'tester',
-    content: 'Create integration tests for authentication flow',
-    hierarchyLevel: 1
-  },
-  {
-    agentType: 'reviewer',
-    content: 'Review security best practices for JWT storage',
-    hierarchyLevel: 1
-  }
-];
-
-// Coordinate with hyperbolic attention (queens have 1.5x influence)
-const result = await coordinator.coordinateHierarchy(
-  queenOutputs,
-  workerOutputs,
-  -1.0 // Hyperbolic curvature
-);
-
-console.log('Consensus:', result.consensus);
-console.log('Queen influence:', result.hierarchyDepth);
-console.log('Top contributors:', result.topAgents.slice(0, 3));
-console.log(`Processed in ${result.executionTimeMs}ms (${2.49}x-${7.47}x faster)`);
-```
-
-### Self-Learning Integration (ReasoningBank)
-
-```typescript
-import { ReasoningBank } from 'agentdb';
-
-class LearningHierarchicalCoordinator extends HierarchicalCoordinator {
-  constructor(
-    attentionService: AttentionService,
-    private reasoningBank: ReasoningBank,
-    queenWeight: number = 1.5
-  ) {
-    super(attentionService, queenWeight);
-  }
-
-  /**
-   * Learn from past hierarchical coordination patterns
-   */
-  async coordinateWithLearning(
-    taskDescription: string,
-    queenOutputs: AgentOutput[],
-    workerOutputs: AgentOutput[]
-  ): Promise<CoordinationResult> {
-    // 1. Search for similar past coordination patterns
-    const similarPatterns = await this.reasoningBank.searchPatterns({
-      task: taskDescription,
-      k: 5,
-      minReward: 0.8
-    });
-
-    if (similarPatterns.length > 0) {
-      console.log('📚 Learning from past hierarchical coordinations:');
-      similarPatterns.forEach(pattern => {
-        console.log(`- ${pattern.task}: ${pattern.reward} success rate`);
-        console.log(`  Critique: ${pattern.critique}`);
-      });
-    }
-
-    // 2. Coordinate with hyperbolic attention
-    const result = await this.coordinateHierarchy(
-      queenOutputs,
-      workerOutputs,
-      -1.0
-    );
-
-    // 3. Calculate success metrics
-    const reward = this.calculateCoordinationReward(result);
-    const success = reward > 0.8;
-
-    // 4. Store learning pattern for future improvement
-    await this.reasoningBank.storePattern({
-      sessionId: `hierarchy-${Date.now()}`,
-      task: taskDescription,
-      input: JSON.stringify({ queens: queenOutputs, workers: workerOutputs }),
-      output: result.consensus,
-      reward,
-      success,
-      critique: this.generateCritique(result),
-      tokensUsed: this.estimateTokens(result),
-      latencyMs: result.executionTimeMs
-    });
-
-    return result;
-  }
-
-  private calculateCoordinationReward(result: CoordinationResult): number {
-    // Reward based on:
-    // - Hierarchy depth (queens should have more influence)
-    // - Attention weight distribution
-    // - Execution time
-
-    const hierarchyScore = Math.min(result.hierarchyDepth || 1, 2) / 2; // 0-1
-    const speedScore = Math.max(0, 1 - result.executionTimeMs / 10000); // Faster is better
-
-    return (hierarchyScore * 0.6 + speedScore * 0.4);
-  }
-
-  private generateCritique(result: CoordinationResult): string {
-    const critiques: string[] = [];
-
-    if (result.hierarchyDepth && result.hierarchyDepth < 1.3) {
-      critiques.push('Queens need more influence - consider increasing queen weight');
-    }
-
-    if (result.executionTimeMs > 5000) {
-      critiques.push('Coordination took too long - consider using flash attention');
-    }
-
-    return critiques.join('; ') || 'Good hierarchical coordination';
-  }
-
-  private estimateTokens(result: CoordinationResult): number {
-    return result.consensus.split(' ').length * 1.3;
-  }
-}
-```
-
 ## MCP Tool Integration
 
 ### Swarm Management
@@ -605,7 +151,7 @@ mcp__claude-flow__swarm_init hierarchical --maxAgents=10 --strategy=centralized
 
 # Spawn specialized workers
 mcp__claude-flow__agent_spawn researcher --capabilities="research,analysis"
-mcp__claude-flow__agent_spawn coder --capabilities="implementation,testing"
+mcp__claude-flow__agent_spawn coder --capabilities="implementation,testing"  
 mcp__claude-flow__agent_spawn analyst --capabilities="data_analysis,reporting"
 
 # Monitor swarm health