Skip to content

docs(checkpoint): mark DeltaChannel and delta-history APIs as beta - #7732

Merged
Sydney Runkle (sydney-runkle) merged 1 commit into
mainfrom
sr/delta-is-beta
May 7, 2026
Merged

Sydney Runkle (sydney-runkle) merged 1 commit into
mainfrom
sr/delta-is-beta

Conversation

@sydney-runkle

Copy link
Copy Markdown
Collaborator

Summary

Adds a Beta admonition to the DeltaChannel surface area so users can distinguish stable from in-progress contracts. Single-sourced on the base class; subclass overrides in checkpoint-postgres / checkpoint-sqlite / memory inherit the marker via their existing references back to the base.

Touched:

  • DeltaChannel (libs/langgraph/langgraph/channels/delta.py)
  • BaseCheckpointSaver.get_delta_channel_history and aget_delta_channel_history (libs/checkpoint/.../base/__init__.py)
  • DeltaChannelHistory TypedDict
  • CheckpointMetadata.delta_updates_since_snapshot

Why docstring admonitions, not @beta

The base get_delta_channel_history methods are designed to be overridden by savers. Wrapping with @beta (from langchain_core._api) would emit warnings whenever a subclass called super().get_delta_channel_history(...) or whenever the default ancestor walk fired. Docstring-only keeps the signal advisory and noise-free. _DeltaSnapshot is already leading-underscore-private, so it implicitly signals "internal."

Versioning note

This intentionally stays a minor bump for the checkpoint releases (4.0 → 4.1, 3.0 → 3.1):

  • The new methods are strictly additive — defaults provided on the base, no signatures changed, no removed APIs. Third-party savers keep working without overriding anything.
  • The beta marker and the version bump do orthogonal jobs: semver answers "is this a breaking change?" (no), the marker answers "is this contract stable?" (no).
  • Bumping major now would consume the lever you want available for when the delta contract actually changes in a breaking way.

Test plan

  • Docstring-only — no behavioral change
  • make format && make lint clean in libs/checkpoint and libs/langgraph

Adds "Beta" admonitions to the DeltaChannel surface so users can
distinguish stable from in-progress contracts:

- `DeltaChannel` (langgraph.channels.delta)
- `BaseCheckpointSaver.get_delta_channel_history` and async variant
- `DeltaChannelHistory` TypedDict
- `CheckpointMetadata.delta_updates_since_snapshot`

Single-sourced on the base class so subclass overrides in
checkpoint-postgres / checkpoint-sqlite / memory inherit the marker via
their existing references back to the base. Uses docstring admonitions
rather than the `@beta` decorator since these methods are designed to be
overridden — wrapping them would emit warnings on every `super()` call.
@sydney-runkle
Sydney Runkle (sydney-runkle) merged commit 9032a3f into main May 7, 2026
68 checks passed
@sydney-runkle
Sydney Runkle (sydney-runkle) deleted the sr/delta-is-beta branch May 7, 2026 10:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant