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