langchain-ai/langgraph
1
0
Fork 0
mirror of https://github.com/langchain-ai/langgraph.git synced 2026-07-15 12:35:43 -04:00
Code Issues 314 Packages Projects Releases 17 Wiki Activity

[PR #6485] feat(langgraph): add probabilistic routing via negative nodes #5066

New Issue
Closed
opened 2026-02-20 17:51:10 -05:00 by yindo · 0 comments
yindo commented 2026-02-20 17:51:10 -05:00
Owner
Copy Link
Copy Source

Original Pull Request: https://github.com/langchain-ai/langgraph/pull/6485

State: closed
Merged: No

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

  • PR title follows format: {TYPE}({SCOPE}): {DESCRIPTION}
  • Type: feat (new feature)
  • Scope: langgraph (core package)
  • Unit tests added (18 tests, no network dependencies)
  • Integration example added
  • make format passes
  • make lint passes
  • make test passes (all 18 tests pass)
  • Changes are backwards compatible
  • No unnecessary changes to pyproject.toml
  • Optional dependencies imported inside functions
  • All functions have complete type hints
  • All functions have docstrings
  • Error messages are clear and actionable
  • 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
**Original Pull Request:** https://github.com/langchain-ai/langgraph/pull/6485 **State:** closed **Merged:** No --- ## 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
yindo added the pull-request label 2026-02-20 17:51:10 -05:00
yindo closed this issue 2026-02-20 17:51:10 -05:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
agents
awaiting author revision
bug
change
chat models
checkpointer
ci
code quality
code quality
dependencies
documentation
drawing
duplicate
enhancement
good first issue
help wanted
invalid
maintainer
meta
missing information
not maintained by langchain
open-swe-auto
open-swe-max
open-swe-max-auto
pending
performance
pull-request
Mirrored from GitHub Pull Request
 question
requires design
sdk
server
stale
studio
tests
type checking
usage question
v0.5
v1.1
No Label pull-request
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
yindo
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: langchain-ai/langgraph#5066
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?