State Flow Visualizer

Analyze LangGraph state mutations and generate visual representations of data flow between nodes.

Capabilities

1. •State Flow Diagrams - Generate Mermaid flowcharts showing node-to-state-key relationships
2. •Key Tracing - Track a specific state key through all read/write operations
3. •Dependency Analysis - Show which nodes depend on outputs from other nodes
4. •Orphan Detection - Find state keys that are written but never read (or vice versa)
5. •Layer Analysis - Visualize state flow within and between layers

Quick Start

Run the analyzer on a LangGraph nodes directory:

python scripts/analyze_state_flow.py /path/to/src/langgraph/nodes

Generate a Mermaid diagram:

python scripts/analyze_state_flow.py /path/to/src/langgraph/nodes --output mermaid

Trace a specific key:

python scripts/analyze_state_flow.py /path/to/src/langgraph/nodes --trace extracted_rates

Output Formats

Mermaid Diagram

flowchart LR
    subgraph Layer2["Layer 2: File Intelligence"]
        mrf_expert[mrf_expert]
    end
    subgraph State
        mrf_structures([mrf_structures])
        provider_reference_maps([provider_reference_maps])
    end
    mrf_expert -->|writes| mrf_structures
    mrf_expert -->|writes| provider_reference_maps
    rate_extractor -->|reads| provider_reference_maps

JSON Report

{
  "nodes": [...],
  "state_keys": [...],
  "reads": [...],
  "writes": [...],
  "orphans": {"written_never_read": [], "read_never_written": []},
  "dependencies": [...]
}

Integration with TiC Pipeline

For TiC-specific analysis, the tool understands:

• •Layer organization (layer0-layer8)
• •TiCPipelineState TypedDict structure
• •BaseLLMNode and BaseDeterministicNode patterns
• •State update patterns via update_layer_status()

Commands

Interpreting Results

Healthy Patterns

• •Each state key has at least one writer and one reader
• •Writers execute before readers (layer ordering)
• •No circular dependencies within a layer

Warning Signs

• •Orphan writes: State key populated but never used downstream
• •Orphan reads: Node expects state key that no node populates
• •Cross-layer cycles: Later layer writes key read by earlier layer
• •Shadow writes: Multiple nodes write same key (potential race condition)

Troubleshooting Common Issues

"extracted_rates is empty at layer 6"

Run: python scripts/analyze_state_flow.py . --trace extracted_rates

Look for:

1. •Which node should write extracted_rates
2. •Whether that node's layer executes before layer 6
3. •Whether the writing node has error handling that silently returns []

"State key not found in analysis"

The key may be:

• •Dynamically constructed (e.g., state.get(f"{prefix}_rates"))
• •Set in initial state factory, not by a node
• •Populated by external process

Check state.py for initial state values.