langgraph-api 0.2.130__py3-none-any.whl → 0.2.134__py3-none-any.whl

langgraph_api/schema.py

@@ -1,8 +1,9 @@
 from collections.abc import Sequence
 from datetime import datetime
-from typing import Any, Literal, Optional, TypeAlias
+from typing import Any, Literal, NotRequired, Optional, TypeAlias
 from uuid import UUID
 
+from langchain_core.runnables.config import RunnableConfig
 from typing_extensions import TypedDict
 
 from langgraph_api.serde import Fragment
@@ -120,6 +121,8 @@ class Thread(TypedDict):
     """The thread metadata."""
     config: Fragment
     """The thread config."""
+    context: Fragment
+    """The thread context."""
     status: ThreadStatus
     """The status of the thread. One of 'idle', 'busy', 'interrupted', "error"."""
     values: Fragment
@@ -157,6 +160,22 @@ class ThreadState(TypedDict):
     """The interrupts for this state."""
 
 
+class RunKwargs(TypedDict):
+    config: RunnableConfig
+    context: dict[str, Any]
+    input: dict[str, Any] | None
+    command: dict[str, Any] | None
+    stream_mode: StreamMode
+    interrupt_before: Sequence[str] | str | None
+    interrupt_after: Sequence[str] | str | None
+    webhook: str | None
+    feedback_keys: Sequence[str] | None
+    temporary: bool
+    subgraphs: bool
+    resumable: bool
+    checkpoint_during: bool
+
+
 class Run(TypedDict):
     run_id: UUID
     """The ID of the run."""
@@ -172,7 +191,7 @@ class Run(TypedDict):
     """The status of the run. One of 'pending', 'error', 'success'."""
     metadata: Fragment
     """The run metadata."""
-    kwargs: Fragment
+    kwargs: RunKwargs
     """The run kwargs."""
     multitask_strategy: MultitaskStrategy
     """Strategy to handle concurrent runs on the same thread."""
@@ -206,14 +225,16 @@ class Cron(TypedDict):
     """The time the cron was created."""
     updated_at: datetime
     """The last time the cron was updated."""
-    user_id: UUID | None
-    """The ID of the user."""
+    user_id: str | None
+    """The ID of the user (string identity)."""
     payload: Fragment
     """The run payload to use for creating new run."""
     next_run_date: datetime
     """The next run date of the cron."""
     metadata: Fragment
     """The cron metadata."""
+    now: NotRequired[datetime]
+    """The current time (present in internal next() only)."""
 
 
 class ThreadUpdateResponse(TypedDict):
@@ -227,3 +248,66 @@ class QueueStats(TypedDict):
     n_running: int
     max_age_secs: datetime | None
     med_age_secs: datetime | None
+
+
+# Canonical field sets for select= validation and type aliases for ops
+
+# Assistant select fields (intentionally excludes 'context')
+AssistantSelectField = Literal[
+    "assistant_id",
+    "graph_id",
+    "name",
+    "description",
+    "config",
+    "context",
+    "created_at",
+    "updated_at",
+    "metadata",
+    "version",
+]
+ASSISTANT_FIELDS: set[str] = set(AssistantSelectField.__args__)  # type: ignore[attr-defined]
+
+# Thread select fields
+ThreadSelectField = Literal[
+    "thread_id",
+    "created_at",
+    "updated_at",
+    "metadata",
+    "config",
+    "context",
+    "status",
+    "values",
+    "interrupts",
+]
+THREAD_FIELDS: set[str] = set(ThreadSelectField.__args__)  # type: ignore[attr-defined]
+
+# Run select fields
+RunSelectField = Literal[
+    "run_id",
+    "thread_id",
+    "assistant_id",
+    "created_at",
+    "updated_at",
+    "status",
+    "metadata",
+    "kwargs",
+    "multitask_strategy",
+]
+RUN_FIELDS: set[str] = set(RunSelectField.__args__)  # type: ignore[attr-defined]
+
+# Cron select fields
+CronSelectField = Literal[
+    "cron_id",
+    "assistant_id",
+    "thread_id",
+    "end_time",
+    "schedule",
+    "created_at",
+    "updated_at",
+    "user_id",
+    "payload",
+    "next_run_date",
+    "metadata",
+    "now",
+]
+CRON_FIELDS: set[str] = set(CronSelectField.__args__)  # type: ignore[attr-defined]

