langgraph-api 0.14.0.dev10__tar.gz → 0.15.0.dev1__tar.gz

{langgraph_api-0.14.0.dev10 → langgraph_api-0.15.0.dev1}/Makefile

@@ -1,7 +1,7 @@
 .PHONY: build release lint format test test_watch start start-inmem start-inmem-license-oss start build-go-server start-go-server stop-go-server check-version check-base-imports test-a2a-tck test-a2a-tck-mandatory start-test-a2a-tck start-test-a2a-tck-mandatory start-test-a2a-tck-watch test-mcp-conformance start-test-mcp-conformance list-mcp-scenarios test-auth-read-only-assistant
 
 # Environment variables
-LANGSERVE_GRAPHS_ALL = '{"agent": {"path": "./tests/graphs/agent.py:graph", "description": "agent"}, "assistant_id_runtime": "./tests/graphs/assistant_id_runtime.py:graph", "custom_lifespan": "./tests/graphs/my_router.py:graph", "single_node": "./tests/graphs/single_node.py:graph", "benchmark": "./tests/graphs/benchmark.py:graph", "config_graph": "./tests/graphs/config_graph.py:graph", "other": "./tests/graphs/other.py:make_graph", "weather": "./tests/graphs/weather.py:mk_weather_graph", "searchy": "./tests/graphs/searchy.py:graph", "agent_simple": "./tests/graphs/agent_simple.py:graph", "simple_runtime": "./tests/graphs/simple_runtime.py:graph", "agent_interrupt": "./tests/graphs/agent_interrupt.py:graph", "agent_parallel_interrupt": "./tests/graphs/agent_parallel_interrupt.py:graph", "message_type_test": "./tests/graphs/message_type_test.py:graph", "remote_subgraph_parent": "./tests/graphs/remote_subgraph_parent.py:graph", "simple_remote": "./tests/graphs/simple_remote.py:graph", "nested_subgraphs": "./tests/graphs/nested_subgraphs.py:graph", "functional_fibonacci": "./tests/graphs/functional_fibonacci.py:fibonacci", "state_graph_fibonacci": "./tests/graphs/state_graph_fibonacci.py:fibonacci", "max_concurrency_graph": "./tests/graphs/max_concurrency_graph.py:graph", "unserializable_subgraph": "./tests/graphs/unserializable_subgraph.py:graph", "agent_interrupt_text": "./tests/graphs/agent_interrupt_text.py:graph", "agent_echo_stream": "./tests/graphs/agent_echo_stream.py:graph", "agent_tool_stream": "./tests/graphs/agent_tool_stream.py:graph", "runtime_graph": "./tests/graphs/runtime_graph.py:graph", "tool_call_chunk_stream": "./tests/graphs/tool_call_chunk_stream.py:graph", "ui_tool_call_stream": "./tests/graphs/ui_tool_call_stream.py:graph", "agent_metrics_stream": "./tests/graphs/agent_metrics_stream.py:graph", "agent_multimodal_stream": "./tests/graphs/agent_multimodal_stream.py:graph", "agent_bedtime_story": "./tests/graphs/agent_bedtime_story.py:graph", "delta_channel": "./tests/graphs/delta_channel.py:graph", "delta_channel_freq": "./tests/graphs/delta_channel_freq.py:graph", "delta_channel_files": "./tests/graphs/delta_channel_files.py:graph", "delta_channel_files_freq": "./tests/graphs/delta_channel_files_freq.py:graph", "delta_channel_legacy": "./tests/graphs/delta_channel_migration.py:graph_legacy", "delta_channel_delta": "./tests/graphs/delta_channel_migration.py:graph_delta", "delta_channel_delta_filter": "./tests/graphs/delta_channel_migration.py:graph_delta_filter", "delta_channel_messages_freq": "./tests/graphs/delta_channel_messages.py:graph_freq", "delta_channel_messages": "./tests/graphs/delta_channel_messages.py:graph", "delta_channel_messages_legacy": "./tests/graphs/delta_channel_messages.py:graph_legacy", "delta_channel_messages_remove": "./tests/graphs/delta_channel_messages.py:graph_remove", "delta_channel_messages_update": "./tests/graphs/delta_channel_messages.py:graph_update", "delta_channel_messages_delta": "./tests/graphs/delta_channel_messages.py:graph_delta", "store_e2e_async": "./tests/graphs/store_e2e.py:graph_async", "store_e2e_sync": "./tests/graphs/store_e2e.py:graph_sync"}'
+LANGSERVE_GRAPHS_ALL = '{"agent": {"path": "./tests/graphs/agent.py:graph", "description": "agent"}, "assistant_id_runtime": "./tests/graphs/assistant_id_runtime.py:graph", "custom_lifespan": "./tests/graphs/my_router.py:graph", "single_node": "./tests/graphs/single_node.py:graph", "benchmark": "./tests/graphs/benchmark.py:graph", "benchmark_delta": "./tests/graphs/benchmark.py:graph_delta", "benchmark_delta_freq": "./tests/graphs/benchmark.py:graph_delta_freq", "config_graph": "./tests/graphs/config_graph.py:graph", "other": "./tests/graphs/other.py:make_graph", "weather": "./tests/graphs/weather.py:mk_weather_graph", "searchy": "./tests/graphs/searchy.py:graph", "agent_simple": "./tests/graphs/agent_simple.py:graph", "simple_runtime": "./tests/graphs/simple_runtime.py:graph", "agent_interrupt": "./tests/graphs/agent_interrupt.py:graph", "agent_parallel_interrupt": "./tests/graphs/agent_parallel_interrupt.py:graph", "message_type_test": "./tests/graphs/message_type_test.py:graph", "remote_subgraph_parent": "./tests/graphs/remote_subgraph_parent.py:graph", "simple_remote": "./tests/graphs/simple_remote.py:graph", "nested_subgraphs": "./tests/graphs/nested_subgraphs.py:graph", "functional_fibonacci": "./tests/graphs/functional_fibonacci.py:fibonacci", "state_graph_fibonacci": "./tests/graphs/state_graph_fibonacci.py:fibonacci", "max_concurrency_graph": "./tests/graphs/max_concurrency_graph.py:graph", "unserializable_subgraph": "./tests/graphs/unserializable_subgraph.py:graph", "agent_interrupt_text": "./tests/graphs/agent_interrupt_text.py:graph", "agent_echo_stream": "./tests/graphs/agent_echo_stream.py:graph", "agent_tool_stream": "./tests/graphs/agent_tool_stream.py:graph", "runtime_graph": "./tests/graphs/runtime_graph.py:graph", "tool_call_chunk_stream": "./tests/graphs/tool_call_chunk_stream.py:graph", "ui_tool_call_stream": "./tests/graphs/ui_tool_call_stream.py:graph", "agent_metrics_stream": "./tests/graphs/agent_metrics_stream.py:graph", "agent_multimodal_stream": "./tests/graphs/agent_multimodal_stream.py:graph", "agent_bedtime_story": "./tests/graphs/agent_bedtime_story.py:graph", "delta_channel": "./tests/graphs/delta_channel.py:graph", "delta_channel_freq": "./tests/graphs/delta_channel_freq.py:graph", "delta_channel_files": "./tests/graphs/delta_channel_files.py:graph", "delta_channel_files_freq": "./tests/graphs/delta_channel_files_freq.py:graph", "delta_channel_legacy": "./tests/graphs/delta_channel_migration.py:graph_legacy", "delta_channel_delta": "./tests/graphs/delta_channel_migration.py:graph_delta", "delta_channel_delta_filter": "./tests/graphs/delta_channel_migration.py:graph_delta_filter", "delta_channel_messages_freq": "./tests/graphs/delta_channel_messages.py:graph_freq", "delta_channel_messages": "./tests/graphs/delta_channel_messages.py:graph", "delta_channel_messages_legacy": "./tests/graphs/delta_channel_messages.py:graph_legacy", "delta_channel_messages_remove": "./tests/graphs/delta_channel_messages.py:graph_remove", "delta_channel_messages_update": "./tests/graphs/delta_channel_messages.py:graph_update", "delta_channel_messages_delta": "./tests/graphs/delta_channel_messages.py:graph_delta", "store_e2e_async": "./tests/graphs/store_e2e.py:graph_async", "store_e2e_sync": "./tests/graphs/store_e2e.py:graph_sync"}'
 LANGSERVE_GRAPHS_AUTH = '{"agent": {"path": "./tests/graphs/agent.py:graph", "description": "agent"}, "assistant_id_runtime": "./tests/graphs/assistant_id_runtime.py:graph", "config_graph": "./tests/graphs/config_graph.py:graph", "other": "./tests/graphs/other.py:make_graph", "weather": "./tests/graphs/weather.py:mk_weather_graph", "searchy": "./tests/graphs/searchy.py:graph", "agent_simple": "./tests/graphs/agent_simple.py:graph", "simple_runtime": "./tests/graphs/simple_runtime.py:graph", "agent_parallel_interrupt": "./tests/graphs/agent_parallel_interrupt.py:graph", "functional_fibonacci": "./tests/graphs/functional_fibonacci.py:fibonacci", "state_graph_fibonacci": "./tests/graphs/state_graph_fibonacci.py:fibonacci", "runtime_graph": "./tests/graphs/runtime_graph.py:graph"}'
 
 # Go server management

