Follow-up to #8540, which turned on `PLC0415` (import-outside-top-level)
for checkpoint-postgres and checkpoint-sqlite. This does the remaining
six packages: checkpoint, checkpoint-conformance, langgraph, prebuilt,
cli, sdk-py.
Scoped to tests, per @sydney-runkle's call on #8540: library code is
exempted with `per-file-ignores`, since it still has deferred imports
nobody has reviewed and mixing that in would make this hard to read.
## What changed
Function-level imports across 56 test files moved to module level. Nine
could not move and carry an explicit `# noqa: PLC0415` with a reason:
| File | Why it stays local |
|---|---|
| `libs/langgraph/tests/test_deprecation.py` (4) | the import has to run
inside `pytest.warns` for the warning to be observed |
| `libs/langgraph/tests/test_serde_allowlist.py` | try/except guard,
skips when langchain_core is absent |
| `libs/langgraph/tests/test_delta_channel_benchmark.py` | optional
psycopg probe |
| `libs/checkpoint/tests/test_conformance_delta.py` (3) | protected by a
module-level `pytest.importorskip`; hoisting past the guard turns a skip
into a collection error |
That last one is the trap: an import moved above `pytest.importorskip`
silently defeats the guard. I hit it locally and it turned the skip into
a `ModuleNotFoundError` at collection. Every file with an `importorskip`
or `except ImportError` was checked by hand for this.
## Verification
`make lint` and `make test` in each of the six:
| Package | Tests |
|---|---|
| checkpoint | 156 passed, 17 skipped |
| checkpoint-conformance | 1 passed |
| langgraph | 1968 passed, 4 skipped |
| prebuilt | 284 passed |
| cli | 336 passed |
| sdk-py | 493 passed |
Also confirmed the rule actually fires: a throwaway test file with a
function-level import is flagged in all six packages, and the source
exemption holds.
`CronClient.update` / `SyncCronClient.update` stripped all `None`-valued
fields from the PATCH body, so `update(end_time=None)` could never clear
a previously set cron end time. This routes an explicit `None` through
as `end_time: null` (via the existing `NOT_PROVIDED` sentinel), while an
omitted argument still leaves the value unchanged.
Verified with `make format`, `make lint`, and `make test` in
`libs/sdk-py` (493 passed), including two new tests asserting the PATCH
body carries an explicit null `end_time`.
## Summary
- replace Python lint type-checking from mypy to ty across LangGraph
packages
- remove mypy config/cache wiring and mypy-only references
- regenerate uv locks with ty 0.0.43
## Verification
- git diff --check
- make lint_package && make lint_tests in libs/langgraph
- make lint_package && make lint_tests in libs/checkpoint
- make lint_package && make lint_tests in libs/checkpoint-sqlite
- make lint_package && make lint_tests in libs/checkpoint-postgres
- make lint_package && make lint_tests in libs/prebuilt
- make lint_package && make lint_tests in libs/cli
- make lint in libs/sdk-py
- make lint in libs/checkpoint-conformance
---------
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: open-swe[bot] <215916821+open-swe[bot]@users.noreply.github.com>
## Problem
Fixes#7953.
The v3 SSE and WebSocket stream transports build their default paths by
interpolating `thread_id` directly into the URL:
```python
self._commands_url = commands_path or f"/threads/{thread_id}/commands"
self._stream_url = stream_path or f"/threads/{thread_id}/stream/events"
```
This skips the `_quote_path_param` escaping that the rest of the SDK
adopted in #7893. A `thread_id` containing reserved characters or
dot-segments is then normalized by the HTTP/WebSocket stack before
transmission. For example, `thread_id = "../assistants/abc"`:
| | before |
|---|---|
| constructed | `/threads/../assistants/abc/commands` |
| wire path | `/assistants/abc/commands` |
So the value stops being one opaque identifier under
`/threads/{thread_id}/...` and silently hits a different resource.
## Fix
Reuse the existing `_quote_path_param` helper for the **default** paths
in all four transports (`http`, `sync_http`, `ws`, `sync_ws`). Explicit
`commands_path` / `stream_path` overrides are left untouched, so callers
that pass their own paths opt out of encoding as before.
`_quote_path_param("../assistants/abc")` → `..%2Fassistants%2Fabc`,
which the HTTP/WS stack no longer collapses.
## Tests
Adds `tests/streaming/test_transport_path_encoding.py` covering all four
transports:
- default `_commands_url` / `_stream_url` / `_stream_path` are
percent-encoded,
- the actual SSE wire path (async + sync) stays under `/threads/`,
- the built WebSocket URL (async + sync) stays under `/threads/`,
- explicit path overrides are left untouched.
`make format`, `make lint`, and `make test` all pass in `libs/sdk-py`
(491 passed).
## Summary
Refactors the four (now five) sdk-py streaming projections into
reusable, transport-agnostic `Decoder` classes and adds a new
`interleave_projections(channels)` method to `AsyncThreadStream` and
`SyncThreadStream` that drives multiple decoders from one shared
subscription, yielding `(channel_name, item)` tuples in arrival order
(the SDK analog of local `GraphRunStream.interleave`).
- **New `langgraph_sdk/stream/decoders.py`**: pure `feed(event) ->
Iterable[item]` state machines — `ValuesDecoder`, `MessagesDecoder`,
`ToolCallsDecoder`, `SubgraphsDecoder`, `ExtensionsDecoder` — behind a
`Decoder` Protocol. No subscription/queue/thread access.
- **Projection migration (async + sync)**: the five existing projections
now delegate their per-event logic to the decoders. Behavior-preserving
— the existing test suite is the regression net. Thread-coupled side
effects (active-stream registration, terminal-error-on-close, root-inbox
forwarding) stay in the projection wrappers; sync messages/tool_calls
keep their pre-dispatch contract (handle/stream resolved on yield) via a
FIFO-head buffer.
- **`interleave_projections`**: flat-namespace channel list (built-ins +
extension names), `tool_calls`↔`tools` wire mapping, subgraphs fed every
event, extensions keyed by bare name.
### Notable
- Fixes a latent sync bug surfaced by the refactor: two tool calls /
messages whose events interleave previously dropped the second; both now
surface. Locked in with a regression test.
- `Decoder.feed` takes `Mapping[str, Any]` (read-only), so the Protocol
is load-bearing in both stream files.
### Deferred (not in this PR)
- Wiring `RemoteGraph._RemoteGraphRunStream.interleave` to
`interleave_projections` (gated on #7927).
- Migrating the handle-scoped projections (`_Handle*Projection`) to the
decoders — hence the small, verified-identical helper duplication
between `decoders.py` and `_async/stream.py`.
- `interleave_projections` handles aren't registered for thread-close
cleanup (additive follow-up).
## Test Plan
- [x] `make test` in `libs/sdk-py` — 464 passed, 0 failures
- [x] `make format` / `make lint` (ruff + ty) clean
- [x] Per-decoder unit tests in `tests/streaming/test_decoders.py`
- [x] `interleave_projections` tests (single-channel, multi-channel
arrival order, builtin+extension mix, tool_calls public-name, subgraphs
discovery) async + sync
- [x] Existing projection suites pass unchanged (regression net for the
migration)
## Summary
- Adds `stream_events(version="v3")` and `astream_events(version="v3")`
to `RemoteGraph`, matching the local `CompiledStateGraph` surface and
unblocking polymorphic v3 streaming over `Graph | RemoteGraph`.
- Implementation is a thin adapter
(`libs/langgraph/langgraph/pregel/_remote_run_stream.py`) that wraps the
v3 SDK's `AsyncThreadStream` / `SyncThreadStream` and duck-types
`GraphRunStream` / `AsyncGraphRunStream`. No coupling to local v3 mux
internals.
- `v1` / `v2` paths unchanged. `astream_events(version='v1'|'v2')` still
raises `NotImplementedError` (separate gap).
### Scope decisions baked into this PR
- Unsupported v3 kwargs hard-reject at dispatch with
`NotImplementedError`: `control`, `transformers`, `interrupt_before`,
`interrupt_after`, and any unknown `**kwargs`. Server / SDK don't plumb
these through v3 yet; easy to lift later.
- Sync `interleave()` raises `NotImplementedError` pointing callers at
`astream_events`. Real sync interleave would need drainer threads;
deferred since most sync RemoteGraph callers just iterate raw events.
- Async `interleave()` is best-effort ordering (client receive order),
documented as a divergence from local v3's monotonic stamp ordering.
- Adapter `interrupted` / `interrupts` properties are **non-blocking**
snapshots of the SDK's current state. This differs from local
`(Async)GraphRunStream.interrupted`, which pump-drives the run to
terminal before returning. Callers needing a wait-for-interrupt pattern
should drain a projection (e.g., `interleave('values')`) until the SDK's
paused sentinel fires. Documented in the adapter docstrings.
### Audit of impact
Existing RemoteGraph callers in this org all use the v2 `.stream()` /
`.astream()` path (deepagents production wrapper, langgraph-api test
graphs, langgraph-supervisor TS type guard). **Zero callers** use
`stream_events` / `astream_events` on RemoteGraph today, so the new v3
methods are net-new surface — no risk of breaking existing consumers.
### Out of scope (follow-ups)
- Bumping `libs/langgraph/pyproject.toml`'s `langgraph-sdk` constraint
from `<0.4.0` to `<0.5.0`. Deferred until 0.4.0 publishes to PyPI; dev
resolution unaffected via the editable workspace dep.
- Real `astream_events(version='v1'|'v2')` implementation.
- Server-side plumbing for `control` / `interrupt_before` /
`interrupt_after` on v3 runs.
- Sync `interleave()` via drainer threads.
## Test plan
- [x] \`make test\` in \`libs/langgraph/\`: 1874 passed, 4 skipped (43
new in \`test_remote_graph_v3.py\`)
- [x] \`make lint\` in \`libs/langgraph/\`: ruff + mypy clean
- [x] \`pytest -m integration
tests/integration/test_remote_graph_v3.py\` in \`libs/sdk-py/\` against
the docker stack: 4/4 passed in 1.35s
- [x] Manual smoke: \`RemoteGraph('tools_agent',
url='http://localhost:2024').astream_events(..., version='v3')\`
end-to-end against the v3 integration api
- [x] Existing RemoteGraph v2 tests untouched (31 passed, 3 skipped with
docker up)
- [x] Will need rebase after \`langgraph-sdk 0.4.0\` lands on PyPI and
the version constraint is bumped in a separate PR
## Summary
Wraps every caller-supplied identifier (thread_id, assistant_id, run_id,
cron_id, checkpoint_id, namespace) interpolated into request URL paths
with `urllib.parse.quote(safe="")` via a new `_quote_path_param` helper.
All-dot strings are encoded as `%2E` triplets so they aren't collapsed
by httpx's client-side path normalization. Helper raises `TypeError` for
None/bytes inputs.
## Test plan
- [x] `make format` / `make lint` / `make test` from `libs/sdk-py`
## Description
Mirrors a server-side change by accepting an optional \`metadata\`
filter on \`crons.search\` and \`crons.count\` in both the async and
sync Python SDK clients. Matches the existing pattern used for
assistants/threads search.
## Release Note
Python SDK: \`crons.search\` and \`crons.count\` now accept an optional
\`metadata\` filter that is forwarded to the server.
## Test Plan
- [ ] New unit tests in \`tests/test_crons_client.py\` verify metadata
is forwarded for both async and sync clients and omitted when not
provided.
---------
Co-authored-by: open-swe[bot] <open-swe@users.noreply.github.com>
Co-authored-by: Parker J. Rule <pjrule@users.noreply.github.com>
Adds a first-class `return_minimal` option to the Python
`threads.update` clients. When enabled, the SDK sends `Prefer:
return=minimal` and returns `None` for the 204 response. Covers both
async and sync clients with focused tests.
## Summary
- Adds a `langsmith_tracing` parameter to `runs.create()`,
`runs.stream()`, and `runs.wait()` on both async and sync SDK clients
- Accepts a `LangSmithTracing` TypedDict with optional `project_name`
and `example_id` fields
- Maps to the server's existing `langsmith_tracer` payload key, enabling
users to route traces to specific LangSmith projects or associate with
dataset examples from the SDK
## Test plan
- [x] Unit tests verify payload serialization (langsmith_tracing →
langsmith_tracer mapping)
- [x] Unit tests verify key is excluded when param not provided
- [x] Unit tests verify partial configs (project_name only) work
- [x] API parity tests pass (async/sync client signatures match)
- [x] Full test suite passes (86 tests)
- [x] Lint + type check pass
Release Notes: Added `langsmith_tracing` parameter to `runs.create()`,
`runs.stream()`, and `runs.wait()` in the Python SDK, allowing users to
route traces to a specific LangSmith project or associate with a dataset
example.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Will Fu-Hinthorn <will@langchain.dev>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Additional guidelines:
- Make sure optional dependencies are imported within a function.
- Please do not add dependencies to `pyproject.toml` files (even
optional ones) unless they are **required** for unit tests.
- Most PRs should not touch more than one package.
- Changes should be backwards compatible.
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
**Description:** The crons create endpoint supports an end-time field
that is not currently supported in the client. Adding that parameter
here.
**Issue:** N/A
**Dependencies:** N/A
**Twitter handle:** N/A
In langgraph-api, custom-encrypted JSONs need to continue to be
SQL-json-mergable after encryption. Previous WIP docs
advocated for custom encryption impls where all encrypted kv pairs were
shoved into a `__encrypted__: $encrypted_kvs` meta-key. Turns out that
pattern causes data loss when running PATCH-style partial updates or in
the many places langgraph-api json-SQL-merges across model types.
This PR contains 2 SDK fixes:
1. remove model-type specific custom json encryption annotations - these
cause surprising behavior as config and context data propagates across
model types, specifically because today we can't guarantee that data
encrypted as one model-type will be decrypted as the same model-type
because kv pairs move across model-types in pure SQL
2. document limitations and validation around "key preservation" in
custom json encryption functions. langgraph-api now validates that
custom JSON encryption fns don't change keys. That validation prevents
customizers from writing custom encryption functions that cause data
loss through patch endpoints and x-model merge propagation.
---------
Signed-off-by: Connor Braa <cwlbraa@langchain.dev>
- **Description:** Provide the id of the event for routes that use SSE
streams. This will allow for more custom retry logic when streams
disconnect if needed.
- **Issue:** N/A
- **Dependencies:** N/A
- **Twitter handle:** N/A
---------
Co-authored-by: William FH <13333726+hinthornw@users.noreply.github.com>
**Description:**
This PR adds the Python SDK types necessary for langgraph platform users
to inject their own custom encryption-at-rest functions. See [docs
PR](https://github.com/langchain-ai/docs/pull/1715) for more details.
note: this PR adds a starlette dev dependency so that custom encryption
can access BaseUser information.
**Issue:**
required for LSD-172
**Dependencies:**
- [depended upon by associated langgraph-api
changes](https://github.com/langchain-ai/langgraph-api/pull/1773)(this
PR must merge before that one)
- [docs PR](https://github.com/langchain-ai/docs/pull/1715)
**TODO:**
- [x] move docs to docs repo
- [x] bump package versions before merge
---------
Signed-off-by: Connor Braa <cwlbraa@langchain.dev>
Co-authored-by: Claude <noreply@anthropic.com>
**Description:** There are times a user might want to create the client,
but conditionally set the API key. For example, consider a complex auth
situation where the system has user callers using jwts and system
callers using API keys. This allows explicitly disabling the
auto-loading behavior of API keys in the client today, so no key is set.
**Issue:** N/A
**Dependencies:** None
**Twitter handle:** N/A
## Summary
- add a public accessor for the last received SSE event id
- retry async and sync SSE streams using the Location reconnect path and
Last-Event-ID while skipping empty events
- add regression tests that simulate interrupted SSE streams for both
async and sync clients
## Testing
- make format
- make lint
- make test
------
https://chatgpt.com/codex/tasks/task_e_68ca8bfa26cc832d98bcb359884962ec
## Summary
- ensure both async and sync HTTP clients flush the SSE decoder after
streaming
- add regression tests covering trailing SSE events without a
terminating blank line
## Testing
- make format
- make lint
- make test
------
https://chatgpt.com/codex/tasks/task_e_68c9727ca9f8832d9f207323c5e02a72
