@illuma-ai/agents 1.0.90 → 1.0.93

package/src/graphs/__tests__/multi-agent-edges.test.ts

@@ -0,0 +1,237 @@
+/**
+ * Unit tests for multi-agent edge categorization, starting node identification,
+ * and parallel group computation in MultiAgentGraph.
+ *
+ * These test the edge classification rules without instantiating the full graph:
+ * - Explicit EdgeType.HANDOFF → handoff
+ * - Explicit EdgeType.DIRECT → direct
+ * - Condition-based edges → handoff (always, regardless of edgeType)
+ * - Default single→single → handoff
+ * - Default single→many → direct (fan-out pattern)
+ */
+import { EdgeType } from '@/common';
+import type { GraphEdge, BaseGraphState } from '@/types';
+
+/**
+ * Extracted categorization logic matching MultiAgentGraph.categorizeEdges().
+ * Kept in sync with the private method for testability.
+ */
+function categorizeEdges(edges: GraphEdge[]): {
+  directEdges: GraphEdge[];
+  handoffEdges: GraphEdge[];
+} {
+  const directEdges: GraphEdge[] = [];
+  const handoffEdges: GraphEdge[] = [];
+
+  for (const edge of edges) {
+    if (edge.edgeType === EdgeType.DIRECT) {
+      directEdges.push(edge);
+    } else if (edge.edgeType === EdgeType.HANDOFF || edge.condition != null) {
+      handoffEdges.push(edge);
+    } else {
+      const destinations = Array.isArray(edge.to) ? edge.to : [edge.to];
+      const sources = Array.isArray(edge.from) ? edge.from : [edge.from];
+
+      if (sources.length === 1 && destinations.length > 1) {
+        directEdges.push(edge);
+      } else {
+        handoffEdges.push(edge);
+      }
+    }
+  }
+
+  return { directEdges, handoffEdges };
+}
+
+/**
+ * Extracted starting node logic matching MultiAgentGraph.analyzeGraph().
+ */
+function findStartingNodes(
+  edges: GraphEdge[],
+  agentIds: string[]
+): Set<string> {
+  const hasIncomingEdge = new Set<string>();
+
+  for (const edge of edges) {
+    const destinations = Array.isArray(edge.to) ? edge.to : [edge.to];
+    destinations.forEach((dest) => hasIncomingEdge.add(dest));
+  }
+
+  const startingNodes = new Set<string>();
+  for (const agentId of agentIds) {
+    if (!hasIncomingEdge.has(agentId)) {
+      startingNodes.add(agentId);
+    }
+  }
+
+  if (startingNodes.size === 0 && agentIds.length > 0) {
+    startingNodes.add(agentIds[0]);
+  }
+
+  return startingNodes;
+}
+
+// ---------------------------------------------------------------------------
+// Edge categorization
+// ---------------------------------------------------------------------------
+describe('edge categorization', () => {
+  it('classifies explicit EdgeType.HANDOFF as handoff', () => {
+    const edges: GraphEdge[] = [
+      { from: 'a', to: 'b', edgeType: EdgeType.HANDOFF },
+    ];
+    const { directEdges, handoffEdges } = categorizeEdges(edges);
+    expect(handoffEdges).toHaveLength(1);
+    expect(directEdges).toHaveLength(0);
+  });
+
+  it('classifies explicit EdgeType.DIRECT as direct', () => {
+    const edges: GraphEdge[] = [
+      { from: 'a', to: 'b', edgeType: EdgeType.DIRECT },
+    ];
+    const { directEdges, handoffEdges } = categorizeEdges(edges);
+    expect(directEdges).toHaveLength(1);
+    expect(handoffEdges).toHaveLength(0);
+  });
+
+  it('classifies condition-based edges as handoff regardless of edgeType', () => {
+    const condition = (_state: BaseGraphState) => true;
+    const edges: GraphEdge[] = [
+      { from: 'a', to: 'b', condition },
+      { from: 'c', to: 'd', condition, edgeType: EdgeType.HANDOFF },
+    ];
+    const { directEdges, handoffEdges } = categorizeEdges(edges);
+    expect(handoffEdges).toHaveLength(2);
+    expect(directEdges).toHaveLength(0);
+  });
+
+  it('defaults single→single edges to handoff', () => {
+    const edges: GraphEdge[] = [{ from: 'supervisor', to: 'worker' }];
+    const { directEdges, handoffEdges } = categorizeEdges(edges);
+    expect(handoffEdges).toHaveLength(1);
+    expect(directEdges).toHaveLength(0);
+  });
+
+  it('defaults single→many edges to direct (fan-out pattern)', () => {
+    const edges: GraphEdge[] = [
+      { from: 'coordinator', to: ['analyst1', 'analyst2', 'analyst3'] },
+    ];
+    const { directEdges, handoffEdges } = categorizeEdges(edges);
+    expect(directEdges).toHaveLength(1);
+    expect(handoffEdges).toHaveLength(0);
+  });
+
+  it('defaults many→single edges to handoff', () => {
+    const edges: GraphEdge[] = [
+      { from: ['analyst1', 'analyst2'], to: 'summarizer' },
+    ];
+    const { directEdges, handoffEdges } = categorizeEdges(edges);
+    expect(handoffEdges).toHaveLength(1);
+    expect(directEdges).toHaveLength(0);
+  });
+
+  it('correctly categorizes a mixed set of edges', () => {
+    const edges: GraphEdge[] = [
+      // Explicit direct: sequential chain
+      { from: 'researcher', to: 'analyst', edgeType: EdgeType.DIRECT },
+      // Fan-out: defaults to direct
+      { from: 'analyst', to: ['reviewer1', 'reviewer2'] },
+      // Explicit handoff: dynamic routing
+      { from: 'supervisor', to: 'specialist', edgeType: EdgeType.HANDOFF },
+      // Default single→single: handoff
+      { from: 'triage', to: 'handler' },
+      // Condition-based: always handoff
+      { from: 'router', to: 'a', condition: () => true },
+    ];
+
+    const { directEdges, handoffEdges } = categorizeEdges(edges);
+    expect(directEdges).toHaveLength(2); // explicit direct + fan-out
+    expect(handoffEdges).toHaveLength(3); // explicit handoff + default single→single + condition
+  });
+
+  it('handles empty edges array', () => {
+    const { directEdges, handoffEdges } = categorizeEdges([]);
+    expect(directEdges).toHaveLength(0);
+    expect(handoffEdges).toHaveLength(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Starting node identification
+// ---------------------------------------------------------------------------
+describe('starting node identification', () => {
+  it('identifies nodes with no incoming edges as starting nodes', () => {
+    const edges: GraphEdge[] = [
+      { from: 'a', to: 'b' },
+      { from: 'b', to: 'c' },
+    ];
+    const startingNodes = findStartingNodes(edges, ['a', 'b', 'c']);
+    expect(startingNodes).toEqual(new Set(['a']));
+  });
+
+  it('identifies multiple starting nodes when graph has parallel roots', () => {
+    const edges: GraphEdge[] = [
+      { from: 'a', to: 'c' },
+      { from: 'b', to: 'c' },
+    ];
+    const startingNodes = findStartingNodes(edges, ['a', 'b', 'c']);
+    expect(startingNodes).toEqual(new Set(['a', 'b']));
+  });
+
+  it('falls back to first agent when all have incoming edges (cycle)', () => {
+    const edges: GraphEdge[] = [
+      { from: 'a', to: 'b' },
+      { from: 'b', to: 'a' },
+    ];
+    const startingNodes = findStartingNodes(edges, ['a', 'b']);
+    expect(startingNodes.size).toBe(1);
+    expect(startingNodes.has('a')).toBe(true);
+  });
+
+  it('handles array-based to field in edges', () => {
+    const edges: GraphEdge[] = [
+      { from: 'coordinator', to: ['worker1', 'worker2'] },
+    ];
+    const startingNodes = findStartingNodes(edges, [
+      'coordinator',
+      'worker1',
+      'worker2',
+    ]);
+    expect(startingNodes).toEqual(new Set(['coordinator']));
+  });
+
+  it('returns empty set for empty agent list', () => {
+    const startingNodes = findStartingNodes([], []);
+    expect(startingNodes.size).toBe(0);
+  });
+
+  it('handles single agent with no edges', () => {
+    const startingNodes = findStartingNodes([], ['solo-agent']);
+    expect(startingNodes).toEqual(new Set(['solo-agent']));
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Edge type enum value stability
+// ---------------------------------------------------------------------------
+describe('EdgeType values match GraphEdge string literals', () => {
+  it('HANDOFF matches the string used in MongoDB documents', () => {
+    // ranger stores edges in MongoDB with string values
+    // This ensures the enum stays compatible
+    expect(EdgeType.HANDOFF).toBe('handoff');
+  });
+
+  it('DIRECT matches the string used in MongoDB documents', () => {
+    expect(EdgeType.DIRECT).toBe('direct');
+  });
+
+  it('categorization works with string values cast as EdgeType', () => {
+    // Simulates data coming from MongoDB where edgeType is stored as string
+    const edges: GraphEdge[] = [
+      { from: 'a', to: 'b', edgeType: 'handoff' as EdgeType },
+      { from: 'c', to: 'd', edgeType: 'direct' as EdgeType },
+    ];
+    const { directEdges, handoffEdges } = categorizeEdges(edges);
+    expect(handoffEdges).toHaveLength(1);
+    expect(directEdges).toHaveLength(1);
+  });
+});