lingxigraph 2.0.1__py3-none-any.whl

lingxigraph/__init__.py

@@ -0,0 +1,187 @@
+"""Public API for the LingxiGraph runtime."""
+
+from .cache import AsyncCache, BaseCache, InMemoryCache
+from .channels import EphemeralValue, Topic
+from .checkpoint import (
+    AsyncCheckpointer,
+    AsyncPostgresSaver,
+    Checkpoint,
+    Checkpointer,
+    CheckpointTuple,
+    InMemorySaver,
+    PendingWrite,
+    PostgresSaver,
+    SqliteSaver,
+)
+from .constants import END, START
+from .errors import (
+    BudgetExceededError,
+    ConcurrentRunError,
+    EmptyInputError,
+    GraphCancelledError,
+    GraphInterrupt,
+    GraphRecursionError,
+    GraphTimeoutError,
+    GraphValidationError,
+    IdempotencyConflictError,
+    InvalidUpdateError,
+    LingxiGraphError,
+    PersistenceError,
+)
+from .events import Event, EventKind
+from .func import entrypoint, task
+from .graph import CompiledGraph, CompiledStateGraph, EdgeInfo, GraphInfo, NodeInfo, StateGraph
+from .messages import (
+    REMOVE_ALL_MESSAGES,
+    AIMessage,
+    AIMessageChunk,
+    AnyMessage,
+    HumanMessage,
+    MessagesState,
+    RemoveMessage,
+    SystemMessage,
+    ToolCall,
+    ToolCallChunk,
+    ToolMessage,
+    add_messages,
+    merge_chunks,
+)
+from .models import ChatModel, StreamingChatModel
+from .prebuilt import AgentState, create_agent, create_react_agent
+from .runtime import (
+    CancellationToken,
+    ExecutionBudget,
+    Runtime,
+    get_config,
+    get_runtime,
+    get_store,
+    get_stream_writer,
+)
+from .serialization import JsonSerializer, SerializationError, Serializer
+from .store import (
+    AsyncPostgresStore,
+    AsyncStore,
+    BaseStore,
+    Embedder,
+    InMemoryStore,
+    Item,
+    PostgresStore,
+    StoreOperation,
+)
+from .tools import ToolNode, ToolSpec, tool, tools_condition, validate_json_schema
+from .types import (
+    CachePolicy,
+    Command,
+    CommandScope,
+    Durability,
+    Interrupt,
+    MultitaskStrategy,
+    RetryPolicy,
+    RunConfig,
+    RunStatus,
+    Send,
+    StateSnapshot,
+    StreamWriter,
+    SubgraphPersistence,
+    TaskSnapshot,
+    interrupt,
+)
+from .version import __version__
+
+__all__ = [
+    "__version__",
+    "AsyncCache",
+    "AsyncCheckpointer",
+    "AsyncPostgresSaver",
+    "AsyncPostgresStore",
+    "AsyncStore",
+    "AIMessage",
+    "AIMessageChunk",
+    "AgentState",
+    "AnyMessage",
+    "BaseCache",
+    "BaseStore",
+    "BudgetExceededError",
+    "CachePolicy",
+    "CancellationToken",
+    "Checkpoint",
+    "Checkpointer",
+    "CheckpointTuple",
+    "ChatModel",
+    "Command",
+    "CommandScope",
+    "CompiledGraph",
+    "CompiledStateGraph",
+    "ConcurrentRunError",
+    "Durability",
+    "EdgeInfo",
+    "Embedder",
+    "ExecutionBudget",
+    "END",
+    "EmptyInputError",
+    "EphemeralValue",
+    "Event",
+    "EventKind",
+    "GraphCancelledError",
+    "GraphInterrupt",
+    "GraphRecursionError",
+    "GraphTimeoutError",
+    "GraphValidationError",
+    "GraphInfo",
+    "HumanMessage",
+    "IdempotencyConflictError",
+    "InMemoryCache",
+    "InMemorySaver",
+    "InMemoryStore",
+    "Interrupt",
+    "InvalidUpdateError",
+    "Item",
+    "JsonSerializer",
+    "LingxiGraphError",
+    "MultitaskStrategy",
+    "MessagesState",
+    "PendingWrite",
+    "NodeInfo",
+    "PersistenceError",
+    "PostgresSaver",
+    "PostgresStore",
+    "RetryPolicy",
+    "RunConfig",
+    "RunStatus",
+    "REMOVE_ALL_MESSAGES",
+    "RemoveMessage",
+    "Runtime",
+    "START",
+    "Send",
+    "SerializationError",
+    "Serializer",
+    "SqliteSaver",
+    "StateGraph",
+    "StateSnapshot",
+    "StreamWriter",
+    "StreamingChatModel",
+    "StoreOperation",
+    "SubgraphPersistence",
+    "SystemMessage",
+    "TaskSnapshot",
+    "ToolCall",
+    "ToolCallChunk",
+    "ToolMessage",
+    "ToolNode",
+    "ToolSpec",
+    "Topic",
+    "add_messages",
+    "create_agent",
+    "create_react_agent",
+    "entrypoint",
+    "get_config",
+    "get_runtime",
+    "get_store",
+    "get_stream_writer",
+    "interrupt",
+    "merge_chunks",
+    "tool",
+    "tools_condition",
+    "validate_json_schema",
+    "task",
+]

