LangGraph Guardian

Prevent silent failures and catch implementation errors in LangGraph pipelines before runtime.

Core Problem This Solves

LangGraph's decoupled architecture causes silent failures:

• •state.get("extracted_rate") returns [] when key is "extracted_rates" - no error
• •Node A writes provider_map, Node B reads provider_maps - silent empty list
• •Incomplete returns missing required keys - downstream nodes fail mysteriously
• •Copy-paste errors across nodes accumulate over time

Quick Commands

# Validate a single node
python scripts/lint_node.py src/langgraph/nodes/layer4/rate_extractor.py

# Trace a flow to find where it breaks
python scripts/trace_flow.py src/langgraph/nodes --flow "layer1,layer2,layer3"

# Check all nodes for completeness
python scripts/check_completeness.py src/langgraph/nodes

# Validate naming consistency across all nodes
python scripts/validate_naming.py src/langgraph/nodes --state-file src/langgraph/state.py

# Pre-commit validation (all checks)
python scripts/preflight.py src/langgraph/nodes --state-file src/langgraph/state.py

Validation Categories

1. State Key Validation

• •Keys used match TypedDict definition exactly
• •No typos in state.get() calls
• •No undeclared keys written

2. Flow Tracing

• •Simulates state propagation through nodes
• •Finds where chains break (key written in layer 4, read in layer 3)
• •Detects missing dependencies

3. Completeness Checks

• •Required error handling patterns present
• •Escalation creation on failures
• •All documented output keys returned
• •Logging for long operations

4. Naming Consistency

• •State keys follow conventions (snake_case, plural for lists)
• •Node names match file names
• •Layer IDs match directory structure

Pre-Implementation Checklist

Before writing a new node, verify:

1. • All input keys exist in TiCPipelineState
2. • All output keys exist in TiCPipelineState
3. • Input keys are written by earlier layers
4. • Output keys are read by later layers (or are terminal)
5. • Error handling returns empty + escalation, not just {}
6. • List outputs accumulate, not overwrite

Common Mistakes Reference

See references/common_mistakes.md for patterns like:

• •Silent empty returns
• •State key typos
• •Missing await
• •Overwriting vs accumulating lists
• •Incomplete error handling

Integration with Development Workflow

1. •Before implementing: Run trace_flow.py to verify inputs available
2. •While implementing: Run lint_node.py on save
3. •Before commit: Run preflight.py for full validation
4. •When debugging: Run trace_flow.py --trace KEY to find breaks