flock-core 0.5.0b28__py3-none-any.whl → 0.5.0b51__py3-none-any.whl

flock/frontend/src/services/layout.test.ts

@@ -0,0 +1,437 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { Node, Edge } from '@xyflow/react';
+
+/**
+ * Phase 4: Graph Visualization & Dual Views - Layout Tests
+ *
+ * Tests for Dagre-based hierarchical layout algorithm.
+ * These tests validate layout generation, node positioning, performance,
+ * and edge routing capabilities.
+ *
+ * SPECIFICATION: docs/specs/003-real-time-dashboard/PLAN.md Phase 4
+ * REQUIREMENT: Auto-layout completes <200ms for 10 nodes
+ */
+
+// Type definitions for the layout service (to be implemented)
+interface LayoutOptions {
+  direction?: 'TB' | 'LR' | 'BT' | 'RL';
+  nodeSpacing?: number;
+  rankSpacing?: number;
+}
+
+interface LayoutResult {
+  nodes: Node[];
+  edges: Edge[];
+  width: number;
+  height: number;
+}
+
+// Mock layout service interface (implementation will be in layout.ts)
+interface LayoutService {
+  applyHierarchicalLayout(nodes: Node[], edges: Edge[], options?: LayoutOptions): LayoutResult;
+}
+
+describe('Layout Service', () => {
+  // This will be replaced with actual implementation
+  let layoutService: LayoutService;
+
+  beforeEach(() => {
+    // Mock implementation for testing
+    layoutService = {
+      applyHierarchicalLayout: (_nodes, _edges, _options) => {
+        // Placeholder that will fail until real implementation
+        throw new Error('Layout service not implemented');
+      },
+    };
+  });
+
+  describe('Hierarchical Layout Generation', () => {
+    it('should generate hierarchical layout in vertical direction (TB)', () => {
+      const nodes: Node[] = [
+        { id: 'agent-1', type: 'agent', position: { x: 0, y: 0 }, data: { name: 'Agent 1' } },
+        { id: 'agent-2', type: 'agent', position: { x: 0, y: 0 }, data: { name: 'Agent 2' } },
+        { id: 'agent-3', type: 'agent', position: { x: 0, y: 0 }, data: { name: 'Agent 3' } },
+      ];
+
+      const edges: Edge[] = [
+        { id: 'e1-2', source: 'agent-1', target: 'agent-2' },
+        { id: 'e2-3', source: 'agent-2', target: 'agent-3' },
+      ];
+
+      expect(() => {
+        layoutService.applyHierarchicalLayout(nodes, edges, { direction: 'TB' });
+      }).toThrow('Layout service not implemented');
+
+      // Expected behavior after implementation:
+      // const result = layoutService.applyHierarchicalLayout(nodes, edges, { direction: 'TB' });
+      //
+      // expect(result.nodes).toHaveLength(3);
+      //
+      // // Verify vertical hierarchy: agent-1 should be above agent-2, agent-2 above agent-3
+      // const node1 = result.nodes.find(n => n.id === 'agent-1');
+      // const node2 = result.nodes.find(n => n.id === 'agent-2');
+      // const node3 = result.nodes.find(n => n.id === 'agent-3');
+      //
+      // expect(node1!.position.y).toBeLessThan(node2!.position.y);
+      // expect(node2!.position.y).toBeLessThan(node3!.position.y);
+    });
+
+    it('should generate hierarchical layout in horizontal direction (LR)', () => {
+      const nodes: Node[] = [
+        { id: 'agent-1', type: 'agent', position: { x: 0, y: 0 }, data: { name: 'Agent 1' } },
+        { id: 'agent-2', type: 'agent', position: { x: 0, y: 0 }, data: { name: 'Agent 2' } },
+      ];
+
+      const edges: Edge[] = [
+        { id: 'e1-2', source: 'agent-1', target: 'agent-2' },
+      ];
+
+      expect(() => {
+        layoutService.applyHierarchicalLayout(nodes, edges, { direction: 'LR' });
+      }).toThrow('Layout service not implemented');
+
+      // Expected behavior after implementation:
+      // const result = layoutService.applyHierarchicalLayout(nodes, edges, { direction: 'LR' });
+      //
+      // const node1 = result.nodes.find(n => n.id === 'agent-1');
+      // const node2 = result.nodes.find(n => n.id === 'agent-2');
+      //
+      // // Verify horizontal hierarchy: agent-1 should be left of agent-2
+      // expect(node1!.position.x).toBeLessThan(node2!.position.x);
+    });
+
+    it('should handle cyclic graphs gracefully', () => {
+      const nodes: Node[] = [
+        { id: 'agent-1', type: 'agent', position: { x: 0, y: 0 }, data: {} },
+        { id: 'agent-2', type: 'agent', position: { x: 0, y: 0 }, data: {} },
+        { id: 'agent-3', type: 'agent', position: { x: 0, y: 0 }, data: {} },
+      ];
+
+      const edges: Edge[] = [
+        { id: 'e1-2', source: 'agent-1', target: 'agent-2' },
+        { id: 'e2-3', source: 'agent-2', target: 'agent-3' },
+        { id: 'e3-1', source: 'agent-3', target: 'agent-1' }, // Cycle
+      ];
+
+      expect(() => {
+        layoutService.applyHierarchicalLayout(nodes, edges);
+      }).toThrow('Layout service not implemented');
+
+      // Expected behavior: Should not throw, should produce valid layout
+      // const result = layoutService.applyHierarchicalLayout(nodes, edges);
+      // expect(result.nodes).toHaveLength(3);
+      // result.nodes.forEach(node => {
+      //   expect(node.position.x).toBeGreaterThanOrEqual(0);
+      //   expect(node.position.y).toBeGreaterThanOrEqual(0);
+      // });
+    });
+  });
+
+  describe('Node Positioning', () => {
+    it('should assign x, y coordinates to all nodes', () => {
+      const nodes: Node[] = [
+        { id: 'node-1', type: 'agent', position: { x: 0, y: 0 }, data: {} },
+        { id: 'node-2', type: 'agent', position: { x: 0, y: 0 }, data: {} },
+        { id: 'node-3', type: 'agent', position: { x: 0, y: 0 }, data: {} },
+      ];
+
+      const edges: Edge[] = [
+        { id: 'e1-2', source: 'node-1', target: 'node-2' },
+      ];
+
+      expect(() => {
+        layoutService.applyHierarchicalLayout(nodes, edges);
+      }).toThrow('Layout service not implemented');
+
+      // Expected behavior:
+      // const result = layoutService.applyHierarchicalLayout(nodes, edges);
+      //
+      // result.nodes.forEach(node => {
+      //   expect(node.position).toHaveProperty('x');
+      //   expect(node.position).toHaveProperty('y');
+      //   expect(typeof node.position.x).toBe('number');
+      //   expect(typeof node.position.y).toBe('number');
+      //   expect(Number.isFinite(node.position.x)).toBe(true);
+      //   expect(Number.isFinite(node.position.y)).toBe(true);
+      // });
+    });
+
+    it('should prevent node overlap with proper spacing', () => {
+      const nodes: Node[] = Array.from({ length: 5 }, (_, i) => ({
+        id: `node-${i}`,
+        type: 'agent',
+        position: { x: 0, y: 0 },
+        data: { name: `Agent ${i}` },
+      }));
+
+      const edges: Edge[] = Array.from({ length: 4 }, (_, i) => ({
+        id: `e${i}-${i + 1}`,
+        source: `node-${i}`,
+        target: `node-${i + 1}`,
+      }));
+
+      expect(() => {
+        layoutService.applyHierarchicalLayout(nodes, edges, { nodeSpacing: 50 });
+      }).toThrow('Layout service not implemented');
+
+      // Expected behavior:
+      // const result = layoutService.applyHierarchicalLayout(nodes, edges, { nodeSpacing: 50 });
+      //
+      // // Check that no two nodes are too close
+      // const minDistance = 50; // Based on nodeSpacing
+      // for (let i = 0; i < result.nodes.length; i++) {
+      //   for (let j = i + 1; j < result.nodes.length; j++) {
+      //     const node1 = result.nodes[i];
+      //     const node2 = result.nodes[j];
+      //     const distance = Math.sqrt(
+      //       Math.pow(node1.position.x - node2.position.x, 2) +
+      //       Math.pow(node1.position.y - node2.position.y, 2)
+      //     );
+      //     expect(distance).toBeGreaterThanOrEqual(minDistance);
+      //   }
+      // }
+    });
+
+    it('should respect custom node spacing', () => {
+      const nodes: Node[] = [
+        { id: 'node-1', type: 'agent', position: { x: 0, y: 0 }, data: {} },
+        { id: 'node-2', type: 'agent', position: { x: 0, y: 0 }, data: {} },
+      ];
+
+      const edges: Edge[] = [
+        { id: 'e1-2', source: 'node-1', target: 'node-2' },
+      ];
+
+      expect(() => {
+        const customSpacing = 100;
+        layoutService.applyHierarchicalLayout(nodes, edges, { nodeSpacing: customSpacing });
+      }).toThrow('Layout service not implemented');
+
+      // Expected behavior:
+      // const result = layoutService.applyHierarchicalLayout(nodes, edges, { nodeSpacing: 100 });
+      //
+      // const node1 = result.nodes.find(n => n.id === 'node-1')!;
+      // const node2 = result.nodes.find(n => n.id === 'node-2')!;
+      //
+      // // Distance should be at least the custom spacing
+      // const distance = Math.abs(node2.position.y - node1.position.y);
+      // expect(distance).toBeGreaterThanOrEqual(100);
+    });
+  });
+
+  describe('Layout Performance', () => {
+    it('should complete layout in <200ms for 10 nodes (REQUIREMENT)', () => {
+      const nodes: Node[] = Array.from({ length: 10 }, (_, i) => ({
+        id: `node-${i}`,
+        type: 'agent',
+        position: { x: 0, y: 0 },
+        data: { name: `Agent ${i}` },
+      }));
+
+      // Create a connected graph
+      const edges: Edge[] = Array.from({ length: 9 }, (_, i) => ({
+        id: `e${i}-${i + 1}`,
+        source: `node-${i}`,
+        target: `node-${i + 1}`,
+      }));
+
+      expect(() => {
+        const startTime = performance.now();
+        layoutService.applyHierarchicalLayout(nodes, edges);
+        const endTime = performance.now();
+        const duration = endTime - startTime;
+
+        // This will fail until implementation
+        expect(duration).toBeLessThan(200);
+      }).toThrow('Layout service not implemented');
+
+      // Expected behavior:
+      // const startTime = performance.now();
+      // const result = layoutService.applyHierarchicalLayout(nodes, edges);
+      // const endTime = performance.now();
+      // const duration = endTime - startTime;
+      //
+      // expect(duration).toBeLessThan(200); // REQUIREMENT: <200ms for 10 nodes
+      // expect(result.nodes).toHaveLength(10);
+    });
+
+    it('should handle large graphs efficiently (50 nodes)', () => {
+      const nodes: Node[] = Array.from({ length: 50 }, (_, i) => ({
+        id: `node-${i}`,
+        type: 'agent',
+        position: { x: 0, y: 0 },
+        data: { name: `Agent ${i}` },
+      }));
+
+      // Create edges with some complexity (not just linear)
+      const edges: Edge[] = [];
+      for (let i = 0; i < 49; i++) {
+        edges.push({
+          id: `e${i}-${i + 1}`,
+          source: `node-${i}`,
+          target: `node-${i + 1}`,
+        });
+        // Add some cross-edges for complexity
+        if (i % 5 === 0 && i + 2 < 50) {
+          edges.push({
+            id: `e${i}-${i + 2}`,
+            source: `node-${i}`,
+            target: `node-${i + 2}`,
+          });
+        }
+      }
+
+      expect(() => {
+        const startTime = performance.now();
+        layoutService.applyHierarchicalLayout(nodes, edges);
+        const endTime = performance.now();
+        const duration = endTime - startTime;
+
+        // Should still be reasonably fast (<1s)
+        expect(duration).toBeLessThan(1000);
+      }).toThrow('Layout service not implemented');
+    });
+  });
+
+  describe('Edge Routing', () => {
+    it('should preserve edge connections after layout', () => {
+      const nodes: Node[] = [
+        { id: 'a', type: 'agent', position: { x: 0, y: 0 }, data: {} },
+        { id: 'b', type: 'agent', position: { x: 0, y: 0 }, data: {} },
+        { id: 'c', type: 'agent', position: { x: 0, y: 0 }, data: {} },
+      ];
+
+      const edges: Edge[] = [
+        { id: 'e-a-b', source: 'a', target: 'b' },
+        { id: 'e-b-c', source: 'b', target: 'c' },
+      ];
+
+      expect(() => {
+        layoutService.applyHierarchicalLayout(nodes, edges);
+      }).toThrow('Layout service not implemented');
+
+      // Expected behavior:
+      // const result = layoutService.applyHierarchicalLayout(nodes, edges);
+      //
+      // // Edges should remain unchanged in structure
+      // expect(result.edges).toHaveLength(2);
+      // expect(result.edges.find(e => e.id === 'e-a-b')).toBeDefined();
+      // expect(result.edges.find(e => e.id === 'e-b-c')).toBeDefined();
+      //
+      // // Source and target should still match
+      // const edgeAB = result.edges.find(e => e.id === 'e-a-b')!;
+      // expect(edgeAB.source).toBe('a');
+      // expect(edgeAB.target).toBe('b');
+    });
+
+    it('should return layout dimensions (width, height)', () => {
+      const nodes: Node[] = [
+        { id: 'node-1', type: 'agent', position: { x: 0, y: 0 }, data: {} },
+        { id: 'node-2', type: 'agent', position: { x: 0, y: 0 }, data: {} },
+      ];
+
+      const edges: Edge[] = [
+        { id: 'e1-2', source: 'node-1', target: 'node-2' },
+      ];
+
+      expect(() => {
+        layoutService.applyHierarchicalLayout(nodes, edges);
+      }).toThrow('Layout service not implemented');
+
+      // Expected behavior:
+      // const result = layoutService.applyHierarchicalLayout(nodes, edges);
+      //
+      // expect(result).toHaveProperty('width');
+      // expect(result).toHaveProperty('height');
+      // expect(typeof result.width).toBe('number');
+      // expect(typeof result.height).toBe('number');
+      // expect(result.width).toBeGreaterThan(0);
+      // expect(result.height).toBeGreaterThan(0);
+    });
+
+    it('should handle disconnected components', () => {
+      const nodes: Node[] = [
+        { id: 'a1', type: 'agent', position: { x: 0, y: 0 }, data: {} },
+        { id: 'a2', type: 'agent', position: { x: 0, y: 0 }, data: {} },
+        { id: 'b1', type: 'agent', position: { x: 0, y: 0 }, data: {} },
+        { id: 'b2', type: 'agent', position: { x: 0, y: 0 }, data: {} },
+      ];
+
+      const edges: Edge[] = [
+        { id: 'e-a1-a2', source: 'a1', target: 'a2' },
+        { id: 'e-b1-b2', source: 'b1', target: 'b2' },
+        // No edges between a* and b* - two separate components
+      ];
+
+      expect(() => {
+        layoutService.applyHierarchicalLayout(nodes, edges);
+      }).toThrow('Layout service not implemented');
+
+      // Expected behavior:
+      // const result = layoutService.applyHierarchicalLayout(nodes, edges);
+      //
+      // // All nodes should still get positions
+      // expect(result.nodes).toHaveLength(4);
+      // result.nodes.forEach(node => {
+      //   expect(Number.isFinite(node.position.x)).toBe(true);
+      //   expect(Number.isFinite(node.position.y)).toBe(true);
+      // });
+    });
+  });
+
+  describe('Empty and Edge Cases', () => {
+    it('should handle empty node list', () => {
+      const nodes: Node[] = [];
+      const edges: Edge[] = [];
+
+      expect(() => {
+        layoutService.applyHierarchicalLayout(nodes, edges);
+      }).toThrow('Layout service not implemented');
+
+      // Expected behavior:
+      // const result = layoutService.applyHierarchicalLayout(nodes, edges);
+      // expect(result.nodes).toHaveLength(0);
+      // expect(result.edges).toHaveLength(0);
+    });
+
+    it('should handle single node with no edges', () => {
+      const nodes: Node[] = [
+        { id: 'lone-node', type: 'agent', position: { x: 0, y: 0 }, data: {} },
+      ];
+      const edges: Edge[] = [];
+
+      expect(() => {
+        layoutService.applyHierarchicalLayout(nodes, edges);
+      }).toThrow('Layout service not implemented');
+
+      // Expected behavior:
+      // const result = layoutService.applyHierarchicalLayout(nodes, edges);
+      // expect(result.nodes).toHaveLength(1);
+      // expect(result.nodes[0].position.x).toBeGreaterThanOrEqual(0);
+      // expect(result.nodes[0].position.y).toBeGreaterThanOrEqual(0);
+    });
+
+    it('should handle nodes with no connecting edges', () => {
+      const nodes: Node[] = [
+        { id: 'node-1', type: 'agent', position: { x: 0, y: 0 }, data: {} },
+        { id: 'node-2', type: 'agent', position: { x: 0, y: 0 }, data: {} },
+        { id: 'node-3', type: 'agent', position: { x: 0, y: 0 }, data: {} },
+      ];
+      const edges: Edge[] = [];
+
+      expect(() => {
+        layoutService.applyHierarchicalLayout(nodes, edges);
+      }).toThrow('Layout service not implemented');
+
+      // Expected behavior:
+      // const result = layoutService.applyHierarchicalLayout(nodes, edges);
+      // expect(result.nodes).toHaveLength(3);
+      //
+      // // All nodes should get valid positions
+      // result.nodes.forEach(node => {
+      //   expect(Number.isFinite(node.position.x)).toBe(true);
+      //   expect(Number.isFinite(node.position.y)).toBe(true);
+      // });
+    });
+  });
+});

