filter-downstream-nodes.ts

Overview

This file provides utility functions for traversing and filtering downstream nodes in a directed graph structure, specifically within the context of agent and tool operators in a workflow or pipeline system. The graph is represented by edges connecting nodes, where each edge has a source node and a target node, along with metadata such as handles that define the type or role of connection.

The main purpose of the file is to offer reusable functions to identify all downstream nodes or subsets thereof (e.g., agent nodes, tool nodes) starting from one or more given nodes, respecting specific filtering criteria based on edge properties.

Detailed Descriptions of Functions

1. filterAllDownstreamNodeIds

function filterAllDownstreamNodeIds(
  edges: Edge[],
  nodeIds: string[],
  predicate: (edge: Edge) => boolean,
): string[]

Purpose

Recursively finds and returns a list of all downstream node IDs connected to the given list of starting node IDs, filtered by a provided predicate function applied to edges.

Parameters

• edges (Edge[]): Array of graph edges. Each edge has properties including source, target, and sourceHandle.

• nodeIds (string[]): Array of starting node IDs from which to begin searching downstream.

• predicate ((edge: Edge) => boolean): A function to filter edges. Only edges that satisfy this predicate are followed.

Returns

• string[]: A flattened array of unique downstream node IDs reachable via edges satisfying the predicate.

Usage Example

const downstreamNodeIds = filterAllDownstreamNodeIds(
  edges,
  ['node1', 'node2'],
  (edge) => edge.sourceHandle === NodeHandleId.AgentBottom
);

This example finds all downstream nodes starting from node1 and node2 following edges whose sourceHandle is AgentBottom.

Implementation Details

• Uses recursion to traverse the graph depth-first.

• Filters edges from the current node(s) by the predicate.

• Accumulates downstream nodes uniquely (no duplicates).

• Combines results from multiple starting nodes.

2. filterAllDownstreamAgentAndToolNodeIds

function filterAllDownstreamAgentAndToolNodeIds(
  edges: Edge[],
  nodeIds: string[],
): string[]

Purpose

Finds all downstream node IDs that are either agent operators at the bottom handle or tool operators, starting from given node IDs.

Parameters

• edges (Edge[]): The graph edges.

• nodeIds (string[]): Starting node IDs.

Returns

• string[]: All downstream agent and tool node IDs.

Usage Example

const downstreamAgentAndToolNodes = filterAllDownstreamAgentAndToolNodeIds(edges, ['agentNode1']);

This returns all downstream nodes connected via edges with sourceHandle of either AgentBottom or Tool.

Implementation Details

• Delegates to filterAllDownstreamNodeIds with a predicate that checks for AgentBottom or Tool source handles.

3. filterAllDownstreamAgentNodeIds

function filterAllDownstreamAgentNodeIds(
  edges: Edge[],
  nodeIds: string[],
): string[]

Purpose

Finds all downstream agent operator node IDs connected from given starting nodes, where edges have the source handle AgentBottom.

Parameters

• edges (Edge[]): The graph edges.

• nodeIds (string[]): Starting node IDs.

Returns

• string[]: All downstream agent node IDs.

Usage Example

const downstreamAgentNodes = filterAllDownstreamAgentNodeIds(edges, ['nodeX']);

Returns all agent nodes reachable downstream from nodeX.

Implementation Details

• Uses filterAllDownstreamNodeIds with a predicate filtering edges by AgentBottom source handle only.

4. filterDownstreamAgentNodeIds

function filterDownstreamAgentNodeIds(
  edges: Edge[],
  nodeId?: string,
): string[]

Purpose

Retrieves the immediate (direct child) downstream agent node IDs connected from a single given node via edges with source handle AgentBottom.

Parameters

• edges (Edge[]): The graph edges.

• nodeId (string | undefined): The single node ID to find direct downstream agent nodes for. If undefined, returns an empty array.

Returns

• string[]: Array of direct downstream agent node IDs.

Usage Example

const directAgentChildren = filterDownstreamAgentNodeIds(edges, 'nodeA');

Gets only the immediate agent nodes connected downstream from nodeA.

Implementation Details

• Filters edges for those with source matching nodeId and source handle AgentBottom.

• Maps filtered edges to their target node IDs.

• Does not recurse; only direct children returned.

Implementation & Algorithm Notes

• The recursive function filterAllDownstreamNodeIds traverses the graph depth-first, filtering edges by the predicate to only follow relevant connections.

• To avoid duplicates, it checks if a node ID is already included before adding it to the accumulator array.

• The other functions are specialized wrappers around the general recursive function with specific filtering predicates related to agent and tool node types.

• The handle identifiers (NodeHandleId.AgentBottom, NodeHandleId.Tool) imply that edges are categorized by roles or connection points, enabling precise traversal control.

Interaction with Other System Components

• Edges and Nodes: This file operates on Edge objects imported from @xyflow/react, which likely define the graph structure of nodes and their connections.

• NodeHandleId Constants: These constants from ../constant define the types of edge handles used for filtering (e.g., differentiating agent bottom handles from tool handles).

• These utilities are presumably used by other parts of the system responsible for visualizing, analyzing, or executing workflows involving agent and tool nodes, enabling operations like dependency resolution or propagation of updates downstream.

• The functions help isolate downstream nodes for tasks such as updating state, running computations, or visual highlighting of affected nodes.

Mermaid Diagram: Function Flowchart

flowchart TD
    A[filterAllDownstreamNodeIds] -->|calls recursively| A
    B[filterAllDownstreamAgentAndToolNodeIds] --> A
    C[filterAllDownstreamAgentNodeIds] --> A
    D[filterDownstreamAgentNodeIds]

    style A fill:#f9f,stroke:#333,stroke-width:2px
    style B fill:#bbf,stroke:#333,stroke-width:1px
    style C fill:#bbf,stroke:#333,stroke-width:1px
    style D fill:#afa,stroke:#333,stroke-width:1px

    B --> |uses predicate: AgentBottom or Tool| A
    C --> |uses predicate: AgentBottom| A

Summary

The filter-downstream-nodes.ts file is a utility module focused on graph traversal to extract downstream node IDs from a directed graph of operators and tools. It provides flexible and reusable functions that filter edges by role-based handles to identify relevant downstream nodes either recursively or directly connected.

These utilities support workflows or pipeline management by enabling precise identification of dependent nodes, facilitating operations such as update propagation, execution planning, or visualization in systems that model complex agent and tool interactions.