{langgraph_api-0.14.0.dev10 → langgraph_api-0.15.0.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: langgraph-api
-Version: 0.14.0.dev10
+Version: 0.15.0.dev1
 Author-email: Will Fu-Hinthorn <will@langchain.dev>, Josh Rogers <josh@langchain.dev>, Parker Rule <parker@langchain.dev>
 License: Elastic-2.0
 License-File: LICENSE
@@ -16,7 +16,7 @@ Requires-Dist: jsonschema-rs<0.45,>=0.20.0
 Requires-Dist: langchain-core>=0.3.64
 Requires-Dist: langchain-protocol<0.1,>=0.0.18
 Requires-Dist: langgraph-checkpoint<5,>=3.0.1
-Requires-Dist: langgraph-runtime-inmem<0.35.0.dev0,>=0.34.0.dev0
+Requires-Dist: langgraph-runtime-inmem<0.36.0.dev0,>=0.35.0.dev0
 Requires-Dist: langgraph-sdk>=0.3.5
 Requires-Dist: langgraph<2,>=0.4.10
 Requires-Dist: langsmith[otel]>=0.6.3

{langgraph_api-0.14.0.dev10 → langgraph_api-0.15.0.dev1}/benchmark/README.md

@@ -47,6 +47,7 @@ The runner contains the actual logic each virtual user will execute during the b
 - `threads_search_metadata` - Validates thread metadata search/filter behavior.
 - `store` - Writes, reads, validates, and deletes a Store item with a configurable payload size.
 - `meta_workload` (randomly delegates to one of the others)
+- `delta_turns` - Keeps one thread per VU and adds a turn to it every iteration, so latency can be read against thread depth. Built for the delta-channel cells; see below.
 
 ## Profiles (`BENCHMARK_PROFILE`)
 
@@ -58,6 +59,7 @@ Profiles are quick ways to configure the benchmark graph for any run depending o
 - `stateless-parallel-medium` - Stateless high-fanout profile with medium checkpoint payloads.
 - `parallel-small` - Stateful high-fanout profile with small checkpoint payloads.
 - `parallel-medium` - Stateful high-fanout profile with medium checkpoint payloads.
+- `delta-turns` - Cheap turns for the delta-channel cells, so a VU reaches the depth where a `snapshot_frequency` of 1000 fires.
 
 Each profile defines:
 
@@ -113,6 +115,53 @@ make benchmark-charts
 make benchmark-clean
 ```
 
+## Delta-channel cells
+
+A `DeltaChannel` stores changes rather than the value, and rebuilds the value on read
+by replaying them. That moves cost from write to read, and the read cost grows with
+thread depth. `delta_turns` measures it: one thread per VU, one turn per iteration,
+`turn_duration` tagged by depth bucket.
+
+Run the cells one at a time and compare `turn_duration` by depth. Both sides get slower
+with depth for different reasons, the control by re-writing a growing value and delta by
+replaying more writes, so the deliverable is which curve is worse and where they cross.
+
+| Cell | Env |
+|---|---|
+| control | `GRAPH_ID=benchmark EXPECT_DELTA=false` |
+| delta, snapshot every 1000 | `GRAPH_ID=benchmark_delta` |
+| delta, snapshot every 50 | `GRAPH_ID=benchmark_delta_freq` |
+| migration | `GRAPH_ID=benchmark_delta MIGRATE_FROM_GRAPH_ID=benchmark MIGRATE_AFTER=200` |
+
+```bash
+BASE_URL=... BENCHMARK_TYPE=delta_turns BENCHMARK_PROFILE=delta-turns \
+  GRAPH_ID=benchmark_delta LOAD_SIZE=25 LEVELS=1 PLATEAU_DURATION=300 \
+  P95_RUN_DURATION=... AVERAGE_RUN_DURATION=... k6 run --system-tags='[]' ramp.js
+```
+
+Knobs beyond the common ones:
+
+- `GRAPH_ID` - graph under test (any runner; defaults to `benchmark`).
+- `EXPECT_DELTA` - whether `GRAPH_ID` is delta-backed. Default `true`.
+- `MIGRATE_FROM_GRAPH_ID` / `MIGRATE_AFTER` - run the first N turns on another graph, then
+  switch on the same thread.
+- `VERIFY_EVERY` - cold re-read cadence in turns. Default 50, `0` disables.
+- `DEPTH_BUCKET` - width of a depth bucket. Default 100.
+
+Two things to know before reading any result:
+
+- **Run at low `LOAD_SIZE`.** Depth and load fight each other: saturate the deployment and
+  turn time measures queueing, not reconstruction. Verify the control curve is flat before
+  trusting the delta one.
+- **`successful_runs` will fail its threshold.** The count is derived from a duration table
+  that assumes the existing workload. Pass `P95_RUN_DURATION` and `AVERAGE_RUN_DURATION`,
+  and treat these cells as report-only until the numbers settle.
+
+The runner fails a turn rather than reporting a false pass when delta is not actually on:
+the `DeltaChannel` import is version-guarded, and its stub degrades to a plain channel.
+Storage savings, the reason the feature exists, are not measured here; that needs a query
+against the deployment database, which CI cannot reach.
+
 ## Outputs
 
 - Ramp:

{langgraph_api-0.14.0.dev10 → langgraph_api-0.15.0.dev1}/benchmark/benchmark-runners/benchmark_profiles.ts

@@ -68,6 +68,26 @@ export const BENCHMARK_PROFILES: Record<string, BenchmarkProfile> = {
       burst_size: 0,
     },
   },
+  // Delta-channel cells: cheap turns, so a VU reaches the depth where a
+  // snapshot_frequency of 1000 finally fires. Run these at a low LOAD_SIZE;
+  // saturation turns the measurement into queue time.
+  'delta-turns': {
+    resumable: false,
+    runMode: 'stateful',
+    context: {
+      delay: 0,
+      delay_jitter_ratio: 0,
+      expand: 1,
+      steps: 1,
+      checkpoint_size: 256,
+      llm_enabled: false,
+      stream_size: 0,
+      chunk_size: 1,
+      burst_mode: false,
+      burst_probability: 0,
+      burst_size: 0,
+    },
+  },
   'streaming-long': {
     resumable: true,
     runMode: 'stateful',

{langgraph_api-0.14.0.dev10 → langgraph_api-0.15.0.dev1}/benchmark/benchmark-runners/benchmarks.ts

@@ -8,6 +8,7 @@ import { ThreadRunsMetadataSearch } from './thread_runs_metadata_search.js';
 import { ThreadsSearchMetadata } from './threads_search_metadata.js';
 import { Store } from './store.js';
 import { MetaWorkload } from './meta_workload.js';
+import { DeltaTurns } from './delta_turns.js';
 import type { BenchmarkRunner } from './benchmark-runner.js';
 
 export class Benchmarks {
@@ -33,6 +34,8 @@ export class Benchmarks {
         return Store;
       case MetaWorkload.toString():
         return MetaWorkload;
+      case DeltaTurns.toString():
+        return DeltaTurns;
       default:
         throw new Error(`Unknown benchmark type: ${type}`);
     }

langgraph_api-0.15.0.dev1/benchmark/benchmark-runners/delta-turns-lib.test.js

@@ -0,0 +1,169 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  planTurn,
+  deltaGuardFailure,
+  stateDrift,
+  unusableCheckpointSize,
+} from './dist/delta-turns-lib.js';
+import { getBenchmarkProfile } from './dist/benchmark_profiles.js';
+
+const BASE = {
+  graphId: 'benchmark_delta',
+  migrateFromGraphId: '',
+  migrateAfter: 0,
+  expectDelta: true,
+  verifyEvery: 50,
+  bucketSize: 100,
+};
+
+const MIGRATING = {
+  ...BASE,
+  migrateFromGraphId: 'benchmark',
+  migrateAfter: 200,
+};
+
+test('steps equals the turn number, because steps is cumulative on a reused thread', () => {
+  assert.equal(planTurn(1, BASE).steps, 1);
+  assert.equal(planTurn(937, BASE).steps, 937);
+});
+
+test('without migration every turn uses the same graph', () => {
+  assert.equal(planTurn(1, BASE).graphId, 'benchmark_delta');
+  assert.equal(planTurn(500, BASE).graphId, 'benchmark_delta');
+  assert.equal(planTurn(500, BASE).expectDelta, true);
+});
+
+test('migration switches graph and delta expectation at the boundary', () => {
+  assert.equal(planTurn(200, MIGRATING).graphId, 'benchmark');
+  assert.equal(planTurn(200, MIGRATING).expectDelta, false);
+  assert.equal(planTurn(201, MIGRATING).graphId, 'benchmark_delta');
+  assert.equal(planTurn(201, MIGRATING).expectDelta, true);
+});
+
+test('migrateAfter is ignored without a graph to migrate from', () => {
+  const plan = planTurn(1, { ...BASE, migrateAfter: 200 });
+  assert.equal(plan.graphId, 'benchmark_delta');
+  assert.equal(plan.expectDelta, true);
+});
+
+test('the guard runs on turn 2, never on turn 1', () => {
+  assert.equal(planTurn(1, BASE).guard, false);
+  assert.equal(planTurn(2, BASE).guard, true);
+  assert.equal(planTurn(3, BASE).guard, false);
+});
+
+test('migration guards again two turns after the switch', () => {
+  assert.equal(planTurn(201, MIGRATING).guard, false);
+  assert.equal(planTurn(202, MIGRATING).guard, true);
+});
+
+test('the guard never lands on a snapshot boundary, where absent counters are correct', () => {
+  const guarded = [];
+  for (let turn = 1; turn <= 1000; turn += 1) {
+    if (planTurn(turn, MIGRATING).guard) guarded.push(turn);
+  }
+  assert.deepEqual(guarded, [2, 202]);
+  for (const turn of guarded) {
+    assert.notEqual(turn % 50, 0);
+    assert.notEqual(turn % 1000, 0);
+  }
+});
+
+test('cold re-read runs on the configured cadence and can be disabled', () => {
+  assert.equal(planTurn(50, BASE).verify, true);
+  assert.equal(planTurn(51, BASE).verify, false);
+  assert.equal(planTurn(50, { ...BASE, verifyEvery: 0 }).verify, false);
+});
+
+test('depth buckets group turns and stay stable at the edges', () => {
+  assert.equal(planTurn(1, BASE).depthBucket, '1-100');
+  assert.equal(planTurn(100, BASE).depthBucket, '1-100');
+  assert.equal(planTurn(101, BASE).depthBucket, '101-200');
+  assert.equal(planTurn(7, { ...BASE, bucketSize: 0 }).depthBucket, '7');
+});
+
+test('a delta graph without counters is a silent fallback to a plain channel', () => {
+  assert.equal(deltaGuardFailure({ counters_since_delta_snapshot: { c: [3, 3] } }, true), null);
+  assert.equal(deltaGuardFailure({ step: 4 }, true), 'delta_off_on_delta_graph');
+  assert.equal(deltaGuardFailure(null, true), 'delta_off_on_delta_graph');
+});
+
+test('empty counters read as absent, matching Pregel filtering out zero entries', () => {
+  assert.equal(deltaGuardFailure({ counters_since_delta_snapshot: {} }, true), 'delta_off_on_delta_graph');
+  assert.equal(deltaGuardFailure({ counters_since_delta_snapshot: {} }, false), null);
+});
+
+test('counters on the control graph mean the wrong graph is under test', () => {
+  assert.equal(deltaGuardFailure({ counters_since_delta_snapshot: { c: [1, 1] } }, false), 'delta_on_on_plain_graph');
+  assert.equal(deltaGuardFailure({ step: 4 }, false), null);
+});
+
+test('matching live and stored state is no drift', () => {
+  const values = { counter: 12, cumulative_checkpoint: 'abcd' };
+  assert.equal(stateDrift(values, { ...values }, 'cumulative_checkpoint'), null);
+});
+
+test('a lost write shows up as a shorter stored channel', () => {
+  const live = { counter: 12, cumulative_checkpoint: 'abcd' };
+  const cold = { counter: 12, cumulative_checkpoint: 'ab' };
+  assert.equal(stateDrift(live, cold, 'cumulative_checkpoint'), 'channel_drift:abcd!=ab');
+});
+
+test('same-length channel corruption is still drift', () => {
+  const live = { counter: 12, cumulative_checkpoint: 'abcd' };
+  const cold = { counter: 12, cumulative_checkpoint: 'abce' };
+  assert.equal(stateDrift(live, cold, 'cumulative_checkpoint'), 'channel_drift:abcd!=abce');
+});
+
+test('a counter that does not survive the read is drift', () => {
+  const live = { counter: 12, cumulative_checkpoint: 'ab' };
+  const cold = { counter: 11, cumulative_checkpoint: 'ab' };
+  assert.equal(stateDrift(live, cold, 'cumulative_checkpoint'), 'counter_drift:12!=11');
+});
+
+test('missing values are reported rather than passing silently', () => {
+  assert.equal(stateDrift(null, {}, 'cumulative_checkpoint'), 'run_values_missing');
+  assert.equal(stateDrift({}, null, 'cumulative_checkpoint'), 'cold_values_missing');
+});
+
+test('a non-string channel encoding is still comparable', () => {
+  const live = { counter: 1, cumulative_checkpoint: { data: [1, 2, 3] } };
+  const cold = { counter: 1, cumulative_checkpoint: { data: [1, 2] } };
+  assert.equal(
+    stateDrift(live, cold, 'cumulative_checkpoint'),
+    'channel_drift:{"data":[1,2,3]}!={"data":[1,2]}'
+  );
+});
+
+test('the first turn of a migration runs on the graph being migrated from', () => {
+  assert.equal(planTurn(1, MIGRATING).graphId, 'benchmark');
+  assert.equal(planTurn(1, MIGRATING).expectDelta, false);
+});
+
+test('adjacent guard turns do not collapse when the switch is early', () => {
+  const early = { ...MIGRATING, migrateAfter: 1 };
+  assert.equal(planTurn(2, early).guard, true);
+  assert.equal(planTurn(3, early).guard, true);
+  assert.equal(planTurn(2, early).expectDelta, true);
+});
+
+test('a channel absent from both sides compares equal, which is why checkpoint_size must be > 0', () => {
+  const drift = stateDrift({ counter: 1 }, { counter: 1 }, 'cumulative_checkpoint');
+  assert.equal(drift, null);
+});
+
+test('a checkpoint size of zero makes the run meaningless and is rejected', () => {
+  assert.equal(unusableCheckpointSize(0), true);
+  assert.equal(unusableCheckpointSize(undefined), true);
+  assert.equal(unusableCheckpointSize(-1), true);
+  assert.equal(unusableCheckpointSize(256), false);
+});
+
+test('the delta-turns profile is wired and writes a growing channel', () => {
+  const { profile } = getBenchmarkProfile('delta-turns');
+  assert.equal(profile.runMode, 'stateful');
+  assert.equal(unusableCheckpointSize(profile.context.checkpoint_size), false);
+  assert.equal(profile.context.delay, 0);
+  assert.equal(profile.context.steps, 1);
+});

langgraph_api-0.15.0.dev1/benchmark/benchmark-runners/delta-turns-lib.ts

@@ -0,0 +1,102 @@
+// No k6 imports here, so `node --test` can import the compiled output.
+
+export interface DeltaTurnsOptions {
+  graphId: string;
+  /** Drives the first `migrateAfter` turns. Empty disables migration. */
+  migrateFromGraphId: string;
+  migrateAfter: number;
+  /** Whether `graphId` is delta-backed. */
+  expectDelta: boolean;
+  /** Cold re-read cadence, in turns. 0 disables. */
+  verifyEvery: number;
+  bucketSize: number;
+}
+
+export interface TurnPlan {
+  graphId: string;
+  /** Cumulative on a reused thread, so turn N asks for N. */
+  steps: number;
+  expectDelta: boolean;
+  guard: boolean;
+  verify: boolean;
+  depthBucket: string;
+}
+
+const DELTA_COUNTERS_KEY = 'counters_since_delta_snapshot';
+
+/** At size 0 the thread deepens but the channel stays empty, measuring nothing. */
+export function unusableCheckpointSize(checkpointSize: number | undefined): boolean {
+  return !(typeof checkpointSize === 'number' && checkpointSize > 0);
+}
+
+export function planTurn(turn: number, options: DeltaTurnsOptions): TurnPlan {
+  const migrating = options.migrateFromGraphId !== '' && options.migrateAfter > 0;
+  const beforeSwitch = migrating && turn <= options.migrateAfter;
+  return {
+    graphId: beforeSwitch ? options.migrateFromGraphId : options.graphId,
+    steps: turn,
+    expectDelta: beforeSwitch ? false : options.expectDelta,
+    guard: isGuardTurn(turn, options, migrating),
+    verify: options.verifyEvery > 0 && turn % options.verifyEvery === 0,
+    depthBucket: depthBucket(turn, options.bucketSize),
+  };
+}
+
+/**
+ * Turn 1 has no counters yet, and on a snapshot point Pregel drops the counters
+ * entry, so its absence there is correct rather than a fallback.
+ */
+function isGuardTurn(turn: number, options: DeltaTurnsOptions, migrating: boolean): boolean {
+  if (turn === 2) return true;
+  return migrating && turn === options.migrateAfter + 2;
+}
+
+function depthBucket(turn: number, bucketSize: number): string {
+  if (bucketSize <= 0) return String(turn);
+  const floor = Math.floor((turn - 1) / bucketSize) * bucketSize;
+  return `${floor + 1}-${floor + bucketSize}`;
+}
+
+/**
+ * The delta import is version-guarded and its stub degrades to a plain channel,
+ * so without this a delta cell can silently measure the control graph.
+ */
+export function deltaGuardFailure(metadata: unknown, expectDelta: boolean): string | null {
+  const counters =
+    metadata != null && typeof metadata === 'object'
+      ? (metadata as Record<string, unknown>)[DELTA_COUNTERS_KEY]
+      : undefined;
+  const present = counters != null && Object.keys(counters as object).length > 0;
+  if (expectDelta && !present) return 'delta_off_on_delta_graph';
+  if (!expectDelta && present) return 'delta_on_on_plain_graph';
+  return null;
+}
+
+/**
+ * Delta bugs return the right answer live and lose it on the next read, so the
+ * run's own output is the reference and the stored value is under test.
+ */
+export function stateDrift(
+  runValues: unknown,
+  coldValues: unknown,
+  channel: string
+): string | null {
+  if (runValues == null || typeof runValues !== 'object') return 'run_values_missing';
+  if (coldValues == null || typeof coldValues !== 'object') return 'cold_values_missing';
+  const live = runValues as Record<string, unknown>;
+  const cold = coldValues as Record<string, unknown>;
+
+  if (live.counter !== cold.counter) {
+    return `counter_drift:${String(live.counter)}!=${String(cold.counter)}`;
+  }
+  const liveEnc = encodeChannel(live[channel]);
+  const coldEnc = encodeChannel(cold[channel]);
+  if (liveEnc !== coldEnc) return `channel_drift:${liveEnc}!=${coldEnc}`;
+  return null;
+}
+
+/** Bytes arrive as a string, other channels as objects. */
+function encodeChannel(value: unknown): string {
+  if (value == null) return '';
+  return typeof value === 'string' ? value : JSON.stringify(value);
+}

langgraph_api-0.15.0.dev1/benchmark/benchmark-runners/delta_turns.ts

@@ -0,0 +1,169 @@
+import { BenchmarkRunner } from './benchmark-runner.js';
+import type { ErrorMetrics } from './benchmark-runner.js';
+import { check } from 'k6';
+import http from 'k6/http';
+import { Trend } from 'k6/metrics';
+import type { BenchmarkResult, BenchmarkGraphOptions, HttpResponse } from './types.js';
+import { addResponse, okResult, failResult } from './types.js';
+import { classifyError, recordError } from './classify-error.js';
+import { logFailure } from './log-failure.js';
+import {
+  planTurn,
+  deltaGuardFailure,
+  stateDrift,
+  unusableCheckpointSize,
+} from './delta-turns-lib.js';
+import type { DeltaTurnsOptions, TurnPlan } from './delta-turns-lib.js';
+
+const CHANNEL = 'cumulative_checkpoint';
+
+/** Tagged by depth: VUs ramp in, so clock time is not thread length. */
+const turnDuration = new Trend('turn_duration', true);
+
+const TURN_CONFIG: Omit<DeltaTurnsOptions, 'graphId'> = {
+  migrateFromGraphId: __ENV.MIGRATE_FROM_GRAPH_ID || '',
+  migrateAfter: parseInt(__ENV.MIGRATE_AFTER || '0', 10),
+  expectDelta: (__ENV.EXPECT_DELTA || 'true') === 'true',
+  verifyEvery: parseInt(__ENV.VERIFY_EVERY || '50', 10),
+  bucketSize: parseInt(__ENV.DEPTH_BUCKET || '100', 10),
+};
+
+// Each k6 VU runs this module in its own context, so these are per VU.
+let threadId: string | null = null;
+let turn = 0;
+
+interface DeltaTurnsData {
+  rawResponse: ReturnType<typeof http.post>;
+  plan: TurnPlan;
+  guardFailure: string | null;
+  drift: string | null;
+}
+
+export class DeltaTurns extends BenchmarkRunner {
+  static run(
+    baseUrl: string,
+    requestParams: Record<string, unknown>,
+    benchmarkGraphOptions: BenchmarkGraphOptions
+  ): BenchmarkResult<DeltaTurnsData> {
+    const responses: Record<string, HttpResponse> = {};
+
+    if (unusableCheckpointSize(benchmarkGraphOptions.context.checkpoint_size)) {
+      return failResult('checkpoint_size', responses) as BenchmarkResult<DeltaTurnsData>;
+    }
+
+    if (threadId === null) {
+      const thread = http.post(`${baseUrl}/threads`, '{}', requestParams);
+      addResponse(responses, 'create_thread', thread);
+      if (thread.status !== 200) {
+        return failResult('create_thread', responses) as BenchmarkResult<DeltaTurnsData>;
+      }
+      threadId = (thread.json() as { thread_id: string }).thread_id;
+      turn = 0;
+    }
+
+    turn += 1;
+    const plan = planTurn(turn, { ...TURN_CONFIG, graphId: benchmarkGraphOptions.graph_id });
+    const payload = JSON.stringify({
+      assistant_id: plan.graphId,
+      input: {},
+      context: { ...benchmarkGraphOptions.context, steps: plan.steps },
+      config: { recursion_limit: plan.steps + 2 },
+    });
+
+    const startedAt = Date.now();
+    const response = http.post(
+      `${baseUrl}/threads/${threadId}/runs/wait`,
+      payload,
+      requestParams
+    );
+    turnDuration.add(Date.now() - startedAt, { depth: plan.depthBucket });
+    addResponse(responses, 'wait', response);
+
+    let guardFailure: string | null = null;
+    let drift: string | null = null;
+    // A failed body is not state, and comparing against it would report drift
+    // on top of the failure that caused it.
+    if (response.status === 200 && (plan.guard || plan.verify)) {
+      const state = http.get(`${baseUrl}/threads/${threadId}/state`, requestParams);
+      addResponse(responses, 'state', state);
+      const body = state.status === 200 ? safeJson(state.body) : null;
+      if (body === null) {
+        guardFailure = plan.guard ? 'state_unreadable' : guardFailure;
+        drift = plan.verify ? 'state_unreadable' : drift;
+      } else {
+        if (plan.guard) {
+          guardFailure = deltaGuardFailure(body.metadata, plan.expectDelta);
+        }
+        if (plan.verify) {
+          // `/runs/wait` returns the state values themselves; `/state` nests them.
+          drift = stateDrift(safeJson(response.body), body.values, CHANNEL);
+        }
+      }
+    }
+
+    return okResult(responses, { rawResponse: response, plan, guardFailure, drift });
+  }
+
+  static validate(
+    result: BenchmarkResult<DeltaTurnsData>,
+    errorMetrics: ErrorMetrics
+  ): boolean {
+    const res = result.data?.rawResponse;
+    const plan = result.data?.plan;
+    const json = res?.status === 200 ? safeJson(res.body) : null;
+    let success = false;
+
+    try {
+      success = check(result, {
+        'Run completed successfully': () => (res?.status ?? 0) === 200,
+        'Response contains valid JSON': () => json != null,
+        'Response does not contain __error__': () => json?.__error__ === undefined,
+        'Run advanced the thread by one turn': () =>
+          json == null || plan == null || json.counter === plan.steps,
+        'Delta storage is as expected': () => result.data?.guardFailure == null,
+        'Cold re-read matches the run': () => result.data?.drift == null,
+      });
+    } catch (error) {
+      console.log(`Unknown error checking result: ${(error as Error).message}`);
+    }
+
+    if (!success) {
+      const detail = [
+        plan ? `turn=${plan.steps} graph=${plan.graphId}` : '',
+        res ? `status=${res.status}` : '',
+        result.data?.guardFailure ? `guard=${result.data.guardFailure}` : '',
+        result.data?.drift ? `drift=${result.data.drift}` : '',
+      ]
+        .filter(Boolean)
+        .join(' ');
+      logFailure(DeltaTurns.toString(), result, { extra: detail });
+      recordError(
+        classifyError({
+          response: res ?? result.responses?.create_thread ?? null,
+          hasApiError: json?.__error__ !== undefined,
+          missingMessage: result.data?.drift != null || result.data?.guardFailure != null,
+        }),
+        errorMetrics
+      );
+      // The thread is now at an unknown depth, so later turns would be tagged
+      // with a depth they do not have.
+      threadId = null;
+    }
+    return success;
+  }
+
+  static toString(): string {
+    return 'delta_turns';
+  }
+}
+
+/** k6 returns a null body on a connection failure. */
+function safeJson(body: string | null | ArrayBuffer): Record<string, any> | null {
+  if (typeof body !== 'string') return null;
+  try {
+    const parsed = JSON.parse(body);
+    return parsed != null && typeof parsed === 'object' ? parsed : null;
+  } catch {
+    return null;
+  }
+}

{langgraph_api-0.14.0.dev10 → langgraph_api-0.15.0.dev1}/benchmark/ramp.js

@@ -123,7 +123,7 @@ export let options = {
 const runner = Benchmarks.getRunner(BENCHMARK_TYPE);
 
 const benchmarkGraphOptions = {
-  graph_id: "benchmark",
+  graph_id: __ENV.GRAPH_ID || "benchmark",
   input: {},
   context: EFFECTIVE_CONTEXT,
   stateful: STATEFUL,

langgraph_api-0.15.0.dev1/langgraph_api/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.15.0.dev1"

{langgraph_api-0.14.0.dev10 → langgraph_api-0.15.0.dev1}/langgraph_api/queue_entrypoint.py

@@ -75,7 +75,6 @@ async def health_and_metrics_server():
     from langgraph_api.api.meta import METRICS_FORMATS, meta_pool_stats  # noqa: PLC0415
 
     port = int(os.getenv("PORT", "8080"))
-    # Not in public docs: LANGGRAPH_SERVER_HOST is internal
     # Empty means every interface: asyncio then opens one socket per address
     # family, so the server answers on IPv4 and IPv6.
     host = normalize_host(os.getenv("LANGGRAPH_SERVER_HOST", ""))

{langgraph_api-0.14.0.dev10 → langgraph_api-0.15.0.dev1}/pyproject.toml

@@ -39,7 +39,7 @@ dependencies = [
     "cryptography>=50.0.0",
     "langgraph-sdk>=0.3.5",
     "cloudpickle>=3.0.0",
-    "langgraph-runtime-inmem>=0.34.0.dev0,<0.35.0.dev0",
+    "langgraph-runtime-inmem>=0.35.0.dev0,<0.36.0.dev0",
     "truststore>=0.1",
     "protobuf>=6.32.1,<7.0.0",
     "grpcio>=1.81.0,<1.82.0",

langgraph_api-0.14.0.dev10/langgraph_api/__init__.py

@@ -1 +0,0 @@
-__version__ = "0.14.0.dev10"