langchain-ai / langchain-ai/langgraph
[Feature Proposal] Standard Reducers Library for Complex Parallel State Merging
- Dominant language
- Python
- Stars
- 41.8k
- Forks
- 7.1k
- Avg merge
- 23h 7m
- Merged PRs (30d)
- 30
Description
### Checked other resources
- [x] This is a bug, not a usage question.
- [x] I added a clear and descriptive title that summarizes this issue.
- [x] I used the GitHub search to find a similar question and didn't find it.
- [x] I am sure that this is a bug in LangGraph rather than my code.
- [x] The bug is not resolved by updating to the latest stable version of LangGraph (or the specific integration package).
- [x] This is not related to the langchain-community package.
- [x] I posted a self-contained, minimal, reproducible example. A maintainer can copy it and run it AS IS.
### Related Issues / PRs
Related PR: #7239
### Reproduction Steps / Example Code (Python)
```python
# [CURRENT PAIN POINT]
# Developers have to manually write boilerplate reducers for every complex state:
def my_custom_reducer(current: dict, update: dict) -> dict:
# ... tedious custom deep merge and conflict resolution logic ...
return merged_dict
# [PROPOSED SOLUTION - IMPLEMENTED IN PR #7239]
# Developers can simply import production-ready reducers out-of-the-box!
from typing import Annotated
from typing_extensions import TypedDict
from langgraph.graph.reducers import smart_merge_dict, combine_distinct
class AgentState(TypedDict):
# Automatically deep merges dicts and upgrades conflicting scalars to lists!
context: Annotated[dict, smart_merge_dict]
# Automatically deduplicates lists!
tags: Annotated[list[str], combine_distinct]
```
### Error Message and Stack Trace (if applicable)
```shell
N/A - This is a Feature Proposal with a ready-to-merge PR (#7239).
The "error" being solved here is the **silent data loss** that developers unknowingly face when relying on default state overwrites in parallel node executions.
```
### Description
*(Note: Using this required field to describe a Feature Proposal, as the feature template is unavailable. I already have a fully tested PR ready for review: #7239)*
**What I am doing:**
Building complex parallel agents (e.g., Map-Reduce workflows) in LangGraph where multiple nodes write to the same state keys simultaneously.
**What is currently happening (The Problem):**
By default, LangGraph uses "last-write-wins", which silently overwrites and loses data from parallel nodes. The alternative, `operator.add`, strictly requires the state to be a list, which is inflexible when dealing with complex nested dictionary states. Developers are forced to repeatedly write boilerplate, CRDT-like reducers from scratch for every project to prevent data loss.
**What I expect to happen (The Solution):**
LangGraph should provide a standard library of production-ready reducers out-of-the-box. I have implemented a `langgraph.graph.reducers` module (including `smart_merge_dict`, `combine_distinct`, and `first_wins`) that intelligently deep-merges dictionaries, extends lists, and upgrades conflicting scalars to lists to preserve all historical signals.
Please see PR #7239 for the complete, fully-tested implementation.
### System Info
System Information
------------------
> OS: Darwin
> OS Version: Darwin Kernel Version 23.2.0: Wed Nov 15 21:54:55 PST 2023; root:xnu-10002.61.3~2/RELEASE_ARM64_T8122
> Python Version: 3.12.13 (main, Mar 18 2026, 15:36:07) [Clang 15.0.0 (clang-1500.3.9.4)]
Package Information
-------------------
> langchain_core: 1.2.20
> langchain: 1.2.12
> langchain_community: 0.4.1
> langsmith: 0.7.20
> langchain_classic: 1.0.3
> langchain_text_splitters: 1.1.1
> langgraph_sdk: 0.3.12
Contributor guide
Research direction
Start with the proposed langgraph.graph.reducers module and the implementation and tests in PR #7239. Review how smart_merge_dict, combine_distinct, and first_wins are specified for parallel state updates, then verify that the documented reducer behavior is covered by the existing tests and matches the proposal.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- ai, distributed-systems
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Clearly specified
- Newbie friendliness
- 20/100