flock/frontend/src/services/layout.ts

@@ -0,0 +1,146 @@
+import dagre from 'dagre';
+import { Node, Edge } from '@xyflow/react';
+
+/**
+ * Phase 4: Graph Visualization & Dual Views - Layout Service
+ *
+ * Provides Dagre-based hierarchical layout algorithm for automatic node positioning.
+ * Supports both vertical (TB) and horizontal (LR) layouts with configurable spacing.
+ *
+ * REQUIREMENT: Must complete <200ms for 10 nodes
+ * SPECIFICATION: docs/specs/003-real-time-dashboard/PLAN.md Phase 4
+ */
+
+export interface LayoutOptions {
+  direction?: 'TB' | 'LR' | 'BT' | 'RL';
+  nodeSpacing?: number;
+  rankSpacing?: number;
+}
+
+export interface LayoutResult {
+  nodes: Node[];
+  edges: Edge[];
+  width: number;
+  height: number;
+}
+
+// Default node dimensions
+const DEFAULT_NODE_WIDTH = 200;
+const DEFAULT_NODE_HEIGHT = 80;
+const MESSAGE_NODE_WIDTH = 150;
+const MESSAGE_NODE_HEIGHT = 60;
+
+// Default spacing (increased by 50% for better label visibility)
+const DEFAULT_NODE_SPACING = 75;  // Was 50
+const DEFAULT_RANK_SPACING = 150; // Was 100
+
+/**
+ * Get node dimensions based on node type
+ */
+function getNodeDimensions(node: Node): { width: number; height: number } {
+  if (node.type === 'message') {
+    return { width: MESSAGE_NODE_WIDTH, height: MESSAGE_NODE_HEIGHT };
+  }
+  return { width: DEFAULT_NODE_WIDTH, height: DEFAULT_NODE_HEIGHT };
+}
+
+/**
+ * Apply hierarchical layout using Dagre algorithm
+ *
+ * @param nodes - Array of nodes to layout
+ * @param edges - Array of edges defining connections
+ * @param options - Layout configuration options
+ * @returns Layout result with positioned nodes and graph dimensions
+ */
+export function applyHierarchicalLayout(
+  nodes: Node[],
+  edges: Edge[],
+  options: LayoutOptions = {}
+): LayoutResult {
+  const {
+    direction = 'TB',
+    nodeSpacing = DEFAULT_NODE_SPACING,
+    rankSpacing = DEFAULT_RANK_SPACING,
+  } = options;
+
+  // Handle empty graph
+  if (nodes.length === 0) {
+    return { nodes: [], edges, width: 0, height: 0 };
+  }
+
+  // Create a new directed graph
+  const graph = new dagre.graphlib.Graph();
+
+  // Set graph layout options
+  graph.setGraph({
+    rankdir: direction,
+    nodesep: nodeSpacing,
+    ranksep: rankSpacing,
+    marginx: 20,
+    marginy: 20,
+  });
+
+  // Default edge configuration
+  graph.setDefaultEdgeLabel(() => ({}));
+
+  // Add nodes to the graph with their dimensions
+  nodes.forEach((node) => {
+    const { width, height } = getNodeDimensions(node);
+    graph.setNode(node.id, { width, height });
+  });
+
+  // Add edges to the graph
+  edges.forEach((edge) => {
+    graph.setEdge(edge.source, edge.target);
+  });
+
+  // Run the layout algorithm
+  dagre.layout(graph);
+
+  // Extract positioned nodes
+  const layoutedNodes = nodes.map((node) => {
+    const nodeWithPosition = graph.node(node.id);
+
+    // Dagre positions nodes at their center, we need top-left corner
+    const { width, height } = getNodeDimensions(node);
+
+    return {
+      ...node,
+      position: {
+        x: nodeWithPosition.x - width / 2,
+        y: nodeWithPosition.y - height / 2,
+      },
+    };
+  });
+
+  // Get graph dimensions
+  const graphConfig = graph.graph();
+  const width = (graphConfig.width || 0) + 40; // Add margin
+  const height = (graphConfig.height || 0) + 40; // Add margin
+
+  return {
+    nodes: layoutedNodes,
+    edges,
+    width,
+    height,
+  };
+}
+
+/**
+ * Legacy function name for backwards compatibility
+ * Delegates to applyHierarchicalLayout
+ */
+export function applyDagreLayout(
+  nodes: Node[],
+  edges: Edge[],
+  direction: 'TB' | 'LR' = 'TB',
+  nodeSpacing?: number,
+  rankSpacing?: number
+): Node[] {
+  const result = applyHierarchicalLayout(nodes, edges, {
+    direction,
+    nodeSpacing,
+    rankSpacing
+  });
+  return result.nodes;
+}