langgraph_api/serde.py

@@ -1,4 +1,5 @@
 import asyncio
+import base64
 import re
 import uuid
 from base64 import b64encode
@@ -16,7 +17,7 @@ from ipaddress import (
 )
 from pathlib import Path
 from re import Pattern
-from typing import Any, NamedTuple
+from typing import Any, NamedTuple, cast
 from zoneinfo import ZoneInfo
 
 import cloudpickle
@@ -46,10 +47,14 @@ def decimal_encoder(dec_value: Decimal) -> int | float:
     >>> decimal_encoder(Decimal("1"))
     1
     """
-    if dec_value.as_tuple().exponent >= 0:
-        return int(dec_value)
-    else:
+    if (
+        # maps to float('nan') / float('inf') / float('-inf')
+        not dec_value.is_finite()
+        # or regular float
+        or cast(int, dec_value.as_tuple().exponent) < 0
+    ):
         return float(dec_value)
+    return int(dec_value)
 
 
 def default(obj):
@@ -142,7 +147,7 @@ def json_loads(content: bytes | Fragment | dict) -> Any:
         content = content.buf
     if isinstance(content, dict):
         return content
-    return orjson.loads(content)
+    return orjson.loads(cast(bytes, content))
 
 
 async def ajson_loads(content: bytes | Fragment) -> Any:
@@ -170,3 +175,25 @@ class Serializer(JsonPlusSerializer):
                 )
                 return None
         return super().loads_typed(data)
+
+
+mpack_keys = {"method", "value"}
+SERIALIZER = Serializer()
+
+
+# TODO: Make more performant (by removing)
+async def reserialize_message(message: bytes) -> bytes:
+    # Stream messages from golang runtime are a byte dict of StreamChunks.
+    loaded = await ajson_loads(message)
+    converted = {}
+    for k, v in loaded.items():
+        if isinstance(v, dict) and v.keys() == mpack_keys:
+            if v["method"] == "missing":
+                converted[k] = v["value"]  # oops
+            else:
+                converted[k] = SERIALIZER.loads_typed(
+                    (v["method"], base64.b64decode(v["value"]))
+                )
+        else:
+            converted[k] = v
+    return json_dumpb(converted)

langgraph_api/server.py

@@ -122,17 +122,19 @@ if user_router:
     # Merge routes
     app = user_router
 
-    meta_route_paths = [route.path for route in meta_routes]
+    meta_route_paths = [
+        getattr(route, "path", None) for route in meta_routes if hasattr(route, "path")
+    ]
     custom_route_paths = [
         route.path
         for route in user_router.router.routes
-        if route.path not in meta_route_paths
+        if hasattr(route, "path") and route.path not in meta_route_paths
     ]
     logger.info(f"Custom route paths: {custom_route_paths}")
 
     update_openapi_spec(app)
     for route in routes:
-        if route.path in ("/docs", "/openapi.json"):
+        if getattr(route, "path", None) in ("/docs", "/openapi.json"):
             # Our handlers for these are inclusive of the custom routes and default API ones
             # Don't let these be shadowed
             app.router.routes.insert(0, route)

langgraph_api/state.py

@@ -60,11 +60,11 @@ def patch_interrupt(
         return {"id": id, **interrupt.raw}
 
     if USE_NEW_INTERRUPTS:
-        interrupt = Interrupt(**interrupt) if isinstance(interrupt, dict) else interrupt
+        interrupt = Interrupt(**interrupt) if isinstance(interrupt, dict) else interrupt  # type: ignore[missing-argument]
 
         return {
-            "id": interrupt.id,
-            "value": interrupt.value,
+            "id": interrupt.id,  # type: ignore[unresolved-attribute]
+            "value": interrupt.value,  # type: ignore[unresolved-attribute]
         }
     else:
         if isinstance(interrupt, dict):
@@ -72,16 +72,16 @@ def patch_interrupt(
             # id is the new field we use for identification, also not supported on init for old versions
             interrupt.pop("interrupt_id", None)
             interrupt.pop("id", None)
-            interrupt = Interrupt(**interrupt)
+            interrupt = Interrupt(**interrupt)  # type: ignore[missing-argument]
 
         return {
             "id": interrupt.interrupt_id
             if hasattr(interrupt, "interrupt_id")
             else None,
-            "value": interrupt.value,
-            "resumable": interrupt.resumable,
-            "ns": interrupt.ns,
-            "when": interrupt.when,
+            "value": interrupt.value,  # type: ignore[unresolved-attribute]
+            "resumable": interrupt.resumable,  # type: ignore[unresolved-attribute]
+            "ns": interrupt.ns,  # type: ignore[unresolved-attribute]
+            "when": interrupt.when,  # type: ignore[unresolved-attribute]
         }
 
 

langgraph_api/store.py

@@ -93,7 +93,7 @@ def _load_store(store_path: str) -> Any:
             raise ValueError(f"Could not find store file: {path_name}")
         module = importlib.util.module_from_spec(modspec)
         sys.modules[module_name] = module
-        modspec.loader.exec_module(module)
+        modspec.loader.exec_module(module)  # type: ignore[possibly-unbound-attribute]
 
     else:
         path_name, function = store_path.rsplit(".", 1)

langgraph_api/stream.py

@@ -1,3 +1,4 @@
+import uuid
 from collections.abc import AsyncIterator, Callable
 from contextlib import AsyncExitStack, aclosing, asynccontextmanager
 from functools import lru_cache
@@ -93,21 +94,23 @@ def _preproces_debug_checkpoint_task(task: dict[str, Any]) -> dict[str, Any]:
     return task
 
 
-def _preprocess_debug_checkpoint(payload: CheckpointPayload | None) -> dict[str, Any]:
+def _preprocess_debug_checkpoint(
+    payload: CheckpointPayload | None,
+) -> dict[str, Any] | None:
     from langgraph_api.state import runnable_config_to_checkpoint
 
     if not payload:
         return None
 
-    payload["checkpoint"] = runnable_config_to_checkpoint(payload["config"])
-    payload["parent_checkpoint"] = runnable_config_to_checkpoint(
-        payload["parent_config"] if "parent_config" in payload else None
-    )
-
-    payload["tasks"] = [_preproces_debug_checkpoint_task(t) for t in payload["tasks"]]
-
     # TODO: deprecate the `config`` and `parent_config`` fields
-    return payload
+    return {
+        **payload,
+        "checkpoint": runnable_config_to_checkpoint(payload["config"]),
+        "parent_checkpoint": runnable_config_to_checkpoint(
+            payload["parent_config"] if "parent_config" in payload else None
+        ),
+        "tasks": [_preproces_debug_checkpoint_task(t) for t in payload["tasks"]],
+    }
 
 
 @asynccontextmanager
@@ -216,7 +219,7 @@ async def astream_state(
     if use_astream_events:
         async with (
             stack,
-            aclosing(
+            aclosing(  # type: ignore[invalid-argument-type]
                 graph.astream_events(
                     input,
                     config,
@@ -231,6 +234,7 @@ async def astream_state(
                 event = await wait_if_not_done(anext(stream, sentinel), done)
                 if event is sentinel:
                     break
+                event = cast(dict, event)
                 if event.get("tags") and "langsmith:hidden" in event["tags"]:
                     continue
                 if "messages" in stream_mode and isinstance(graph, BaseRemotePregel):
@@ -251,6 +255,7 @@ async def astream_state(
                     if mode == "debug":
                         if chunk["type"] == "checkpoint":
                             checkpoint = _preprocess_debug_checkpoint(chunk["payload"])
+                            chunk["payload"] = checkpoint
                             on_checkpoint(checkpoint)
                         elif chunk["type"] == "task_result":
                             on_task_result(chunk["payload"])
@@ -261,11 +266,14 @@ async def astream_state(
                             else:
                                 yield "messages", chunk
                         else:
-                            msg, meta = cast(
+                            msg_, meta = cast(
                                 tuple[BaseMessage | dict, dict[str, Any]], chunk
                             )
-                            if isinstance(msg, dict):
-                                msg = convert_to_messages([msg])[0]
+                            msg = (
+                                convert_to_messages([msg_])[0]
+                                if isinstance(msg_, dict)
+                                else cast(BaseMessage, msg_)
+                            )
                             if msg.id in messages:
                                 messages[msg.id] += msg
                             else:
@@ -323,14 +331,15 @@ async def astream_state(
                 if event is sentinel:
                     break
                 if subgraphs:
-                    ns, mode, chunk = event
+                    ns, mode, chunk = cast(tuple[str, str, dict[str, Any]], event)
                 else:
-                    mode, chunk = event
+                    mode, chunk = cast(tuple[str, dict[str, Any]], event)
                     ns = None
                 # --- begin shared logic with astream_events ---
                 if mode == "debug":
                     if chunk["type"] == "checkpoint":
                         checkpoint = _preprocess_debug_checkpoint(chunk["payload"])
+                        chunk["payload"] = checkpoint
                         on_checkpoint(checkpoint)
                     elif chunk["type"] == "task_result":
                         on_task_result(chunk["payload"])
@@ -341,11 +350,15 @@ async def astream_state(
                         else:
                             yield "messages", chunk
                     else:
-                        msg, meta = cast(
+                        msg_, meta = cast(
                             tuple[BaseMessage | dict, dict[str, Any]], chunk
                         )
-                        if isinstance(msg, dict):
-                            msg = convert_to_messages([msg])[0]
+                        msg = (
+                            convert_to_messages([msg_])[0]
+                            if isinstance(msg_, dict)
+                            else cast(BaseMessage, msg_)
+                        )
+
                         if msg.id in messages:
                             messages[msg.id] += msg
                         else:
@@ -399,7 +412,7 @@ async def astream_state(
 
 async def consume(
     stream: AnyStream,
-    run_id: str,
+    run_id: str | uuid.UUID,
     resumable: bool = False,
     stream_modes: set[StreamMode] | None = None,
 ) -> None:
@@ -408,7 +421,7 @@ async def consume(
         stream_modes.add("messages")
     stream_modes.add("metadata")
 
-    async with aclosing(stream):
+    async with aclosing(stream):  # type: ignore[invalid-argument-type]
         try:
             async for mode, payload in stream:
                 await Runs.Stream.publish(

langgraph_api/traceblock.py

@@ -19,4 +19,4 @@ def patch_requests():
                 raise RuntimeError(f"POST to {url} blocked by policy")
         return _orig(self, method, url, *a, **kw)
 
-    Session.request = _guard
+    Session.request = _guard  # type: ignore[invalid-assignment]

langgraph_api/utils/__init__.py

@@ -1,9 +1,9 @@
 import contextvars
 import uuid
-from collections.abc import AsyncGenerator, AsyncIterator
+from collections.abc import AsyncIterator
 from contextlib import asynccontextmanager
 from datetime import datetime
-from typing import Any, Protocol, TypeAlias, TypeVar
+from typing import Any, Protocol, TypeAlias, TypeVar, cast
 
 import structlog
 from langgraph_sdk import Auth
@@ -12,6 +12,7 @@ from starlette.exceptions import HTTPException
 from starlette.schemas import BaseSchemaGenerator
 
 from langgraph_api.auth.custom import SimpleUser
+from langgraph_api.utils.uuids import uuid7
 
 logger = structlog.stdlib.get_logger(__name__)
 
@@ -32,7 +33,9 @@ async def with_user(
     yield
     if current is None:
         return
-    set_auth_ctx(current.user, AuthCredentials(scopes=current.permissions))
+    set_auth_ctx(
+        cast(BaseUser, current.user), AuthCredentials(scopes=current.permissions)
+    )
 
 
 def set_auth_ctx(
@@ -99,7 +102,7 @@ def validate_uuid(uuid_str: str, invalid_uuid_detail: str | None) -> uuid.UUID:
 
 
 def next_cron_date(schedule: str, base_time: datetime) -> datetime:
-    import croniter
+    import croniter  # type: ignore[unresolved-import]
 
     cron_iter = croniter.croniter(schedule, base_time)
     return cron_iter.get_next(datetime)
@@ -130,7 +133,7 @@ class SchemaGenerator(BaseSchemaGenerator):
 
 
 async def get_pagination_headers(
-    resource: AsyncGenerator[T],
+    resource: AsyncIterator[T],
     next_offset: int | None,
     offset: int,
 ) -> tuple[list[T], dict[str, str]]:
@@ -143,3 +146,35 @@ async def get_pagination_headers(
             "X-Pagination-Next": str(next_offset),
         }
     return resources, response_headers
+
+
+def validate_select_columns(
+    select: list[str] | None, allowed: set[str]
+) -> list[str] | None:
+    """Validate select columns against an allowed set.
+
+    Returns the input list (or None) if valid, otherwise raises HTTP 422.
+    """
+    if not select:
+        return None
+    invalid = [col for col in select if col not in allowed]
+    if invalid:
+        raise HTTPException(
+            status_code=422,
+            detail=f"Invalid select columns: {invalid}. Expected: {allowed}",
+        )
+    return select
+
+
+__all__ = [
+    "AsyncCursorProto",
+    "AsyncPipelineProto",
+    "AsyncConnectionProto",
+    "fetchone",
+    "validate_uuid",
+    "next_cron_date",
+    "SchemaGenerator",
+    "get_pagination_headers",
+    "uuid7",
+    "validate_select_columns",
+]

langgraph_api/utils/config.py

@@ -7,9 +7,10 @@ from collections import ChainMap
 from concurrent.futures import Executor
 from contextvars import copy_context
 from os import getenv
-from typing import Any, ParamSpec, TypeVar, cast
+from typing import Any, ParamSpec, TypeVar
 
 from langgraph.constants import CONF
+from typing_extensions import TypedDict
 
 if typing.TYPE_CHECKING:
     from langchain_core.runnables import RunnableConfig
@@ -19,7 +20,7 @@ try:
         var_child_runnable_config,
     )
 except ImportError:
-    var_child_runnable_config = None
+    var_child_runnable_config = None  # type: ignore[invalid-assignment]
 
 CONFIG_KEYS = [
     "tags",
@@ -52,6 +53,14 @@ def _is_not_empty(value: Any) -> bool:
         return value is not None
 
 
+class _Config(TypedDict):
+    tags: list[str]
+    metadata: ChainMap
+    callbacks: None
+    recursion_limit: int
+    configurable: dict[str, Any]
+
+
 def ensure_config(*configs: RunnableConfig | None) -> RunnableConfig:
     """Return a config with all keys, merging any provided configs.
 