lingxigraph/__main__.py

@@ -0,0 +1,6 @@
+"""Enable ``python -m lingxigraph`` as an alias for the console entry point."""
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

lingxigraph/cache.py

@@ -0,0 +1,84 @@
+"""Provider-neutral cache protocol and in-memory implementation."""
+
+from __future__ import annotations
+
+import asyncio
+import copy
+import time
+from dataclasses import dataclass
+from threading import RLock
+from typing import Any, Protocol, runtime_checkable
+
+
+@dataclass(frozen=True, slots=True)
+class CacheEntry:
+    value: Any
+    expires_at: float | None = None
+
+
+@runtime_checkable
+class BaseCache(Protocol):
+    def get(self, key: str) -> Any | None: ...
+
+    def set(self, key: str, value: Any, *, ttl: float | None = None) -> None: ...
+
+    def delete(self, key: str) -> None: ...
+
+    def clear(self, *, namespace: str | None = None) -> None: ...
+
+
+@runtime_checkable
+class AsyncCache(Protocol):
+    async def aget(self, key: str) -> Any | None: ...
+
+    async def aset(self, key: str, value: Any, *, ttl: float | None = None) -> None: ...
+
+    async def adelete(self, key: str) -> None: ...
+
+
+class InMemoryCache:
+    """Thread-safe TTL cache intended for tests and embedded deployments."""
+
+    def __init__(self) -> None:
+        self._items: dict[str, CacheEntry] = {}
+        self._lock = RLock()
+
+    def get(self, key: str) -> Any | None:
+        with self._lock:
+            entry = self._items.get(key)
+            if entry is None:
+                return None
+            if entry.expires_at is not None and entry.expires_at <= time.monotonic():
+                self._items.pop(key, None)
+                return None
+            return copy.deepcopy(entry.value)
+
+    def set(self, key: str, value: Any, *, ttl: float | None = None) -> None:
+        expires_at = time.monotonic() + ttl if ttl is not None else None
+        with self._lock:
+            self._items[key] = CacheEntry(copy.deepcopy(value), expires_at)
+
+    def delete(self, key: str) -> None:
+        with self._lock:
+            self._items.pop(key, None)
+
+    def clear(self, *, namespace: str | None = None) -> None:
+        with self._lock:
+            if namespace is None:
+                self._items.clear()
+                return
+            prefix = f"{namespace}:"
+            for key in [item for item in self._items if item.startswith(prefix)]:
+                self._items.pop(key, None)
+
+    async def aget(self, key: str) -> Any | None:
+        return await asyncio.to_thread(self.get, key)
+
+    async def aset(self, key: str, value: Any, *, ttl: float | None = None) -> None:
+        await asyncio.to_thread(self.set, key, value, ttl=ttl)
+
+    async def adelete(self, key: str) -> None:
+        await asyncio.to_thread(self.delete, key)
+
+
+__all__ = ["AsyncCache", "BaseCache", "CacheEntry", "InMemoryCache"]

