agentic-flow 2.0.0-alpha → 2.0.1-alpha

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

@@ -142,6 +142,460 @@ 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
@@ -151,7 +605,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