mirror of
https://github.com/langchain-ai/langgraph.git
synced 2026-11-19 12:21:01 +01:00
Compare commits
8
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
1ae9718c8d | ||
|
|
97c4e4cf53 | ||
|
|
2322a66895 | ||
|
|
29a6dbc0a7 | ||
|
|
6480735aa3 | ||
|
|
cd32489e8e | ||
|
|
6cf7a4f00b | ||
|
|
97bf96f04d |
No files matched your search
@@ -76,6 +76,7 @@ The suite tests **base** capabilities (required) and **extended** capabilities (
|
||||
| `copy_thread` | no | `acopy_thread` |
|
||||
| `prune` | no | `aprune` |
|
||||
| `delta_channel_history` | no | `aget_delta_channel_history` |
|
||||
| `transcript` | no | `aget_transcript` |
|
||||
|
||||
Extended capabilities are detected by checking whether the method is overridden from `BaseCheckpointSaver`. If not overridden, those tests are skipped.
|
||||
|
||||
|
||||
@@ -24,6 +24,7 @@ class Capability(str, Enum):
|
||||
COPY_THREAD = "copy_thread"
|
||||
PRUNE = "prune"
|
||||
DELTA_CHANNEL_HISTORY = "delta_channel_history"
|
||||
TRANSCRIPT = "transcript"
|
||||
|
||||
|
||||
# Capabilities that every checkpointer must support.
|
||||
@@ -44,6 +45,7 @@ EXTENDED_CAPABILITIES = frozenset(
|
||||
Capability.COPY_THREAD,
|
||||
Capability.PRUNE,
|
||||
Capability.DELTA_CHANNEL_HISTORY,
|
||||
Capability.TRANSCRIPT,
|
||||
}
|
||||
)
|
||||
|
||||
@@ -60,6 +62,7 @@ _CAPABILITY_METHOD_MAP: dict[Capability, str] = {
|
||||
Capability.COPY_THREAD: "acopy_thread",
|
||||
Capability.PRUNE: "aprune",
|
||||
Capability.DELTA_CHANNEL_HISTORY: "aget_delta_channel_history",
|
||||
Capability.TRANSCRIPT: "aget_transcript",
|
||||
}
|
||||
|
||||
|
||||
|
||||
@@ -17,6 +17,7 @@ from langgraph.checkpoint.conformance.spec.test_list import run_list_tests
|
||||
from langgraph.checkpoint.conformance.spec.test_prune import run_prune_tests
|
||||
from langgraph.checkpoint.conformance.spec.test_put import run_put_tests
|
||||
from langgraph.checkpoint.conformance.spec.test_put_writes import run_put_writes_tests
|
||||
from langgraph.checkpoint.conformance.spec.test_transcript import run_transcript_tests
|
||||
|
||||
__all__ = [
|
||||
"run_put_tests",
|
||||
@@ -28,4 +29,5 @@ __all__ = [
|
||||
"run_copy_thread_tests",
|
||||
"run_prune_tests",
|
||||
"run_delta_channel_history_tests",
|
||||
"run_transcript_tests",
|
||||
]
|
||||
@@ -0,0 +1,175 @@
|
||||
"""TRANSCRIPT capability tests: entries stored by `aput`, read by `aget_transcript`.
|
||||
|
||||
The cases live in `transcript_cases.json` so that stores written in other
|
||||
languages can run the same ones. Each case runs against fresh ids. A `put` step
|
||||
stores one checkpoint whose channels hold one `_TranscriptWrite` each, as a
|
||||
child of checkpoint `from` when given; `expect` is `"conflict"`
|
||||
(`TranscriptConflictError`) or `"invalid"` (`ValueError`). A `read` step
|
||||
compares values, or expects `"invalid"`, and `expect_later` compares
|
||||
`has_later_entries`. `ns` is the checkpoint namespace, default `""`. An entry
|
||||
`{"seq": n, "text": s}` has `value = s`.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import traceback
|
||||
from collections.abc import Callable
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
from uuid import uuid4
|
||||
|
||||
from langchain_core.runnables import RunnableConfig
|
||||
from langgraph.checkpoint.base import BaseCheckpointSaver, TranscriptConflictError
|
||||
from langgraph.checkpoint.base.id import uuid6
|
||||
from langgraph.checkpoint.serde.types import (
|
||||
_TranscriptEntry,
|
||||
_TranscriptRef,
|
||||
_TranscriptWrite,
|
||||
)
|
||||
|
||||
from langgraph.checkpoint.conformance.test_utils import (
|
||||
generate_checkpoint,
|
||||
generate_metadata,
|
||||
)
|
||||
|
||||
CASES: list[dict[str, Any]] = json.loads(
|
||||
(Path(__file__).parent / "transcript_cases.json").read_text()
|
||||
)
|
||||
|
||||
|
||||
async def _run_case(saver: BaseCheckpointSaver, case: dict[str, Any]) -> None:
|
||||
names: dict[tuple[str, str], str] = {}
|
||||
|
||||
def ident(kind: str, name: str) -> str:
|
||||
if (kind, name) not in names:
|
||||
names[kind, name] = (
|
||||
str(uuid6(clock_seq=-1)) if kind == "checkpoint" else str(uuid4())
|
||||
)
|
||||
return names[kind, name]
|
||||
|
||||
def config(thread: str, ns: str = "", parent: str | None = None) -> RunnableConfig:
|
||||
cfg: RunnableConfig = {
|
||||
"configurable": {"thread_id": ident("thread", thread), "checkpoint_ns": ns}
|
||||
}
|
||||
if parent is not None:
|
||||
cfg["configurable"]["checkpoint_id"] = ident("checkpoint", parent)
|
||||
return cfg
|
||||
|
||||
for i, step in enumerate(case["steps"]):
|
||||
if "put" in step:
|
||||
put = step["put"]
|
||||
writes = [
|
||||
_TranscriptWrite(
|
||||
transcript_id=ident("transcript", w["transcript"]),
|
||||
head=w["head"],
|
||||
entries=[
|
||||
_TranscriptEntry(e["seq"], e["text"]) for e in w["entries"]
|
||||
],
|
||||
parent_transcript_id=ident("transcript", w["parent"])
|
||||
if "parent" in w
|
||||
else None,
|
||||
fork_seq=w.get("fork_seq"),
|
||||
)
|
||||
for w in put["writes"]
|
||||
]
|
||||
values = {f"messages{n or ''}": w for n, w in enumerate(writes)}
|
||||
checkpoint = generate_checkpoint(
|
||||
checkpoint_id=ident("checkpoint", put["checkpoint"]),
|
||||
channel_values=values,
|
||||
channel_versions={k: i + 1 for k in values},
|
||||
)
|
||||
outcome = None
|
||||
try:
|
||||
await saver.aput(
|
||||
config(put["thread"], put.get("ns", ""), put.get("from")),
|
||||
checkpoint,
|
||||
generate_metadata(step=i),
|
||||
{k: i + 1 for k in values},
|
||||
)
|
||||
except TranscriptConflictError:
|
||||
outcome = "conflict"
|
||||
except ValueError:
|
||||
outcome = "invalid"
|
||||
assert outcome == step.get("expect"), (
|
||||
f"step {i}: expected {step.get('expect')}, got {outcome}"
|
||||
)
|
||||
else:
|
||||
read = step["read"]
|
||||
try:
|
||||
result = await saver.aget_transcript(
|
||||
config=config(read["thread"], read.get("ns", "")),
|
||||
ref=_TranscriptRef(
|
||||
ident("transcript", read["transcript"]), read["head"]
|
||||
),
|
||||
)
|
||||
except ValueError:
|
||||
assert step["expect"] == "invalid", f"step {i}: unexpected ValueError"
|
||||
continue
|
||||
assert step["expect"] != "invalid", f"step {i}: expected ValueError"
|
||||
got = [e.value for e in result.entries]
|
||||
assert got == step["expect"], (
|
||||
f"step {i}: expected {step['expect']}, got {got}"
|
||||
)
|
||||
seqs = [e.seq for e in result.entries]
|
||||
assert seqs == list(range(1, len(seqs) + 1)), f"step {i}: seqs {seqs}"
|
||||
if "expect_later" in step:
|
||||
assert result.has_later_entries == step["expect_later"], (
|
||||
f"step {i}: has_later_entries is {result.has_later_entries}"
|
||||
)
|
||||
|
||||
|
||||
async def test_pointer_is_stored_in_place_of_the_write(
|
||||
saver: BaseCheckpointSaver,
|
||||
) -> None:
|
||||
"""The checkpoint read back holds a `_TranscriptRef`, not the entries."""
|
||||
cfg: RunnableConfig = {
|
||||
"configurable": {"thread_id": str(uuid4()), "checkpoint_ns": ""}
|
||||
}
|
||||
write = _TranscriptWrite("t", 1, [_TranscriptEntry(1, "a")])
|
||||
checkpoint = generate_checkpoint(
|
||||
channel_values={"messages": write}, channel_versions={"messages": 1}
|
||||
)
|
||||
stored = await saver.aput(cfg, checkpoint, generate_metadata(), {"messages": 1})
|
||||
tup = await saver.aget_tuple(stored)
|
||||
assert tup is not None
|
||||
ref = tup.checkpoint["channel_values"]["messages"]
|
||||
assert ref == _TranscriptRef("t", 1), f"expected a pointer to (t, 1), got {ref!r}"
|
||||
|
||||
|
||||
def _case_test(case: dict[str, Any]) -> Callable[[BaseCheckpointSaver], Any]:
|
||||
async def test(saver: BaseCheckpointSaver) -> None:
|
||||
await _run_case(saver, case)
|
||||
|
||||
test.__name__ = f"test_{case['name']}"
|
||||
return test
|
||||
|
||||
|
||||
ALL_TRANSCRIPT_TESTS = [
|
||||
*(_case_test(case) for case in CASES),
|
||||
test_pointer_is_stored_in_place_of_the_write,
|
||||
]
|
||||
|
||||
|
||||
async def run_transcript_tests(
|
||||
saver: BaseCheckpointSaver,
|
||||
on_test_result: Callable[[str, str, bool, str | None], None] | None = None,
|
||||
) -> tuple[int, int, list[str]]:
|
||||
"""Run all transcript tests. Returns (passed, failed, failure_names)."""
|
||||
passed = 0
|
||||
failed = 0
|
||||
failures: list[str] = []
|
||||
for test_fn in ALL_TRANSCRIPT_TESTS:
|
||||
try:
|
||||
await test_fn(saver)
|
||||
passed += 1
|
||||
if on_test_result:
|
||||
on_test_result("transcript", test_fn.__name__, True, None)
|
||||
except Exception:
|
||||
failed += 1
|
||||
failures.append(f"{test_fn.__name__}: {traceback.format_exc()}")
|
||||
if on_test_result:
|
||||
on_test_result(
|
||||
"transcript", test_fn.__name__, False, traceback.format_exc()
|
||||
)
|
||||
return passed, failed, failures
|
||||
+305
@@ -0,0 +1,305 @@
|
||||
[
|
||||
{
|
||||
"name": "append_then_read",
|
||||
"steps": [
|
||||
{"put": {"thread": "t", "checkpoint": "c1", "writes": [{"transcript": "T", "entries": [{"seq": 1, "text": "a"}, {"seq": 2, "text": "b"}], "head": 2}]}},
|
||||
{"put": {"thread": "t", "checkpoint": "c2", "writes": [{"transcript": "T", "entries": [{"seq": 3, "text": "c"}], "head": 3}], "from": "c1"}},
|
||||
{"read": {"thread": "t", "transcript": "T", "head": 3}, "expect": ["a", "b", "c"]}
|
||||
]
|
||||
},
|
||||
{
|
||||
"name": "older_head_reads_prefix",
|
||||
"steps": [
|
||||
{"put": {"thread": "t", "checkpoint": "c1", "writes": [{"transcript": "T", "entries": [{"seq": 1, "text": "a"}, {"seq": 2, "text": "b"}, {"seq": 3, "text": "c"}], "head": 3}]}},
|
||||
{"read": {"thread": "t", "transcript": "T", "head": 2}, "expect": ["a", "b"], "expect_later": true}
|
||||
]
|
||||
},
|
||||
{
|
||||
"name": "read_reports_later_entries",
|
||||
"steps": [
|
||||
{"put": {"thread": "t", "checkpoint": "c1", "writes": [{"transcript": "T", "entries": [{"seq": 1, "text": "a"}, {"seq": 2, "text": "b"}], "head": 2}]}},
|
||||
{"put": {"thread": "t", "checkpoint": "c2", "writes": [{"transcript": "T", "entries": [{"seq": 3, "text": "c"}], "head": 3}], "from": "c1"}},
|
||||
{"read": {"thread": "t", "transcript": "T", "head": 2}, "expect": ["a", "b"], "expect_later": true},
|
||||
{"read": {"thread": "t", "transcript": "T", "head": 3}, "expect": ["a", "b", "c"], "expect_later": false}
|
||||
]
|
||||
},
|
||||
{
|
||||
"name": "put_without_writes_changes_nothing",
|
||||
"steps": [
|
||||
{"put": {"thread": "t", "checkpoint": "c1", "writes": [{"transcript": "T", "entries": [{"seq": 1, "text": "a"}], "head": 1}]}},
|
||||
{"put": {"thread": "t", "checkpoint": "c2", "writes": [], "from": "c1"}},
|
||||
{"read": {"thread": "t", "transcript": "T", "head": 1}, "expect": ["a"], "expect_later": false}
|
||||
]
|
||||
},
|
||||
{
|
||||
"name": "pointer_without_entries_is_accepted",
|
||||
"steps": [
|
||||
{"put": {"thread": "t", "checkpoint": "c1", "writes": [{"transcript": "T", "entries": [{"seq": 1, "text": "a"}, {"seq": 2, "text": "b"}], "head": 2}]}},
|
||||
{"put": {"thread": "t", "checkpoint": "c2", "writes": [{"transcript": "T", "entries": [], "head": 2}], "from": "c1"}},
|
||||
{"read": {"thread": "t", "transcript": "T", "head": 2}, "expect": ["a", "b"], "expect_later": false}
|
||||
]
|
||||
},
|
||||
{
|
||||
"name": "replayed_put_is_accepted",
|
||||
"steps": [
|
||||
{"put": {"thread": "t", "checkpoint": "c1", "writes": [{"transcript": "T", "entries": [{"seq": 1, "text": "a"}], "head": 1}]}},
|
||||
{"put": {"thread": "t", "checkpoint": "c1", "writes": [{"transcript": "T", "entries": [{"seq": 1, "text": "a"}], "head": 1}]}},
|
||||
{"read": {"thread": "t", "transcript": "T", "head": 1}, "expect": ["a"], "expect_later": false}
|
||||
]
|
||||
},
|
||||
{
|
||||
"name": "append_after_rollback_without_fork_is_conflict",
|
||||
"steps": [
|
||||
{"put": {"thread": "t", "checkpoint": "c1", "writes": [{"transcript": "T", "entries": [{"seq": 1, "text": "a"}], "head": 1}]}},
|
||||
{"put": {"thread": "t", "checkpoint": "rolled_back", "writes": [{"transcript": "T", "entries": [{"seq": 2, "text": "lost"}], "head": 2}], "from": "c1"}},
|
||||
{"put": {"thread": "t", "checkpoint": "c2", "writes": [{"transcript": "T", "entries": [{"seq": 2, "text": "b"}], "head": 2}], "from": "c1"}, "expect": "conflict"},
|
||||
{"read": {"thread": "t", "transcript": "T", "head": 2}, "expect": ["a", "lost"], "expect_later": false}
|
||||
]
|
||||
},
|
||||
{
|
||||
"name": "existing_seq_with_same_content_is_conflict",
|
||||
"steps": [
|
||||
{"put": {"thread": "t", "checkpoint": "c1", "writes": [{"transcript": "T", "entries": [{"seq": 1, "text": "a"}], "head": 1}]}},
|
||||
{"put": {"thread": "t", "checkpoint": "rolled_back", "writes": [{"transcript": "T", "entries": [{"seq": 2, "text": "b"}], "head": 2}], "from": "c1"}},
|
||||
{"put": {"thread": "t", "checkpoint": "c2", "writes": [{"transcript": "T", "entries": [{"seq": 2, "text": "b"}], "head": 2}], "from": "c1"}, "expect": "conflict"}
|
||||
]
|
||||
},
|
||||
{
|
||||
"name": "conflict_stores_none_of_the_put",
|
||||
"steps": [
|
||||
{"put": {"thread": "t", "checkpoint": "c1", "writes": [{"transcript": "T", "entries": [{"seq": 1, "text": "a"}], "head": 1}]}},
|
||||
{"put": {"thread": "t", "checkpoint": "rolled_back", "writes": [{"transcript": "T", "entries": [{"seq": 2, "text": "lost"}], "head": 2}], "from": "c1"}},
|
||||
{"put": {"thread": "t", "checkpoint": "c2", "writes": [{"transcript": "U", "entries": [{"seq": 1, "text": "u"}], "head": 1}, {"transcript": "T", "entries": [{"seq": 2, "text": "b"}], "head": 2}], "from": "c1"}, "expect": "conflict"},
|
||||
{"read": {"thread": "t", "transcript": "U", "head": 0}, "expect": [], "expect_later": false}
|
||||
]
|
||||
},
|
||||
{
|
||||
"name": "run_after_rollback_forks",
|
||||
"steps": [
|
||||
{"put": {"thread": "t", "checkpoint": "c1", "writes": [{"transcript": "T", "entries": [{"seq": 1, "text": "a"}], "head": 1}]}},
|
||||
{"put": {"thread": "t", "checkpoint": "rolled_back", "writes": [{"transcript": "T", "entries": [{"seq": 2, "text": "lost"}], "head": 2}], "from": "c1"}},
|
||||
{"read": {"thread": "t", "transcript": "T", "head": 1}, "expect": ["a"], "expect_later": true},
|
||||
{"put": {"thread": "t", "checkpoint": "c2", "writes": [{"transcript": "T2", "parent": "T", "fork_seq": 1, "entries": [{"seq": 2, "text": "b"}], "head": 2}], "from": "c1"}},
|
||||
{"read": {"thread": "t", "transcript": "T2", "head": 2}, "expect": ["a", "b"], "expect_later": false},
|
||||
{"put": {"thread": "t", "checkpoint": "c3", "writes": [{"transcript": "T2", "entries": [{"seq": 3, "text": "c"}], "head": 3}], "from": "c2"}},
|
||||
{"read": {"thread": "t", "transcript": "T2", "head": 3}, "expect": ["a", "b", "c"], "expect_later": false}
|
||||
]
|
||||
},
|
||||
{
|
||||
"name": "fork_shares_parent_prefix",
|
||||
"steps": [
|
||||
{"put": {"thread": "t", "checkpoint": "c1", "writes": [{"transcript": "T", "entries": [{"seq": 1, "text": "a"}, {"seq": 2, "text": "b"}, {"seq": 3, "text": "c"}], "head": 3}]}},
|
||||
{"put": {"thread": "t", "checkpoint": "c2", "writes": [{"transcript": "T2", "parent": "T", "fork_seq": 2, "entries": [{"seq": 3, "text": "z"}], "head": 3}], "from": "c1"}},
|
||||
{"read": {"thread": "t", "transcript": "T2", "head": 3}, "expect": ["a", "b", "z"], "expect_later": false},
|
||||
{"read": {"thread": "t", "transcript": "T", "head": 3}, "expect": ["a", "b", "c"], "expect_later": false}
|
||||
]
|
||||
},
|
||||
{
|
||||
"name": "fork_of_fork",
|
||||
"steps": [
|
||||
{"put": {"thread": "t", "checkpoint": "c1", "writes": [{"transcript": "T", "entries": [{"seq": 1, "text": "a"}, {"seq": 2, "text": "b"}], "head": 2}]}},
|
||||
{"put": {"thread": "t", "checkpoint": "c2", "writes": [{"transcript": "T2", "parent": "T", "fork_seq": 1, "entries": [{"seq": 2, "text": "y"}, {"seq": 3, "text": "z"}], "head": 3}], "from": "c1"}},
|
||||
{"put": {"thread": "t", "checkpoint": "c3", "writes": [{"transcript": "T3", "parent": "T2", "fork_seq": 2, "entries": [{"seq": 3, "text": "q"}], "head": 3}], "from": "c2"}},
|
||||
{"read": {"thread": "t", "transcript": "T3", "head": 3}, "expect": ["a", "y", "q"]}
|
||||
]
|
||||
},
|
||||
{
|
||||
"name": "write_to_fork_may_omit_or_repeat_fork_point",
|
||||
"steps": [
|
||||
{"put": {"thread": "t", "checkpoint": "c1", "writes": [{"transcript": "T", "entries": [{"seq": 1, "text": "a"}, {"seq": 2, "text": "b"}], "head": 2}]}},
|
||||
{"put": {"thread": "t", "checkpoint": "c2", "writes": [{"transcript": "T2", "parent": "T", "fork_seq": 1, "entries": [{"seq": 2, "text": "y"}], "head": 2}], "from": "c1"}},
|
||||
{"put": {"thread": "t", "checkpoint": "c3", "writes": [{"transcript": "T2", "entries": [{"seq": 3, "text": "z"}], "head": 3}], "from": "c2"}},
|
||||
{"put": {"thread": "t", "checkpoint": "c4", "writes": [{"transcript": "T2", "parent": "T", "fork_seq": 1, "entries": [{"seq": 4, "text": "w"}], "head": 4}], "from": "c3"}},
|
||||
{"read": {"thread": "t", "transcript": "T2", "head": 4}, "expect": ["a", "y", "z", "w"]}
|
||||
]
|
||||
},
|
||||
{
|
||||
"name": "history_rewrite_copies_later_entries",
|
||||
"steps": [
|
||||
{"put": {"thread": "t", "checkpoint": "c1", "writes": [{"transcript": "T1", "entries": [{"seq": 1, "text": "m1"}, {"seq": 2, "text": "m2"}, {"seq": 3, "text": "m3"}, {"seq": 4, "text": "m4"}, {"seq": 5, "text": "m5"}], "head": 5}]}},
|
||||
{"put": {"thread": "t", "checkpoint": "c2", "writes": [{"transcript": "T2", "parent": "T1", "fork_seq": 2, "entries": [{"seq": 3, "text": "m3 edited"}, {"seq": 4, "text": "m4"}, {"seq": 5, "text": "m5"}], "head": 5}], "from": "c1"}},
|
||||
{"read": {"thread": "t", "transcript": "T2", "head": 5}, "expect": ["m1", "m2", "m3 edited", "m4", "m5"]},
|
||||
{"read": {"thread": "t", "transcript": "T1", "head": 5}, "expect": ["m1", "m2", "m3", "m4", "m5"]}
|
||||
]
|
||||
},
|
||||
{
|
||||
"name": "fork_at_seq_zero_shares_nothing",
|
||||
"steps": [
|
||||
{"put": {"thread": "t", "checkpoint": "c1", "writes": [{"transcript": "T", "entries": [{"seq": 1, "text": "a"}, {"seq": 2, "text": "b"}], "head": 2}]}},
|
||||
{"put": {"thread": "t", "checkpoint": "c2", "writes": [{"transcript": "T2", "parent": "T", "fork_seq": 0, "entries": [{"seq": 1, "text": "x"}], "head": 1}], "from": "c1"}},
|
||||
{"read": {"thread": "t", "transcript": "T2", "head": 1}, "expect": ["x"]}
|
||||
]
|
||||
},
|
||||
{
|
||||
"name": "fork_without_own_entries_reads_parent_prefix",
|
||||
"steps": [
|
||||
{"put": {"thread": "t", "checkpoint": "c1", "writes": [{"transcript": "T", "entries": [{"seq": 1, "text": "a"}, {"seq": 2, "text": "b"}], "head": 2}]}},
|
||||
{"put": {"thread": "t", "checkpoint": "c2", "writes": [{"transcript": "T2", "parent": "T", "fork_seq": 1, "entries": [], "head": 1}], "from": "c1"}},
|
||||
{"read": {"thread": "t", "transcript": "T2", "head": 1}, "expect": ["a"], "expect_later": false}
|
||||
]
|
||||
},
|
||||
{
|
||||
"name": "resend_of_committed_entries_is_invalid",
|
||||
"steps": [
|
||||
{"put": {"thread": "t", "checkpoint": "c1", "writes": [{"transcript": "T", "entries": [{"seq": 1, "text": "a"}, {"seq": 2, "text": "b"}], "head": 2}]}},
|
||||
{"put": {"thread": "t", "checkpoint": "c2", "writes": [{"transcript": "T", "entries": [{"seq": 1, "text": "a"}, {"seq": 2, "text": "b"}, {"seq": 3, "text": "c"}], "head": 3}], "from": "c1"}, "expect": "invalid"},
|
||||
{"read": {"thread": "t", "transcript": "T", "head": 2}, "expect": ["a", "b"], "expect_later": false}
|
||||
]
|
||||
},
|
||||
{
|
||||
"name": "seq_gap_is_invalid",
|
||||
"steps": [
|
||||
{"put": {"thread": "t", "checkpoint": "c1", "writes": [{"transcript": "T", "entries": [{"seq": 1, "text": "a"}], "head": 1}]}},
|
||||
{"put": {"thread": "t", "checkpoint": "c2", "writes": [{"transcript": "T", "entries": [{"seq": 3, "text": "c"}], "head": 3}], "from": "c1"}, "expect": "invalid"},
|
||||
{"read": {"thread": "t", "transcript": "T", "head": 1}, "expect": ["a"], "expect_later": false}
|
||||
]
|
||||
},
|
||||
{
|
||||
"name": "unsorted_entries_are_invalid",
|
||||
"steps": [
|
||||
{"put": {"thread": "t", "checkpoint": "c1", "writes": [{"transcript": "T", "entries": [{"seq": 2, "text": "b"}, {"seq": 1, "text": "a"}], "head": 2}]}, "expect": "invalid"},
|
||||
{"read": {"thread": "t", "transcript": "T", "head": 0}, "expect": [], "expect_later": false}
|
||||
]
|
||||
},
|
||||
{
|
||||
"name": "repeated_seq_is_invalid",
|
||||
"steps": [
|
||||
{"put": {"thread": "t", "checkpoint": "c1", "writes": [{"transcript": "T", "entries": [{"seq": 1, "text": "a"}, {"seq": 1, "text": "a"}], "head": 1}]}, "expect": "invalid"},
|
||||
{"read": {"thread": "t", "transcript": "T", "head": 0}, "expect": [], "expect_later": false}
|
||||
]
|
||||
},
|
||||
{
|
||||
"name": "entry_above_head_is_invalid",
|
||||
"steps": [
|
||||
{"put": {"thread": "t", "checkpoint": "c1", "writes": [{"transcript": "T", "entries": [{"seq": 1, "text": "a"}, {"seq": 2, "text": "b"}], "head": 1}]}, "expect": "invalid"},
|
||||
{"read": {"thread": "t", "transcript": "T", "head": 0}, "expect": [], "expect_later": false}
|
||||
]
|
||||
},
|
||||
{
|
||||
"name": "head_past_last_entry_is_invalid",
|
||||
"steps": [
|
||||
{"put": {"thread": "t", "checkpoint": "c1", "writes": [{"transcript": "T", "entries": [{"seq": 1, "text": "a"}], "head": 2}]}, "expect": "invalid"},
|
||||
{"read": {"thread": "t", "transcript": "T", "head": 0}, "expect": [], "expect_later": false}
|
||||
]
|
||||
},
|
||||
{
|
||||
"name": "head_below_parent_head_is_invalid",
|
||||
"steps": [
|
||||
{"put": {"thread": "t", "checkpoint": "c1", "writes": [{"transcript": "T", "entries": [{"seq": 1, "text": "a"}, {"seq": 2, "text": "b"}], "head": 2}]}},
|
||||
{"put": {"thread": "t", "checkpoint": "c2", "writes": [{"transcript": "T", "entries": [], "head": 1}], "from": "c1"}, "expect": "invalid"}
|
||||
]
|
||||
},
|
||||
{
|
||||
"name": "write_to_transcript_parent_checkpoint_lacks_is_invalid",
|
||||
"steps": [
|
||||
{"put": {"thread": "t", "checkpoint": "c1", "writes": [{"transcript": "T", "entries": [{"seq": 1, "text": "a"}], "head": 1}]}},
|
||||
{"put": {"thread": "t", "checkpoint": "c2", "writes": [{"transcript": "T", "entries": [{"seq": 2, "text": "b"}], "head": 2}]}, "expect": "invalid"},
|
||||
{"read": {"thread": "t", "transcript": "T", "head": 1}, "expect": ["a"], "expect_later": false}
|
||||
]
|
||||
},
|
||||
{
|
||||
"name": "two_writes_to_one_transcript_in_one_put_are_invalid",
|
||||
"steps": [
|
||||
{"put": {"thread": "t", "checkpoint": "c1", "writes": [{"transcript": "T", "entries": [{"seq": 1, "text": "a"}], "head": 1}, {"transcript": "T", "entries": [{"seq": 1, "text": "a"}], "head": 1}]}, "expect": "invalid"},
|
||||
{"read": {"thread": "t", "transcript": "T", "head": 0}, "expect": [], "expect_later": false}
|
||||
]
|
||||
},
|
||||
{
|
||||
"name": "fork_entry_at_or_below_fork_seq_is_invalid",
|
||||
"steps": [
|
||||
{"put": {"thread": "t", "checkpoint": "c1", "writes": [{"transcript": "T", "entries": [{"seq": 1, "text": "a"}, {"seq": 2, "text": "b"}], "head": 2}]}},
|
||||
{"put": {"thread": "t", "checkpoint": "c2", "writes": [{"transcript": "T2", "parent": "T", "fork_seq": 1, "entries": [{"seq": 1, "text": "x"}, {"seq": 2, "text": "y"}], "head": 2}], "from": "c1"}, "expect": "invalid"},
|
||||
{"read": {"thread": "t", "transcript": "T2", "head": 0}, "expect": [], "expect_later": false}
|
||||
]
|
||||
},
|
||||
{
|
||||
"name": "fork_of_unknown_parent_is_invalid",
|
||||
"steps": [
|
||||
{"put": {"thread": "t", "checkpoint": "c1", "writes": [{"transcript": "T2", "parent": "missing", "fork_seq": 1, "entries": [{"seq": 2, "text": "y"}], "head": 2}]}, "expect": "invalid"},
|
||||
{"read": {"thread": "t", "transcript": "T2", "head": 0}, "expect": [], "expect_later": false}
|
||||
]
|
||||
},
|
||||
{
|
||||
"name": "fork_seq_past_parent_is_invalid",
|
||||
"steps": [
|
||||
{"put": {"thread": "t", "checkpoint": "c1", "writes": [{"transcript": "T", "entries": [{"seq": 1, "text": "a"}, {"seq": 2, "text": "b"}], "head": 2}]}},
|
||||
{"put": {"thread": "t", "checkpoint": "c2", "writes": [{"transcript": "T2", "parent": "T", "fork_seq": 3, "entries": [{"seq": 4, "text": "y"}], "head": 4}], "from": "c1"}, "expect": "invalid"}
|
||||
]
|
||||
},
|
||||
{
|
||||
"name": "fork_seq_without_parent_is_invalid",
|
||||
"steps": [
|
||||
{"put": {"thread": "t", "checkpoint": "c1", "writes": [{"transcript": "T", "fork_seq": 0, "entries": [{"seq": 1, "text": "a"}], "head": 1}]}, "expect": "invalid"}
|
||||
]
|
||||
},
|
||||
{
|
||||
"name": "parent_without_fork_seq_is_invalid",
|
||||
"steps": [
|
||||
{"put": {"thread": "t", "checkpoint": "c1", "writes": [{"transcript": "T", "entries": [{"seq": 1, "text": "a"}, {"seq": 2, "text": "b"}], "head": 2}]}},
|
||||
{"put": {"thread": "t", "checkpoint": "c2", "writes": [{"transcript": "T2", "parent": "T", "entries": [{"seq": 2, "text": "y"}], "head": 2}], "from": "c1"}, "expect": "invalid"}
|
||||
]
|
||||
},
|
||||
{
|
||||
"name": "changed_fork_point_is_invalid",
|
||||
"steps": [
|
||||
{"put": {"thread": "t", "checkpoint": "c1", "writes": [{"transcript": "T", "entries": [{"seq": 1, "text": "a"}, {"seq": 2, "text": "b"}], "head": 2}]}},
|
||||
{"put": {"thread": "t", "checkpoint": "c2", "writes": [{"transcript": "T2", "parent": "T", "fork_seq": 1, "entries": [{"seq": 2, "text": "y"}], "head": 2}], "from": "c1"}},
|
||||
{"put": {"thread": "t", "checkpoint": "c3", "writes": [{"transcript": "T2", "parent": "T", "fork_seq": 0, "entries": [{"seq": 3, "text": "z"}], "head": 3}], "from": "c2"}, "expect": "invalid"}
|
||||
]
|
||||
},
|
||||
{
|
||||
"name": "self_parent_is_invalid",
|
||||
"steps": [
|
||||
{"put": {"thread": "t", "checkpoint": "c1", "writes": [{"transcript": "T", "parent": "T", "fork_seq": 0, "entries": [{"seq": 1, "text": "a"}], "head": 1}]}, "expect": "invalid"}
|
||||
]
|
||||
},
|
||||
{
|
||||
"name": "parent_created_in_same_put_is_invalid",
|
||||
"steps": [
|
||||
{"put": {"thread": "t", "checkpoint": "c1", "writes": [{"transcript": "T", "entries": [{"seq": 1, "text": "a"}], "head": 1}, {"transcript": "T2", "parent": "T", "fork_seq": 1, "entries": [{"seq": 2, "text": "y"}], "head": 2}]}, "expect": "invalid"},
|
||||
{"put": {"thread": "t", "checkpoint": "c2", "writes": [{"transcript": "T2", "parent": "T", "fork_seq": 1, "entries": [{"seq": 2, "text": "y"}], "head": 2}, {"transcript": "T", "entries": [{"seq": 1, "text": "a"}], "head": 1}]}, "expect": "invalid"},
|
||||
{"read": {"thread": "t", "transcript": "T", "head": 0}, "expect": [], "expect_later": false}
|
||||
]
|
||||
},
|
||||
{
|
||||
"name": "read_past_stored_entries_is_invalid",
|
||||
"steps": [
|
||||
{"put": {"thread": "t", "checkpoint": "c1", "writes": [{"transcript": "T", "entries": [{"seq": 1, "text": "a"}, {"seq": 2, "text": "b"}], "head": 2}]}},
|
||||
{"read": {"thread": "t", "transcript": "T", "head": 3}, "expect": "invalid"}
|
||||
]
|
||||
},
|
||||
{
|
||||
"name": "read_of_unknown_transcript_is_invalid",
|
||||
"steps": [
|
||||
{"read": {"thread": "t", "transcript": "T", "head": 1}, "expect": "invalid"}
|
||||
]
|
||||
},
|
||||
{
|
||||
"name": "transcripts_are_scoped_to_thread",
|
||||
"steps": [
|
||||
{"put": {"thread": "t1", "checkpoint": "c1", "writes": [{"transcript": "T", "entries": [{"seq": 1, "text": "a"}], "head": 1}]}},
|
||||
{"put": {"thread": "t2", "checkpoint": "c2", "writes": [{"transcript": "T", "entries": [{"seq": 1, "text": "x"}], "head": 1}]}},
|
||||
{"read": {"thread": "t1", "transcript": "T", "head": 1}, "expect": ["a"]},
|
||||
{"read": {"thread": "t2", "transcript": "T", "head": 1}, "expect": ["x"]},
|
||||
{"read": {"thread": "t3", "transcript": "T", "head": 1}, "expect": "invalid"}
|
||||
]
|
||||
},
|
||||
{
|
||||
"name": "transcripts_are_scoped_to_namespace",
|
||||
"steps": [
|
||||
{"put": {"thread": "t", "checkpoint": "c1", "writes": [{"transcript": "T", "entries": [{"seq": 1, "text": "a"}], "head": 1}], "ns": "a"}},
|
||||
{"put": {"thread": "t", "checkpoint": "c2", "writes": [{"transcript": "T", "entries": [{"seq": 1, "text": "x"}], "head": 1}], "ns": "b"}},
|
||||
{"read": {"thread": "t", "transcript": "T", "head": 1, "ns": "a"}, "expect": ["a"]},
|
||||
{"read": {"thread": "t", "transcript": "T", "head": 1, "ns": "b"}, "expect": ["x"]},
|
||||
{"read": {"thread": "t", "transcript": "T", "head": 1, "ns": ""}, "expect": "invalid"}
|
||||
]
|
||||
},
|
||||
{
|
||||
"name": "replay_that_changes_the_pointer_is_invalid",
|
||||
"steps": [
|
||||
{"put": {"thread": "t", "checkpoint": "c1", "writes": [{"transcript": "T", "entries": [{"seq": 1, "text": "a"}], "head": 1}]}},
|
||||
{"put": {"thread": "t", "checkpoint": "c1", "writes": [{"transcript": "T", "entries": [{"seq": 2, "text": "b"}], "head": 2}]}, "expect": "invalid"},
|
||||
{"read": {"thread": "t", "transcript": "T", "head": 1}, "expect": ["a"], "expect_later": false}
|
||||
]
|
||||
}
|
||||
]
|
||||
@@ -27,6 +27,7 @@ from langgraph.checkpoint.conformance.spec.test_list import run_list_tests
|
||||
from langgraph.checkpoint.conformance.spec.test_prune import run_prune_tests
|
||||
from langgraph.checkpoint.conformance.spec.test_put import run_put_tests
|
||||
from langgraph.checkpoint.conformance.spec.test_put_writes import run_put_writes_tests
|
||||
from langgraph.checkpoint.conformance.spec.test_transcript import run_transcript_tests
|
||||
|
||||
# Maps capability to its runner function.
|
||||
_RUNNERS = {
|
||||
@@ -39,6 +40,7 @@ _RUNNERS = {
|
||||
Capability.COPY_THREAD: run_copy_thread_tests,
|
||||
Capability.PRUNE: run_prune_tests,
|
||||
Capability.DELTA_CHANNEL_HISTORY: run_delta_channel_history_tests,
|
||||
Capability.TRANSCRIPT: run_transcript_tests,
|
||||
}
|
||||
|
||||
|
||||
|
||||
@@ -26,8 +26,15 @@ from langgraph.checkpoint.serde.types import (
|
||||
RESUME,
|
||||
SCHEDULED,
|
||||
ChannelProtocol,
|
||||
_Transcript,
|
||||
_TranscriptRef,
|
||||
)
|
||||
|
||||
|
||||
class TranscriptConflictError(Exception):
|
||||
"""A transcript entry already exists at this seq with different content."""
|
||||
|
||||
|
||||
V = TypeVar("V", int, float, str)
|
||||
PendingWrite = tuple[str, str, Any]
|
||||
|
||||
@@ -604,6 +611,24 @@ class BaseCheckpointSaver(Generic[V]):
|
||||
"""
|
||||
raise NotImplementedError
|
||||
|
||||
def get_transcript(
|
||||
self, *, config: RunnableConfig, ref: _TranscriptRef
|
||||
) -> _Transcript:
|
||||
"""Read a transcript up to `ref.head` in the thread and namespace of `config`.
|
||||
|
||||
!!! warning "Beta"
|
||||
|
||||
Part of transcript support; in beta. A saver that overrides this also
|
||||
stores each `_TranscriptWrite` in `put` by the rules on that type.
|
||||
"""
|
||||
raise NotImplementedError
|
||||
|
||||
async def aget_transcript(
|
||||
self, *, config: RunnableConfig, ref: _TranscriptRef
|
||||
) -> _Transcript:
|
||||
"""Async version of `get_transcript`."""
|
||||
raise NotImplementedError
|
||||
|
||||
def get_delta_channel_history(
|
||||
self, *, config: RunnableConfig, channels: Sequence[str]
|
||||
) -> Mapping[str, DeltaChannelHistory]:
|
||||
|
||||
@@ -6,7 +6,14 @@ import pickle
|
||||
import random
|
||||
import shutil
|
||||
from collections import defaultdict
|
||||
from collections.abc import AsyncIterator, Iterator, Mapping, Sequence
|
||||
from collections.abc import (
|
||||
AsyncIterator,
|
||||
Callable,
|
||||
Iterable,
|
||||
Iterator,
|
||||
Mapping,
|
||||
Sequence,
|
||||
)
|
||||
from contextlib import AbstractAsyncContextManager, AbstractContextManager, ExitStack
|
||||
from types import TracebackType
|
||||
from typing import Any
|
||||
@@ -23,10 +30,17 @@ from langgraph.checkpoint.base import (
|
||||
DeltaChannelHistory,
|
||||
PendingWrite,
|
||||
SerializerProtocol,
|
||||
TranscriptConflictError,
|
||||
get_checkpoint_id,
|
||||
get_checkpoint_metadata,
|
||||
writes_sort_key,
|
||||
)
|
||||
from langgraph.checkpoint.serde.types import (
|
||||
_Transcript,
|
||||
_TranscriptEntry,
|
||||
_TranscriptRef,
|
||||
_TranscriptWrite,
|
||||
)
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
@@ -82,6 +96,10 @@ class InMemorySaver(
|
||||
], # thread id, checkpoint ns, channel, version
|
||||
tuple[str, bytes],
|
||||
]
|
||||
# (thread ID, checkpoint NS, transcript ID) -> (parent transcript ID, fork seq)
|
||||
transcripts: dict[tuple[str, str, str], tuple[str, int] | None]
|
||||
# (thread ID, checkpoint NS, transcript ID) -> seq -> blob
|
||||
transcript_entries: dict[tuple[str, str, str], dict[int, tuple[str, bytes]]]
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
@@ -93,6 +111,8 @@ class InMemorySaver(
|
||||
self.storage = factory(lambda: defaultdict(dict))
|
||||
self.writes = factory(dict)
|
||||
self.blobs = factory()
|
||||
self.transcripts = {}
|
||||
self.transcript_entries = {}
|
||||
self.stack = ExitStack()
|
||||
if factory is not defaultdict:
|
||||
self.stack.enter_context(self.storage) # type: ignore[arg-type]
|
||||
@@ -149,6 +169,184 @@ class InMemorySaver(
|
||||
for k in sorted(stored, key=lambda k: writes_sort_key(stored[k][3], *k))
|
||||
]
|
||||
|
||||
def _parent_refs(
|
||||
self, config: RunnableConfig, channels: Iterable[str]
|
||||
) -> dict[str, _TranscriptRef]:
|
||||
"""The transcript pointers held by the checkpoint `config` points at."""
|
||||
return self._checkpoint_refs(
|
||||
config["configurable"]["thread_id"],
|
||||
config["configurable"]["checkpoint_ns"],
|
||||
config["configurable"].get("checkpoint_id") or "",
|
||||
channels,
|
||||
)
|
||||
|
||||
def _checkpoint_refs(
|
||||
self,
|
||||
thread_id: str,
|
||||
checkpoint_ns: str,
|
||||
checkpoint_id: str,
|
||||
channels: Iterable[str],
|
||||
) -> dict[str, _TranscriptRef]:
|
||||
"""The transcript pointers a stored checkpoint holds on `channels`."""
|
||||
saved = self.storage[thread_id][checkpoint_ns].get(checkpoint_id)
|
||||
if saved is None:
|
||||
return {}
|
||||
versions = self.serde.loads_typed(saved[0])["channel_versions"]
|
||||
refs: dict[str, _TranscriptRef] = {}
|
||||
for k in channels:
|
||||
blob = self.blobs.get((thread_id, checkpoint_ns, k, versions.get(k, "")))
|
||||
if blob is not None and blob[0] != "empty":
|
||||
value = self.serde.loads_typed(blob)
|
||||
if isinstance(value, _TranscriptRef):
|
||||
refs[k] = value
|
||||
return refs
|
||||
|
||||
def _put_transcripts(
|
||||
self,
|
||||
config: RunnableConfig,
|
||||
checkpoint_id: str,
|
||||
values: dict[str, Any],
|
||||
new_versions: ChannelVersions,
|
||||
) -> tuple[dict[str, Any], Callable[[], None]]:
|
||||
"""Check each `_TranscriptWrite` and replace it with its pointer.
|
||||
|
||||
Returns the values to store and a function that stores the entries, to call
|
||||
once the rest of the checkpoint has serialized. A bare `_TranscriptRef` is
|
||||
checked as a write with no entries.
|
||||
"""
|
||||
writes = {
|
||||
k: _TranscriptWrite(v.transcript_id, v.head)
|
||||
if isinstance(v, _TranscriptRef)
|
||||
else v
|
||||
for k, v in values.items()
|
||||
if isinstance(v, (_TranscriptWrite, _TranscriptRef))
|
||||
}
|
||||
if not writes:
|
||||
return values, lambda: None
|
||||
stored_values = {
|
||||
**values,
|
||||
**{k: _TranscriptRef(w.transcript_id, w.head) for k, w in writes.items()},
|
||||
}
|
||||
thread_id = config["configurable"]["thread_id"]
|
||||
checkpoint_ns = config["configurable"]["checkpoint_ns"]
|
||||
if checkpoint_id in self.storage[thread_id][checkpoint_ns]:
|
||||
stored_refs = self._checkpoint_refs(
|
||||
thread_id, checkpoint_ns, checkpoint_id, writes
|
||||
)
|
||||
for k, w in writes.items():
|
||||
if stored_refs.get(k) != _TranscriptRef(w.transcript_id, w.head):
|
||||
raise ValueError(
|
||||
f"replay of checkpoint {checkpoint_id} changes the pointer on {k}"
|
||||
)
|
||||
return stored_values, lambda: None
|
||||
parent_heads = {
|
||||
r.transcript_id: r.head for r in self._parent_refs(config, writes).values()
|
||||
}
|
||||
# transcript -> (fork point, serialized entries this put adds)
|
||||
staged: dict[
|
||||
tuple[str, str, str],
|
||||
tuple[tuple[str, int] | None, dict[int, tuple[str, bytes]]],
|
||||
] = {}
|
||||
for k, w in writes.items():
|
||||
tid = w.transcript_id
|
||||
key = (thread_id, checkpoint_ns, tid)
|
||||
if key in staged:
|
||||
raise ValueError(f"transcript {tid}: written twice in one put")
|
||||
if w.entries and k not in new_versions:
|
||||
raise ValueError(
|
||||
f"transcript {tid}: entries on unversioned channel {k}"
|
||||
)
|
||||
if (w.parent_transcript_id is None) != (w.fork_seq is None):
|
||||
raise ValueError(
|
||||
f"transcript {tid}: parent_transcript_id and fork_seq go together"
|
||||
)
|
||||
given = (
|
||||
None
|
||||
if w.parent_transcript_id is None
|
||||
else (w.parent_transcript_id, w.fork_seq)
|
||||
)
|
||||
if key in self.transcripts:
|
||||
fork = self.transcripts[key]
|
||||
if given is not None and given != fork:
|
||||
raise ValueError(
|
||||
f"transcript {tid}: fork point differs from its own"
|
||||
)
|
||||
if tid not in parent_heads:
|
||||
raise ValueError(
|
||||
f"transcript {tid}: the parent checkpoint does not point at it"
|
||||
)
|
||||
base = parent_heads[tid]
|
||||
else:
|
||||
if given is not None:
|
||||
parent = (thread_id, checkpoint_ns, given[0])
|
||||
if parent not in self.transcripts or not (
|
||||
0 <= given[1] <= self._last_seq(parent)
|
||||
):
|
||||
raise ValueError(
|
||||
f"transcript {tid}: no stored parent entry at fork_seq {given[1]}"
|
||||
)
|
||||
fork = given
|
||||
base = given[1] if given else 0
|
||||
seqs = [e.seq for e in w.entries]
|
||||
if w.head < base or seqs != list(range(base + 1, w.head + 1)):
|
||||
raise ValueError(
|
||||
f"transcript {tid}: entries must be seqs {base + 1}..{w.head}, got {seqs}"
|
||||
)
|
||||
stored = self.transcript_entries.get(key, {})
|
||||
if any(seq in stored for seq in seqs):
|
||||
raise TranscriptConflictError(
|
||||
f"transcript {tid} already holds an entry in {base + 1}..{w.head}"
|
||||
)
|
||||
staged[key] = (
|
||||
fork,
|
||||
{e.seq: self.serde.dumps_typed(e.value) for e in w.entries},
|
||||
)
|
||||
|
||||
def commit() -> None:
|
||||
for key, (fork, new) in staged.items():
|
||||
self.transcripts[key] = fork
|
||||
self.transcript_entries.setdefault(key, {}).update(new)
|
||||
|
||||
return stored_values, commit
|
||||
|
||||
def _last_seq(self, key: tuple[str, str, str]) -> int:
|
||||
fork = self.transcripts[key]
|
||||
return (fork[1] if fork else 0) + len(self.transcript_entries.get(key, {}))
|
||||
|
||||
def get_transcript(
|
||||
self, *, config: RunnableConfig, ref: _TranscriptRef
|
||||
) -> _Transcript:
|
||||
thread_id = config["configurable"]["thread_id"]
|
||||
checkpoint_ns = config["configurable"].get("checkpoint_ns", "")
|
||||
transcript_id: str | None = ref.transcript_id
|
||||
head = ref.head
|
||||
own = self.transcript_entries.get(
|
||||
(thread_id, checkpoint_ns, ref.transcript_id), {}
|
||||
)
|
||||
entries: list[_TranscriptEntry] = []
|
||||
while transcript_id is not None:
|
||||
key = (thread_id, checkpoint_ns, transcript_id)
|
||||
fork = self.transcripts.get(key)
|
||||
floor = fork[1] if fork else 0
|
||||
entries += [
|
||||
_TranscriptEntry(seq, self.serde.loads_typed(blob))
|
||||
for seq, blob in self.transcript_entries.get(key, {}).items()
|
||||
if floor < seq <= head
|
||||
]
|
||||
transcript_id, head = (fork[0], min(head, fork[1])) if fork else (None, 0)
|
||||
if len(entries) != ref.head:
|
||||
raise ValueError(
|
||||
f"transcript {ref.transcript_id}: {len(entries)} entries through head {ref.head}"
|
||||
)
|
||||
return _Transcript(
|
||||
sorted(entries, key=lambda e: e.seq), any(seq > ref.head for seq in own)
|
||||
)
|
||||
|
||||
async def aget_transcript(
|
||||
self, *, config: RunnableConfig, ref: _TranscriptRef
|
||||
) -> _Transcript:
|
||||
return self.get_transcript(config=config, ref=ref)
|
||||
|
||||
def get_delta_channel_history(
|
||||
self, *, config: RunnableConfig, channels: Sequence[str]
|
||||
) -> Mapping[str, DeltaChannelHistory]:
|
||||
@@ -452,19 +650,23 @@ class InMemorySaver(
|
||||
thread_id = config["configurable"]["thread_id"]
|
||||
checkpoint_ns = config["configurable"]["checkpoint_ns"]
|
||||
values: dict[str, Any] = c.pop("channel_values") # type: ignore[misc]
|
||||
for k, v in new_versions.items():
|
||||
self.blobs[(thread_id, checkpoint_ns, k, v)] = (
|
||||
values, commit_transcripts = self._put_transcripts(
|
||||
config, checkpoint["id"], values, new_versions
|
||||
)
|
||||
blobs = {
|
||||
(thread_id, checkpoint_ns, k, v): (
|
||||
self.serde.dumps_typed(values[k]) if k in values else ("empty", b"")
|
||||
)
|
||||
self.storage[thread_id][checkpoint_ns].update(
|
||||
{
|
||||
checkpoint["id"]: (
|
||||
self.serde.dumps_typed(c),
|
||||
self.serde.dumps_typed(get_checkpoint_metadata(config, metadata)),
|
||||
config["configurable"].get("checkpoint_id"), # parent
|
||||
)
|
||||
}
|
||||
for k, v in new_versions.items()
|
||||
}
|
||||
saved = (
|
||||
self.serde.dumps_typed(c),
|
||||
self.serde.dumps_typed(get_checkpoint_metadata(config, metadata)),
|
||||
config["configurable"].get("checkpoint_id"), # parent
|
||||
)
|
||||
commit_transcripts()
|
||||
self.blobs.update(blobs)
|
||||
self.storage[thread_id][checkpoint_ns][checkpoint["id"]] = saved
|
||||
return {
|
||||
"configurable": {
|
||||
"thread_id": thread_id,
|
||||
@@ -528,6 +730,9 @@ class InMemorySaver(
|
||||
for k in list(self.blobs.keys()):
|
||||
if k[0] == thread_id:
|
||||
del self.blobs[k]
|
||||
for tk in [k for k in self.transcripts if k[0] == thread_id]:
|
||||
del self.transcripts[tk]
|
||||
self.transcript_entries.pop(tk, None)
|
||||
|
||||
async def aget_tuple(self, config: RunnableConfig) -> CheckpointTuple | None:
|
||||
"""Asynchronous version of `get_tuple`.
|
||||
|
||||
@@ -79,6 +79,7 @@ SAFE_MSGPACK_TYPES: frozenset[tuple[str, ...]] = frozenset(
|
||||
("langgraph.types", "StateSnapshot"),
|
||||
("langgraph.types", "PregelTask"),
|
||||
("langgraph.types", "Overwrite"),
|
||||
("langgraph.checkpoint.serde.types", "_TranscriptRef"),
|
||||
("langgraph.store.base", "Item"),
|
||||
("langgraph.store.base", "GetOp"),
|
||||
}
|
||||
|
||||
@@ -31,6 +31,73 @@ class _DeltaSnapshot(NamedTuple):
|
||||
value: Any
|
||||
|
||||
|
||||
class _TranscriptEntry(NamedTuple):
|
||||
"""One immutable entry of a transcript.
|
||||
|
||||
The writer assigns `seq`. The saver serializes `value` with its own serde.
|
||||
"""
|
||||
|
||||
seq: int
|
||||
value: Any
|
||||
|
||||
|
||||
class _TranscriptRef(NamedTuple):
|
||||
"""Pointer to a transcript, stored as the checkpoint's value for a channel."""
|
||||
|
||||
transcript_id: str
|
||||
head: int
|
||||
|
||||
|
||||
class _TranscriptWrite(NamedTuple):
|
||||
"""What a channel hands `put` for a transcript.
|
||||
|
||||
The saver stores `entries` in the checkpoint's transaction and keeps
|
||||
`_TranscriptRef(transcript_id, head)` as the channel's value. A write carries
|
||||
exactly the entries its checkpoint adds:
|
||||
|
||||
- The base is the head of the parent checkpoint's pointer to this transcript.
|
||||
For a transcript the put creates, it is `fork_seq`, or 0 without a parent.
|
||||
- `entries` have seqs `base + 1` through `head`, in order, with no gaps and
|
||||
nothing at or below the base. A write with no entries has `head == base`.
|
||||
- An entry at a seq the transcript already holds raises
|
||||
`TranscriptConflictError`, whatever its content.
|
||||
- A transcript the parent checkpoint does not point at can only be created,
|
||||
not written to.
|
||||
- `parent_transcript_id` and `fork_seq` are set together, on the write that
|
||||
creates a fork. Later writes may omit them; if given, they must match. The
|
||||
parent must already be stored, before this put, in the same thread and
|
||||
namespace with entries through `fork_seq`.
|
||||
- Only a channel in `new_versions` may carry entries, and one put writes each
|
||||
transcript at most once.
|
||||
- A put whose checkpoint id is already stored is a replay: its pointers must
|
||||
equal the stored ones, and its entries are not checked or stored. A retry
|
||||
resends the same put, with the same checkpoint id.
|
||||
|
||||
Breaking any other rule raises `ValueError`. A rejected put stores nothing.
|
||||
A bare `_TranscriptRef` in a checkpoint is checked as a write with no entries.
|
||||
"""
|
||||
|
||||
transcript_id: str
|
||||
head: int
|
||||
entries: Sequence[_TranscriptEntry] = ()
|
||||
parent_transcript_id: str | None = None
|
||||
fork_seq: int | None = None
|
||||
|
||||
|
||||
class _Transcript(NamedTuple):
|
||||
"""Entries `1..head` of a transcript, with ancestors' shared prefixes resolved.
|
||||
|
||||
Reading a head past the stored entries raises `ValueError`.
|
||||
|
||||
`has_later_entries` is true when the transcript holds an entry of its own
|
||||
above the requested head. A writer that loaded such a head forks instead of
|
||||
appending.
|
||||
"""
|
||||
|
||||
entries: list[_TranscriptEntry]
|
||||
has_later_entries: bool
|
||||
|
||||
|
||||
Value = TypeVar("Value", covariant=True)
|
||||
Update = TypeVar("Update", contravariant=True)
|
||||
C = TypeVar("C")
|
||||
|
||||
@@ -13,11 +13,17 @@ from langgraph.checkpoint.base import (
|
||||
empty_checkpoint,
|
||||
)
|
||||
from langgraph.checkpoint.memory import InMemorySaver
|
||||
from langgraph.checkpoint.serde.encrypted import EncryptedSerializer
|
||||
from langgraph.checkpoint.serde.jsonplus import (
|
||||
JsonPlusSerializer,
|
||||
_warned_blocked_types,
|
||||
_warned_unregistered_types,
|
||||
)
|
||||
from langgraph.checkpoint.serde.types import (
|
||||
_TranscriptEntry,
|
||||
_TranscriptRef,
|
||||
_TranscriptWrite,
|
||||
)
|
||||
|
||||
|
||||
class MemoryPydantic(BaseModel):
|
||||
@@ -720,3 +726,51 @@ class TestPreDeltaBlobTerminator:
|
||||
assert "PRE-DELTA-WRITE" in values
|
||||
# And the pending write at the target is never folded in.
|
||||
assert "PENDING-AT-TARGET" not in values
|
||||
|
||||
|
||||
def test_transcript_entries_round_trip_under_encryption() -> None:
|
||||
saver = InMemorySaver(
|
||||
serde=EncryptedSerializer.from_pycryptodome_aes(key=b"1234567890123456")
|
||||
)
|
||||
config: RunnableConfig = {"configurable": {"thread_id": "t", "checkpoint_ns": ""}}
|
||||
checkpoint = empty_checkpoint()
|
||||
checkpoint["channel_values"] = {
|
||||
"messages": _TranscriptWrite("T", 1, [_TranscriptEntry(1, {"text": "a"})])
|
||||
}
|
||||
saver.put(config, checkpoint, {}, {"messages": 1})
|
||||
read = saver.get_transcript(config=config, ref=_TranscriptRef("T", 1))
|
||||
assert read.entries == [_TranscriptEntry(1, {"text": "a"})]
|
||||
|
||||
|
||||
def test_transcript_entries_need_a_new_version() -> None:
|
||||
saver = InMemorySaver()
|
||||
config: RunnableConfig = {"configurable": {"thread_id": "t", "checkpoint_ns": ""}}
|
||||
checkpoint = empty_checkpoint()
|
||||
checkpoint["channel_values"] = {
|
||||
"messages": _TranscriptWrite("T", 1, [_TranscriptEntry(1, "a")])
|
||||
}
|
||||
with pytest.raises(ValueError):
|
||||
saver.put(config, checkpoint, {}, {})
|
||||
|
||||
|
||||
def test_transcript_failed_put_stores_no_entries() -> None:
|
||||
saver = InMemorySaver()
|
||||
config: RunnableConfig = {"configurable": {"thread_id": "t", "checkpoint_ns": ""}}
|
||||
checkpoint = empty_checkpoint()
|
||||
checkpoint["channel_values"] = {
|
||||
"messages": _TranscriptWrite("T", 1, [_TranscriptEntry(1, "a")]),
|
||||
"other": object(),
|
||||
}
|
||||
with pytest.raises(TypeError):
|
||||
saver.put(config, checkpoint, {}, {"messages": 1, "other": 1})
|
||||
read = saver.get_transcript(config=config, ref=_TranscriptRef("T", 0))
|
||||
assert read == ([], False)
|
||||
|
||||
|
||||
def test_transcript_bare_ref_is_checked() -> None:
|
||||
saver = InMemorySaver()
|
||||
config: RunnableConfig = {"configurable": {"thread_id": "t", "checkpoint_ns": ""}}
|
||||
checkpoint = empty_checkpoint()
|
||||
checkpoint["channel_values"] = {"messages": _TranscriptRef("T", 5)}
|
||||
with pytest.raises(ValueError):
|
||||
saver.put(config, checkpoint, {}, {"messages": 1})
|
||||
Reference in new issue
Block a user