mirror of
https://github.com/bytedance/deer-flow.git
synced 2026-11-20 11:20:35 +00:00
* fix(threads): reject a state update as_node LangGraph cannot compile
POST /threads/{id}/state passes the client's as_node to the state
mutation graph as its only node. LangGraph refuses __start__, __end__,
its other reserved names and names containing ':' or '|', and that
compile runs before the route's error handling, so those values ended in
an unhandled 500.
Check the name in the request model with the same rules, so it is a 422
on the as_node field before any graph is built or state is written. A
parity test keeps the check aligned with LangGraph's own compile.
* docs(runtime): note the LangGraph floor the reserved-name check was verified on
* docs(checkpoints): re-anchor checkpoint_state rows and list validate_state_mutation_node
The new function shifts the cstate line ranges the reference page cites
for CheckpointStateAccessor.bind and build_state_mutation_graph.
267 lines
12 KiB
Python
267 lines
12 KiB
Python
"""Materialized checkpoint-state access and state-only mutation graphs.
|
|
|
|
:class:`CheckpointStateAccessor` is the single choke point for thread
|
|
checkpoint-state reads and writes. It binds a compiled graph (which carries
|
|
the mode-matched channel schema), a checkpointer, and the frozen channel mode:
|
|
every operation injects the mode marker into the config and passes the
|
|
compatibility gate before touching state. Delta checkpoints store no full
|
|
``channel_values`` — raw saver reads see sentinels — so consumers must go
|
|
through this accessor instead of calling the checkpointer directly.
|
|
|
|
:func:`build_state_mutation_graph` compiles a state-only graph (one no-op
|
|
node, entry = finish) for wholesale state replacement such as rollback
|
|
restore and context compaction: it shares the agent graph's checkpoint
|
|
machinery but schedules no pending nodes, so the written head stays idle.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
from dataclasses import dataclass
|
|
from typing import Any
|
|
|
|
from deerflow.agents.thread_state import get_thread_state_schema
|
|
from deerflow.config.database_config import CheckpointChannelMode
|
|
from deerflow.runtime.checkpoint_mode import (
|
|
aensure_checkpoint_mode_compatible,
|
|
ensure_checkpoint_mode_compatible,
|
|
inject_checkpoint_mode,
|
|
raise_if_checkpoint_tuple_incompatible,
|
|
raise_if_snapshot_incompatible,
|
|
)
|
|
|
|
|
|
def _finish_state_mutation(_state: dict[str, Any]) -> dict[str, Any]:
|
|
return {}
|
|
|
|
|
|
def validate_state_mutation_node(as_node: str) -> str:
|
|
"""Return *as_node*, or raise ``ValueError`` when LangGraph refuses it as a node name.
|
|
|
|
:func:`build_state_mutation_graph` registers ``as_node`` as the graph's
|
|
only node, and LangGraph refuses ``__start__``, ``__end__``, its other
|
|
reserved names and any name containing a namespace separator (``|``) or
|
|
task separator (``:``). Callers that take the name from a client check it
|
|
here first, so a bad name is an input error and not a failed compile.
|
|
The reserved set is private to LangGraph; recheck this import when
|
|
upgrading LangGraph (verified against 1.2.9 and 1.2.14).
|
|
"""
|
|
from langgraph._internal._constants import NS_END, NS_SEP, RESERVED
|
|
from langgraph.constants import END, START
|
|
|
|
if as_node in (START, END) or as_node in RESERVED:
|
|
raise ValueError(f"Node name {as_node!r} is reserved by LangGraph")
|
|
for character in (NS_SEP, NS_END):
|
|
if character in as_node:
|
|
raise ValueError(f"Node name must not contain {character!r}")
|
|
return as_node
|
|
|
|
|
|
def build_state_mutation_graph(
|
|
as_node: str,
|
|
mode: CheckpointChannelMode,
|
|
state_schema: Any | None = None,
|
|
*,
|
|
snapshot_frequency: int | None = None,
|
|
) -> Any:
|
|
"""Compile a state-only graph whose single writer node finishes immediately.
|
|
|
|
``update_state(..., as_node=...)`` requires the node to be registered in
|
|
the graph; a dedicated single-node graph applies reducer writes and
|
|
finishes, so the mutation checkpoint schedules no agent nodes and has no
|
|
pending ``next`` nodes.
|
|
|
|
``state_schema`` must be the thread's *effective* schema (the class the
|
|
assistant graph was compiled with) whenever the write carries materialized
|
|
state: the base ThreadState fallback does not know channels contributed by
|
|
custom middleware, and writes to unknown channels are silently discarded.
|
|
The fallback resolves the delta snapshot cadence explicit arg ->
|
|
process-frozen -> config default; an explicit ``state_schema`` already
|
|
carries its cadence in its identity.
|
|
"""
|
|
if not as_node:
|
|
raise ValueError("as_node is required for checkpoint state mutation")
|
|
from langgraph.graph import StateGraph
|
|
|
|
builder = StateGraph(state_schema if state_schema is not None else get_thread_state_schema(mode, snapshot_frequency))
|
|
builder.add_node(as_node, _finish_state_mutation)
|
|
builder.set_entry_point(as_node)
|
|
builder.set_finish_point(as_node)
|
|
return builder.compile()
|
|
|
|
|
|
def graph_state_schema(graph: Any) -> Any | None:
|
|
"""Return the state schema class a compiled graph was built with.
|
|
|
|
The schema is the first entry of ``StateGraph.schemas`` (state schema is
|
|
registered before input/output schemas). Returns ``None`` for stub
|
|
accessors in tests that do not wrap a real compiled graph.
|
|
"""
|
|
schemas = getattr(getattr(graph, "builder", None), "schemas", None)
|
|
if not schemas:
|
|
return None
|
|
return next(iter(schemas))
|
|
|
|
|
|
def graph_writable_channels(graph: Any) -> frozenset[str] | None:
|
|
"""Return the user-visible state channel names of a compiled graph.
|
|
|
|
Excludes Pregel-internal channels (``__*``) and branch fan-in channels
|
|
(``branch:*``). Returns ``None`` when the graph does not expose channels
|
|
(stub accessors), so callers can fall back to the base ThreadState set.
|
|
"""
|
|
channels = getattr(graph, "channels", None)
|
|
if not channels:
|
|
return None
|
|
return frozenset(name for name in channels if not name.startswith("__") and not name.startswith("branch:"))
|
|
|
|
|
|
def graph_reducer_channels(graph: Any) -> frozenset[str] | None:
|
|
"""Return channel names whose writes merge through a reducer.
|
|
|
|
Covers classic reducers (``BinaryOperatorAggregate``) and delta channels:
|
|
both require ``Overwrite`` wrapping for replace-style writes, in any mode.
|
|
Returns ``None`` when the graph does not expose channels (stub
|
|
accessors), so callers can fall back to the base ThreadState set.
|
|
"""
|
|
from langgraph.channels import BinaryOperatorAggregate, DeltaChannel
|
|
|
|
channels = getattr(graph, "channels", None)
|
|
if channels is None:
|
|
return None
|
|
return frozenset(name for name, channel in channels.items() if isinstance(channel, (BinaryOperatorAggregate, DeltaChannel)))
|
|
|
|
|
|
@dataclass
|
|
class CheckpointStateAccessor:
|
|
graph: Any
|
|
checkpointer: Any
|
|
mode: CheckpointChannelMode
|
|
direct_namespace: bool = False
|
|
|
|
@classmethod
|
|
def bind(
|
|
cls,
|
|
graph: Any,
|
|
checkpointer: Any,
|
|
*,
|
|
store: Any | None = None,
|
|
mode: CheckpointChannelMode = "full",
|
|
direct_namespace: bool = False,
|
|
) -> CheckpointStateAccessor:
|
|
graph.checkpointer = checkpointer
|
|
if store is not None:
|
|
graph.store = store
|
|
return cls(graph=graph, checkpointer=checkpointer, mode=mode, direct_namespace=direct_namespace)
|
|
|
|
def _prepare_config(self, config: dict[str, Any]) -> dict[str, Any]:
|
|
prepared = {
|
|
**config,
|
|
"configurable": dict(config.get("configurable", {})),
|
|
"metadata": dict(config.get("metadata", {})),
|
|
}
|
|
if self.direct_namespace and prepared["configurable"].get("checkpoint_ns"):
|
|
# A state-only mutation graph has no subgraphs to delegate to. Bind
|
|
# the saver explicitly so LangGraph reads/writes this namespace on
|
|
# the graph itself, including when reading back an updated config.
|
|
# This private key is verified against LangGraph 1.2.9; recheck it
|
|
# when upgrading LangGraph because its internal location may move.
|
|
from langgraph._internal._constants import CONFIG_KEY_CHECKPOINTER
|
|
|
|
prepared["configurable"][CONFIG_KEY_CHECKPOINTER] = self.checkpointer
|
|
inject_checkpoint_mode(prepared, self.mode)
|
|
return prepared
|
|
|
|
def get(self, config: dict[str, Any]) -> Any:
|
|
prepared = self._prepare_config(config)
|
|
snapshot = self.graph.get_state(prepared)
|
|
raise_if_snapshot_incompatible(snapshot, self.mode)
|
|
return snapshot
|
|
|
|
async def aget(self, config: dict[str, Any]) -> Any:
|
|
prepared = self._prepare_config(config)
|
|
snapshot = await self.graph.aget_state(prepared)
|
|
raise_if_snapshot_incompatible(snapshot, self.mode)
|
|
# Delta materialization may perform a second saver read after LangGraph
|
|
# has resolved the latest checkpoint. Retention can remove a trailing
|
|
# metadata-only leaf in that interval. CachedHistorySaver then cannot
|
|
# walk the vanished target's parent chain and the first materialization
|
|
# can contain an empty messages channel. For an unpinned latest-state
|
|
# read, verify that the resolved target still exists and retry once from
|
|
# the new head when it does not. Explicit historical selections remain
|
|
# fail-closed instead of silently moving to another checkpoint.
|
|
if self.mode == "delta" and not prepared["configurable"].get("checkpoint_id"):
|
|
snapshot_config = getattr(snapshot, "config", None)
|
|
checkpoint_id = (snapshot_config or {}).get("configurable", {}).get("checkpoint_id")
|
|
if checkpoint_id and await self.checkpointer.aget_tuple(snapshot_config) is None:
|
|
snapshot = await self.graph.aget_state(prepared)
|
|
raise_if_snapshot_incompatible(snapshot, self.mode)
|
|
return snapshot
|
|
|
|
def get_tuple(self, config: dict[str, Any]) -> Any | None:
|
|
"""Raw checkpoint tuple for a config, without materializing state."""
|
|
|
|
return self.checkpointer.get_tuple(self._prepare_config(config))
|
|
|
|
async def aget_tuple(self, config: dict[str, Any]) -> Any | None:
|
|
"""Raw checkpoint tuple for a config, without materializing state."""
|
|
|
|
return await self.checkpointer.aget_tuple(self._prepare_config(config))
|
|
|
|
def get_metadata(self, config: dict[str, Any]) -> dict[str, Any]:
|
|
"""Read checkpoint metadata without materializing channel state."""
|
|
checkpoint_tuple = self.checkpointer.get_tuple(self._prepare_config(config))
|
|
raise_if_checkpoint_tuple_incompatible(checkpoint_tuple, self.mode)
|
|
return dict(getattr(checkpoint_tuple, "metadata", {}) or {})
|
|
|
|
async def aget_metadata(self, config: dict[str, Any]) -> dict[str, Any]:
|
|
"""Read checkpoint metadata without materializing channel state."""
|
|
checkpoint_tuple = await self.checkpointer.aget_tuple(self._prepare_config(config))
|
|
raise_if_checkpoint_tuple_incompatible(checkpoint_tuple, self.mode)
|
|
return dict(getattr(checkpoint_tuple, "metadata", {}) or {})
|
|
|
|
def history(self, config: dict[str, Any], *, limit: int | None = None) -> list[Any]:
|
|
prepared = self._prepare_config(config)
|
|
if limit is not None and limit <= 0:
|
|
return []
|
|
result = []
|
|
for snapshot in self.graph.get_state_history(prepared, limit=limit):
|
|
raise_if_snapshot_incompatible(snapshot, self.mode)
|
|
result.append(snapshot)
|
|
if limit is not None and len(result) >= limit:
|
|
break
|
|
return result
|
|
|
|
async def ahistory(self, config: dict[str, Any], *, limit: int | None = None) -> list[Any]:
|
|
prepared = self._prepare_config(config)
|
|
if limit is not None and limit <= 0:
|
|
return []
|
|
result = []
|
|
async for snapshot in self.graph.aget_state_history(prepared, limit=limit):
|
|
raise_if_snapshot_incompatible(snapshot, self.mode)
|
|
result.append(snapshot)
|
|
if limit is not None and len(result) >= limit:
|
|
break
|
|
return result
|
|
|
|
def update(
|
|
self,
|
|
config: dict[str, Any],
|
|
values: dict[str, Any],
|
|
*,
|
|
as_node: str | None = None,
|
|
) -> dict[str, Any]:
|
|
prepared = self._prepare_config(config)
|
|
ensure_checkpoint_mode_compatible(self.checkpointer, prepared, self.mode)
|
|
return self.graph.update_state(prepared, values, as_node=as_node)
|
|
|
|
async def aupdate(
|
|
self,
|
|
config: dict[str, Any],
|
|
values: dict[str, Any],
|
|
*,
|
|
as_node: str | None = None,
|
|
) -> dict[str, Any]:
|
|
prepared = self._prepare_config(config)
|
|
await aensure_checkpoint_mode_compatible(self.checkpointer, prepared, self.mode)
|
|
return await self.graph.aupdate_state(prepared, values, as_node=as_node)
|