@@ -61,7 +70,7 @@ def ensure_config(*configs: RunnableConfig | None) -> RunnableConfig:
     Returns:
         RunnableConfig: The merged and ensured config.
     """
-    empty = dict(
+    empty = _Config(
         tags=[],
         metadata=ChainMap(),
         callbacks=None,
@@ -84,7 +93,7 @@ def ensure_config(*configs: RunnableConfig | None) -> RunnableConfig:
         for k, v in config.items():
             if _is_not_empty(v) and k in CONFIG_KEYS:
                 if k == CONF:
-                    empty[k] = cast(dict, v).copy()
+                    empty[k] = v.copy()  # type: ignore
                 else:
                     empty[k] = v  # type: ignore[literal-required]
         for k, v in config.items():

langgraph_api/utils/future.py

@@ -167,7 +167,7 @@ def _ensure_future(
         elif EAGER_NOT_SUPPORTED or lazy:
             return loop.create_task(coro_or_future, name=name, context=context)
         else:
-            return asyncio.eager_task_factory(
+            return asyncio.eager_task_factory(  # type: ignore[unresolved-attribute]
                 loop, coro_or_future, name=name, context=context
             )
     except RuntimeError:

langgraph_api/utils/uuids.py

@@ -0,0 +1,87 @@
+import os
+import time
+from uuid import UUID, SafeUUID
+
+_last_timestamp_v7 = None
+_last_counter_v7 = 0  # 42-bit counter
+_RFC_4122_VERSION_7_FLAGS = (7 << 76) | (0x8000 << 48)
+
+
+def _uuid7_get_counter_and_tail():
+    rand = int.from_bytes(os.urandom(10))
+    # 42-bit counter with MSB set to 0
+    counter = (rand >> 32) & 0x1FF_FFFF_FFFF
+    # 32-bit random data
+    tail = rand & 0xFFFF_FFFF
+    return counter, tail
+
+
+def _from_int(value: int) -> UUID:
+    uid = object.__new__(UUID)
+    object.__setattr__(uid, "int", value)
+    object.__setattr__(uid, "is_safe", SafeUUID.unknown)
+    return uid
+
+
+def uuid7():
+    """Generate a UUID from a Unix timestamp in milliseconds and random bits.
+
+    UUIDv7 objects feature monotonicity within a millisecond.
+    """
+    # --- 48 ---   -- 4 --   --- 12 ---   -- 2 --   --- 30 ---   - 32 -
+    # unix_ts_ms | version | counter_hi | variant | counter_lo | random
+    #
+    # 'counter = counter_hi | counter_lo' is a 42-bit counter constructed
+    # with Method 1 of RFC 9562, §6.2, and its MSB is set to 0.
+    #
+    # 'random' is a 32-bit random value regenerated for every new UUID.
+    #
+    # If multiple UUIDs are generated within the same millisecond, the LSB
+    # of 'counter' is incremented by 1. When overflowing, the timestamp is
+    # advanced and the counter is reset to a random 42-bit integer with MSB
+    # set to 0.
+
+    global _last_timestamp_v7
+    global _last_counter_v7
+
+    nanoseconds = time.time_ns()
+    timestamp_ms = nanoseconds // 1_000_000
+
+    if _last_timestamp_v7 is None or timestamp_ms > _last_timestamp_v7:
+        counter, tail = _uuid7_get_counter_and_tail()
+    else:
+        if timestamp_ms < _last_timestamp_v7:
+            timestamp_ms = _last_timestamp_v7 + 1
+        # advance the 42-bit counter
+        counter = _last_counter_v7 + 1
+        if counter > 0x3FF_FFFF_FFFF:
+            # advance the 48-bit timestamp
+            timestamp_ms += 1
+            counter, tail = _uuid7_get_counter_and_tail()
+        else:
+            # 32-bit random data
+            tail = int.from_bytes(os.urandom(4))
+
+    unix_ts_ms = timestamp_ms & 0xFFFF_FFFF_FFFF
+    counter_msbs = counter >> 30
+    # keep 12 counter's MSBs and clear variant bits
+    counter_hi = counter_msbs & 0x0FFF
+    # keep 30 counter's LSBs and clear version bits
+    counter_lo = counter & 0x3FFF_FFFF
+    # ensure that the tail is always a 32-bit integer (by construction,
+    # it is already the case, but future interfaces may allow the user
+    # to specify the random tail)
+    tail &= 0xFFFF_FFFF
+
+    int_uuid_7 = unix_ts_ms << 80
+    int_uuid_7 |= counter_hi << 64
+    int_uuid_7 |= counter_lo << 32
+    int_uuid_7 |= tail
+    # by construction, the variant and version bits are already cleared
+    int_uuid_7 |= _RFC_4122_VERSION_7_FLAGS
+    res = _from_int(int_uuid_7)
+
+    # defer global update until all computations are done
+    _last_timestamp_v7 = timestamp_ms
+    _last_counter_v7 = counter
+    return res

langgraph_api/validation.py

@@ -14,9 +14,15 @@ AssistantVersionsSearchRequest = jsonschema_rs.validator_for(
 AssistantSearchRequest = jsonschema_rs.validator_for(
     openapi["components"]["schemas"]["AssistantSearchRequest"]
 )
+AssistantCountRequest = jsonschema_rs.validator_for(
+    openapi["components"]["schemas"]["AssistantCountRequest"]
+)
 ThreadSearchRequest = jsonschema_rs.validator_for(
     openapi["components"]["schemas"]["ThreadSearchRequest"]
 )
+ThreadCountRequest = jsonschema_rs.validator_for(
+    openapi["components"]["schemas"]["ThreadCountRequest"]
+)
 AssistantCreate = jsonschema_rs.validator_for(
     openapi["components"]["schemas"]["AssistantCreate"]
 )
@@ -116,6 +122,9 @@ RunCreateStateful = jsonschema_rs.validator_for(
 RunsCancel = jsonschema_rs.validator_for(openapi["components"]["schemas"]["RunsCancel"])
 CronCreate = jsonschema_rs.validator_for(openapi["components"]["schemas"]["CronCreate"])
 CronSearch = jsonschema_rs.validator_for(openapi["components"]["schemas"]["CronSearch"])
+CronCountRequest = jsonschema_rs.validator_for(
+    openapi["components"]["schemas"]["CronCountRequest"]
+)
 
 
 # Stuff around storage/BaseStore API