lingxigraph/cache_redis.py

@@ -0,0 +1,66 @@
+"""Optional Redis-backed node cache."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+from .serialization import JsonSerializer
+
+
+class RedisCache:
+    """Async-first Redis cache with strict JSON payloads and namespace clearing."""
+
+    def __init__(
+        self,
+        url: str = "redis://localhost:6379/0",
+        *,
+        prefix: str = "lingxigraph:cache",
+        serializer: JsonSerializer | None = None,
+    ) -> None:
+        try:
+            from redis.asyncio import Redis
+        except ImportError as exc:  # pragma: no cover - optional dependency
+            raise RuntimeError("install lingxigraph[redis] to use RedisCache") from exc
+        self._redis = Redis.from_url(url)
+        self._prefix = prefix.rstrip(":")
+        self._serializer = serializer or JsonSerializer()
+
+    def _key(self, key: str) -> str:
+        return f"{self._prefix}:{key}"
+
+    async def aget(self, key: str) -> Any | None:
+        payload = await self._redis.get(self._key(key))
+        return None if payload is None else self._serializer.loads(payload)
+
+    async def aset(self, key: str, value: Any, *, ttl: float | None = None) -> None:
+        milliseconds = max(1, int(ttl * 1000)) if ttl is not None else None
+        await self._redis.set(
+            self._key(key), self._serializer.dumps(value), px=milliseconds
+        )
+
+    async def adelete(self, key: str) -> None:
+        await self._redis.delete(self._key(key))
+
+    async def aclear(self, *, namespace: str | None = None) -> None:
+        pattern = self._key(f"{namespace}:*" if namespace else "*")
+        async for key in self._redis.scan_iter(match=pattern, count=500):
+            await self._redis.delete(key)
+
+    def get(self, key: str) -> Any | None:
+        return asyncio.run(self.aget(key))
+
+    def set(self, key: str, value: Any, *, ttl: float | None = None) -> None:
+        asyncio.run(self.aset(key, value, ttl=ttl))
+
+    def delete(self, key: str) -> None:
+        asyncio.run(self.adelete(key))
+
+    def clear(self, *, namespace: str | None = None) -> None:
+        asyncio.run(self.aclear(namespace=namespace))
+
+    async def close(self) -> None:
+        await self._redis.aclose()
+
+
+__all__ = ["RedisCache"]

lingxigraph/channels.py

@@ -0,0 +1,190 @@
+"""State channels and reducer discovery for ``TypedDict`` schemas."""
+
+from __future__ import annotations
+
+import copy
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from typing import Annotated, Any, get_args, get_origin, get_type_hints
+
+from .errors import InvalidUpdateError
+
+Reducer = Callable[[Any, Any], Any]
+
+
+@dataclass(frozen=True, slots=True)
+class ReplaceValue:
+    """Internal write wrapper that overwrites a channel instead of reducing.
+
+    Subgraph nodes return their final channel values wrapped in this marker:
+    the child already merged the parent's seed value, so folding the result
+    through the reducer again would double-count it.
+    """
+
+    value: Any
+
+
+@dataclass(frozen=True, slots=True)
+class LastValue:
+    """A channel that accepts at most one write per superstep."""
+
+    value_type: Any = Any
+
+    def merge(self, current: Any, writes: list[Any], *, key: str) -> Any:
+        if len(writes) > 1:
+            raise InvalidUpdateError(
+                f"state key {key!r} received {len(writes)} writes in one superstep; "
+                "declare an Annotated reducer to merge concurrent writes"
+            )
+        if not writes:
+            return current
+        write = writes[0]
+        if isinstance(write, ReplaceValue):
+            write = write.value
+        return copy.deepcopy(write)
+
+
+@dataclass(frozen=True, slots=True)
+class BinaryOperatorAggregate:
+    """A channel that folds writes through a binary reducer."""
+
+    value_type: Any
+    operator: Reducer
+
+    def merge(self, current: Any, writes: list[Any], *, key: str) -> Any:
+        del key
+        if not writes:
+            return current
+        result = _MISSING if current is _MISSING else copy.deepcopy(current)
+        for value in writes:
+            if isinstance(value, ReplaceValue):
+                result = copy.deepcopy(value.value)
+            elif result is _MISSING:
+                result = copy.deepcopy(value)
+            else:
+                result = self.operator(result, copy.deepcopy(value))
+        return result
+
+
+@dataclass(frozen=True, slots=True)
+class Topic:
+    """A multi-value channel that optionally accumulates across supersteps."""
+
+    value_type: Any = Any
+    accumulate: bool = False
+
+    def merge(self, current: Any, writes: list[Any], *, key: str) -> Any:
+        del key
+        values: list[Any] = []
+        if self.accumulate and current is not _MISSING:
+            values.extend(copy.deepcopy(list(current)))
+        for write in writes:
+            if isinstance(write, ReplaceValue):
+                values = copy.deepcopy(list(write.value))
+            elif isinstance(write, (list, tuple)):
+                values.extend(copy.deepcopy(list(write)))
+            else:
+                values.append(copy.deepcopy(write))
+        return values
+
+
+@dataclass(frozen=True, slots=True)
+class EphemeralValue:
+    """A last-value channel cleared when a superstep does not write it."""
+
+    value_type: Any = Any
+
+    def merge(self, current: Any, writes: list[Any], *, key: str) -> Any:
+        if len(writes) > 1:
+            raise InvalidUpdateError(
+                f"ephemeral state key {key!r} received {len(writes)} writes in one superstep"
+            )
+        if not writes:
+            return _CLEAR
+        write = writes[0]
+        return copy.deepcopy(write.value if isinstance(write, ReplaceValue) else write)
+
+
+Channel = LastValue | BinaryOperatorAggregate | Topic | EphemeralValue
+_MISSING = object()
+_CLEAR = object()
+
+
+def extract_channels(schema: type) -> dict[str, Channel]:
+    """Build channels from a ``TypedDict``-style annotated schema."""
+
+    model_fields = getattr(schema, "model_fields", None)
+    if isinstance(model_fields, Mapping):
+        hints = {
+            name: getattr(field, "annotation", Any)
+            for name, field in model_fields.items()
+        }
+    else:
+        try:
+            hints = get_type_hints(schema, include_extras=True)
+        except (NameError, TypeError) as exc:
+            raise InvalidUpdateError(f"cannot inspect state schema {schema!r}: {exc}") from exc
+    if not hints:
+        raise InvalidUpdateError("state schema must declare at least one annotated key")
+
+    channels: dict[str, Channel] = {}
+    for key, hint in hints.items():
+        if get_origin(hint) is Annotated:
+            args = get_args(hint)
+            value_type, metadata = args[0], args[1:]
+            channel = next((item for item in metadata if isinstance(item, (LastValue, BinaryOperatorAggregate, Topic, EphemeralValue))), None)
+            if channel is not None:
+                channels[key] = channel
+                continue
+            reducer = next((item for item in metadata if callable(item)), None)
+            channels[key] = (
+                BinaryOperatorAggregate(value_type, reducer)
+                if reducer is not None
+                else LastValue(value_type)
+            )
+        else:
+            channels[key] = LastValue(hint)
+    return channels
+
+
+def merge_updates(
+    state: Mapping[str, Any],
+    updates: list[tuple[str, Mapping[str, Any]]],
+    channels: Mapping[str, Channel],
+) -> dict[str, Any]:
+    """Merge node updates deterministically in the supplied task order."""
+
+    writes: dict[str, list[Any]] = {key: [] for key in channels}
+    for node, update in updates:
+        if not isinstance(update, Mapping):
+            raise InvalidUpdateError(
+                f"node {node!r} returned {type(update).__name__}; expected dict or Command"
+            )
+        unknown = set(update) - set(channels)
+        if unknown:
+            names = ", ".join(sorted(unknown))
+            raise InvalidUpdateError(f"node {node!r} wrote unknown state key(s): {names}")
+        for key, value in update.items():
+            writes[key].append(value)
+
+    merged = copy.deepcopy(dict(state))
+    for key, channel in channels.items():
+        current = merged.get(key, _MISSING)
+        value = channel.merge(current, writes[key], key=key)
+        if value is _CLEAR:
+            merged.pop(key, None)
+        elif value is not _MISSING:
+            merged[key] = value
+    return merged
+
+
+__all__ = [
+    "BinaryOperatorAggregate",
+    "Channel",
+    "LastValue",
+    "EphemeralValue",
+    "ReplaceValue",
+    "Topic",
+    "extract_channels",
+    "merge_updates",
+]

lingxigraph/checkpoint/__init__.py

@@ -0,0 +1,115 @@
+"""Checkpoint protocol and persisted value types."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Iterable, Mapping
+from dataclasses import dataclass, field
+from typing import Any, Protocol, runtime_checkable
+
+from ..types import Interrupt, Send, TaskSnapshot
+
+
+@dataclass(frozen=True, slots=True)
+class PendingWrite:
+    """One durable task result written before its superstep commits."""
+
+    checkpoint_id: str
+    task_id: str
+    index: int
+    values: Mapping[str, Any]
+    task_path: tuple[str, ...] = ()
+    goto: tuple[str | Send, ...] = ()
+    error: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class Checkpoint:
+    id: str
+    ts: str
+    step: int
+    channel_values: Mapping[str, Any]
+    next: tuple[str, ...]
+    pending_sends: tuple[Send, ...] = ()
+    pending_interrupts: tuple[Interrupt, ...] = ()
+    parent_id: str | None = None
+    namespace: tuple[str, ...] = ()
+    run_id: str | None = None
+    channel_versions: Mapping[str, int] = field(default_factory=dict)
+    tasks: tuple[TaskSnapshot, ...] = ()
+    schema_version: int = 2
+
+
+@dataclass(frozen=True, slots=True)
+class CheckpointTuple:
+    config: Mapping[str, Any]
+    checkpoint: Checkpoint
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+
+
+@runtime_checkable
+class Checkpointer(Protocol):
+    def put(
+        self,
+        config: Mapping[str, Any],
+        checkpoint: Checkpoint,
+        metadata: Mapping[str, Any],
+    ) -> Mapping[str, Any]: ...
+
+    def get_tuple(self, config: Mapping[str, Any]) -> CheckpointTuple | None: ...
+
+    def list(self, config: Mapping[str, Any]) -> Iterable[CheckpointTuple]: ...
+
+    def put_writes(
+        self,
+        config: Mapping[str, Any],
+        checkpoint_id: str,
+        writes: Iterable[PendingWrite],
+    ) -> None: ...
+
+    def get_writes(
+        self, config: Mapping[str, Any], checkpoint_id: str
+    ) -> Iterable[PendingWrite]: ...
+
+    def delete_thread(self, config: Mapping[str, Any]) -> None: ...
+
+
+@runtime_checkable
+class AsyncCheckpointer(Protocol):
+    async def aput(
+        self,
+        config: Mapping[str, Any],
+        checkpoint: Checkpoint,
+        metadata: Mapping[str, Any],
+    ) -> Mapping[str, Any]: ...
+
+    async def aget_tuple(self, config: Mapping[str, Any]) -> CheckpointTuple | None: ...
+
+    def alist(self, config: Mapping[str, Any]) -> AsyncIterator[CheckpointTuple]: ...
+
+    async def aput_writes(
+        self,
+        config: Mapping[str, Any],
+        checkpoint_id: str,
+        writes: Iterable[PendingWrite],
+    ) -> None: ...
+
+    async def aget_writes(
+        self, config: Mapping[str, Any], checkpoint_id: str
+    ) -> Iterable[PendingWrite]: ...
+
+
+from .memory import InMemorySaver
+from .postgres import AsyncPostgresSaver, PostgresSaver
+from .sqlite import SqliteSaver
+
+__all__ = [
+    "AsyncCheckpointer",
+    "Checkpoint",
+    "Checkpointer",
+    "CheckpointTuple",
+    "InMemorySaver",
+    "PendingWrite",
+    "PostgresSaver",
+    "AsyncPostgresSaver",
+    "SqliteSaver",
+]