feat(langgraph): add probabilistic routing via negative nodes

[rachitjindal56]

Description

This PR introduces negative nodes - a new node type in LangGraph that enables probabilistic routing to multiple destination nodes. Negative nodes are special nodes marked with metadata that allow graphs to route execution probabilistically based on a probability distribution.

Key Features

• New add_negative_node() method in StateGraph for creating probabilistic router nodes
• Extended add_edge() method to support nodes_prob_distribution parameter
• Probabilistic routing using numpy's np.random.choice() for fair random selection
• Comprehensive validation of probability distributions (must sum to 1.0, all non-negative)
• Full backwards compatibility - no breaking changes to existing API

Technical Implementation

1. Negative nodes are marked with metadata flag __node_type_negative_langgraph__: True
2. When adding edges from negative nodes, users provide a list of destinations and probability distribution
3. Implementation converts probabilistic edges into conditional edges internally
4. Routing decisions made at runtime using numpy's random choice function

Dependencies

No new dependencies required. Uses existing numpy dependency already in LangGraph.

Tests Added

• Location: libs/langgraph/tests/test_negative_nodes.py
• Coverage: 18 comprehensive edge case tests
• All tests pass without network dependencies

Test Coverage Includes:

• ✅ Negative node creation and metadata validation
• ✅ Probability distribution validation (sum to 1.0, non-negative)
• ✅ Single destination routing with probabilities
• ✅ Multiple destination routing
• ✅ Error handling for invalid distributions
• ✅ Backwards compatibility verification
• ✅ START and END node handling
• ✅ Conditional edge integration

Documentation

• Location: docs/docs/integrations/negative_nodes.ipynb
• Includes: Complete examples, use cases, and integration patterns

Examples Provided:

1. Basic negative node setup and usage
2. A/B testing pattern (80% version A, 20% version B)
3. Load balancing across processors
4. Real-world use case demonstrations

Validation

• [x] PR title follows format: {TYPE}({SCOPE}): {DESCRIPTION}
• [x] Type: feat (new feature)
• [x] Scope: langgraph (core package)
• [x] Unit tests added (18 tests, no network dependencies)
• [x] Integration example added
• [x] make format passes
• [x] make lint passes
• [x] make test passes (all 18 tests pass)
• [x] Changes are backwards compatible
• [x] No unnecessary changes to pyproject.toml
• [x] Optional dependencies imported inside functions
• [x] All functions have complete type hints
• [x] All functions have docstrings
• [x] Error messages are clear and actionable
• [x] Code follows LangGraph conventions

Breaking Changes

None - This is a fully backwards compatible addition.

• add_node() unchanged
• add_edge() works same for single start/end (new param optional)
• add_conditional_edges() unchanged
• All existing tests pass

Files Changed

1. libs/langgraph/langgraph/graph/state.py (modified)

   • Added add_negative_node() method
   • Extended add_edge() for probabilistic routing
   • Added validation and bug fixes

2. libs/langgraph/tests/test_negative_nodes.py (new)

   • 18 comprehensive edge case tests

3. docs/docs/integrations/negative_nodes.ipynb (new)

   • Complete usage examples and patterns

[vercel[bot]]

@rachitjindal56 is attempting to deploy a commit to the LangChain Team on Vercel.

A member of the Team first needs to authorize it.

[hinthornw]

Is this an honest feature request or did you just ask Claude for a fun pr to open?

Where do you need this functionality?

[hinthornw]

In general, I don't plan to add a heavy dependency (numpy) to langgraph and extend our API with features that can already be addressed within the existing API unless you have a compelling reason otherwise.

[casparb]

@rachitjindal56 Achieve this natively with conditional edges: https://docs.langchain.com/oss/python/langgraph/graph-api#conditional-edges