langgraph-api 0.4.1__py3-none-any.whl → 0.7.3__py3-none-any.whl

langgraph_api/schema.py

@@ -16,9 +16,19 @@ RunStatus = Literal["pending", "running", "error", "success", "timeout", "interr
 ThreadStatus = Literal["idle", "busy", "interrupted", "error"]
 
 StreamMode = Literal[
-    "values", "messages", "updates", "events", "debug", "tasks", "checkpoints", "custom"
+    "values",
+    "messages",
+    "updates",
+    "events",
+    "debug",
+    "tasks",
+    "checkpoints",
+    "custom",
+    "messages-tuple",
 ]
 
+ThreadStreamMode = Literal["lifecycle", "run_modes", "state_update"]
+
 MultitaskStrategy = Literal["reject", "rollback", "interrupt", "enqueue"]
 
 OnConflictBehavior = Literal["raise", "do_nothing"]
@@ -48,10 +58,16 @@ class Config(TypedDict, total=False):
     """
     Runtime values for attributes previously made configurable on this Runnable,
     or sub-Runnables, through .configurable_fields() or .configurable_alternatives().
-    Check .output_schema() for a description of the attributes that have been made 
+    Check .output_schema() for a description of the attributes that have been made
     configurable.
     """
 
+    __encryption_context__: dict[str, Any]
+    """
+    Internal: Encryption context for encryption/decryption operations.
+    Not exposed to users.
+    """
+
 
 class Checkpoint(TypedDict):
     thread_id: str
@@ -60,7 +76,7 @@ class Checkpoint(TypedDict):
     checkpoint_map: dict[str, Any] | None
 
 
-class Assistant(TypedDict):
+class Assistant(TypedDict, total=False):
     """Assistant model."""
 
     assistant_id: UUID
@@ -110,6 +126,17 @@ class DeprecatedInterrupt(TypedDict, total=False):
     """When the interrupt occurred, always "during"."""
 
 
+class ThreadTTLInfo(TypedDict, total=False):
+    """TTL information for a thread. Only present when ?include=ttl is passed."""
+
+    strategy: Literal["delete", "keep_latest"]
+    """The TTL strategy."""
+    ttl_minutes: float
+    """The TTL in minutes."""
+    expires_at: datetime
+    """When the thread will expire."""
+
+
 class Thread(TypedDict):
     thread_id: UUID
     """The ID of the thread."""
@@ -121,14 +148,14 @@ 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
     """The current state of the thread."""
     interrupts: dict[str, list[Interrupt]]
     """The current interrupts of the thread, a map of task_id to list of interrupts."""
+    ttl: NotRequired[ThreadTTLInfo]
+    """TTL information if set for this thread. Only present when ?include=ttl is passed."""
 
 
 class ThreadTask(TypedDict):
@@ -146,7 +173,7 @@ class ThreadState(TypedDict):
     next: Sequence[str]
     """The name of the node to execute in each task for this step."""
     checkpoint: Checkpoint
-    """The checkpoint keys. This object can be passed to the /threads and /runs 
+    """The checkpoint keys. This object can be passed to the /threads and /runs
     endpoints to resume execution or update state."""
     metadata: Fragment
     """Metadata for this state"""
@@ -174,6 +201,7 @@ class RunKwargs(TypedDict):
     subgraphs: bool
     resumable: bool
     checkpoint_during: bool
+    durability: str | None
 
 
 class Run(TypedDict):
@@ -217,6 +245,8 @@ class Cron(TypedDict):
     """The ID of the assistant."""
     thread_id: UUID | None
     """The ID of the thread."""
+    on_run_completed: NotRequired[Literal["delete", "keep"] | None]
+    """What to do with the thread after the run completes."""
     end_time: datetime | None
     """The end date to stop running the cron."""
     schedule: str
@@ -246,8 +276,9 @@ class ThreadUpdateResponse(TypedDict):
 class QueueStats(TypedDict):
     n_pending: int
     n_running: int
-    max_age_secs: datetime | None
-    med_age_secs: datetime | None
+    pending_runs_wait_time_max_secs: float | None
+    pending_runs_wait_time_med_secs: float | None
+    pending_unblocked_runs_wait_time_max_secs: float | None
 
 
 # Canonical field sets for select= validation and type aliases for ops
@@ -274,7 +305,6 @@ ThreadSelectField = Literal[
     "updated_at",
     "metadata",
     "config",
-    "context",
     "status",
     "values",
     "interrupts",
@@ -300,6 +330,7 @@ CronSelectField = Literal[
     "cron_id",
     "assistant_id",
     "thread_id",
+    "on_run_completed",
     "end_time",
     "schedule",
     "created_at",
@@ -308,6 +339,53 @@ CronSelectField = Literal[
     "payload",
     "next_run_date",
     "metadata",
-    "now",
 ]
 CRON_FIELDS: set[str] = set(CronSelectField.__args__)  # type: ignore[attr-defined]
+
+# Encryption field constants
+# These define which fields are encrypted for each model type.
+#
+# Note: Checkpoint encryption (checkpoint, metadata columns in checkpoints table, plus
+# blob data in checkpoint_blobs and checkpoint_writes) is handled directly by the
+# Checkpointer class in storage_postgres/langgraph_runtime_postgres/checkpoint.py.
+# The checkpointer uses encrypt_json_if_needed/decrypt_json_if_needed directly rather
+# than the field list pattern used by the API middleware. This is because checkpoints
+# are only accessed via the checkpointer's internal methods (aget_tuple, aput, etc.),
+# not through generic API CRUD operations.
+
+THREAD_ENCRYPTION_FIELDS = ["metadata", "config", "values", "interrupts", "error"]
+
+# kwargs is a nested blob - its subfields are decrypted automatically by the middleware
+RUN_ENCRYPTION_FIELDS = ["metadata", "kwargs"]
+
+ASSISTANT_ENCRYPTION_FIELDS = ["metadata", "config", "context"]
+
+# payload is a nested blob - its subfields are decrypted automatically by the middleware
+CRON_ENCRYPTION_FIELDS = ["metadata", "payload"]
+
+# Store encryption - only the value field contains user data
+STORE_ENCRYPTION_FIELDS = ["value"]
+
+# The middleware automatically decrypts these subfields when decrypting the parent field.
+# This is recursive: if a subfield is also in NESTED_ENCRYPTED_SUBFIELDS, its subfields
+# are decrypted too (e.g., run.kwargs.config.configurable).
+NESTED_ENCRYPTED_SUBFIELDS: dict[tuple[str, str], list[str]] = {
+    ("run", "kwargs"): ["input", "config", "context", "command"],
+    ("run", "config"): ["configurable", "metadata"],
+    ("cron", "payload"): ["metadata", "context", "input", "config"],
+    ("cron", "config"): ["configurable", "metadata"],
+    ("assistant", "config"): ["configurable"],
+}
+
+# Convenience alias for cron payload subfields.
+#
+# This is a reflection of an unfortunate asymmetry in cron's data model.
+#
+# The cron API requests have payload fields (metadata, input, config, context) at the
+# top level, but at rest they're nested inside the `payload` JSONB column (with
+# metadata also duplicated as a top-level column). This alias is used to encrypt
+# those fields in the flat request before storage.
+CRON_PAYLOAD_ENCRYPTION_SUBFIELDS = NESTED_ENCRYPTED_SUBFIELDS[("cron", "payload")]
+
+# Convenience alias for run kwargs subfields, used by the worker for decryption.
+RUN_KWARGS_ENCRYPTION_SUBFIELDS = NESTED_ENCRYPTED_SUBFIELDS[("run", "kwargs")]

langgraph_api/self_hosted_logs.py

@@ -0,0 +1,124 @@
+import logging
+import os
+from typing import cast
+
+import structlog
+from opentelemetry.exporter.otlp.proto.http._log_exporter import OTLPLogExporter
+from opentelemetry.sdk._logs import LoggerProvider, LoggingHandler
+from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
+from opentelemetry.sdk.resources import SERVICE_NAME, Resource
+from opentelemetry.util.types import Attributes
+
+from langgraph_api import config
+from langgraph_api.logging import OTLPFormatter
+
+logger = structlog.stdlib.get_logger(__name__)
+
+_logger_provider = None
+_customer_attributes = {}
+
+
+# see https://github.com/open-telemetry/opentelemetry-python/issues/3649 for why we need this
+class AttrFilteredLoggingHandler(LoggingHandler):
+    DROP_ATTRIBUTES = ("_logger",)
+
+    @staticmethod
+    def _get_attributes(record: logging.LogRecord) -> Attributes:
+        base_attributes = LoggingHandler._get_attributes(record)
+        attributes = {
+            k: v
+            for k, v in base_attributes.items()
+            if k not in AttrFilteredLoggingHandler.DROP_ATTRIBUTES
+        }
+        if _customer_attributes:
+            attributes.update(_customer_attributes)
+        return cast("Attributes", attributes)
+
+
+def initialize_self_hosted_logs() -> None:
+    global _logger_provider
+
+    if not config.LANGGRAPH_LOGS_ENABLED:
+        return
+
+    if not config.LANGGRAPH_LOGS_ENDPOINT:
+        raise RuntimeError(
+            "LANGGRAPH_LOGS_ENABLED is true but no LANGGRAPH_LOGS_ENDPOINT is configured"
+        )
+
+    # For now, this is only enabled for fully self-hosted customers
+    # We will need to update the otel collector auth model to support hybrid customers
+    if not config.LANGGRAPH_CLOUD_LICENSE_KEY:
+        logger.warning(
+            "Self-hosted logs require a license key, and do not work with hybrid deployments yet."
+        )
+        return
+
+    try:
+        resource_attributes = {
+            SERVICE_NAME: config.SELF_HOSTED_OBSERVABILITY_SERVICE_NAME,
+        }
+
+        if config.LANGGRAPH_CLOUD_LICENSE_KEY:
+            try:
+                from langgraph_license.validation import (
+                    CUSTOMER_ID,  # type: ignore[unresolved-import]
+                    CUSTOMER_NAME,  # type: ignore[unresolved-import]
+                )
+
+                if CUSTOMER_ID:
+                    _customer_attributes["customer_id"] = CUSTOMER_ID
+                if CUSTOMER_NAME:
+                    _customer_attributes["customer_name"] = CUSTOMER_NAME
+
+                # resolves to pod name in k8s, or container id in docker
+                instance_id = os.environ.get("HOSTNAME")
+                if instance_id:
+                    _customer_attributes["instance_id"] = instance_id
+            except ImportError:
+                pass
+            except Exception as e:
+                logger.warning("Failed to get customer info from license", exc_info=e)
+
+        if config.IS_QUEUE_ENTRYPOINT:
+            _customer_attributes["entrypoint"] = "queue"
+        elif config.IS_EXECUTOR_ENTRYPOINT:
+            _customer_attributes["entrypoint"] = "executor"
+        else:
+            _customer_attributes["entrypoint"] = "api"
+
+        _logger_provider = LoggerProvider(
+            resource=Resource.create(resource_attributes),
+        )
+        _logger_provider.add_log_record_processor(
+            BatchLogRecordProcessor(
+                OTLPLogExporter(
+                    endpoint=config.LANGGRAPH_LOGS_ENDPOINT,
+                    headers={
+                        "X-Langchain-License-Key": config.LANGGRAPH_CLOUD_LICENSE_KEY,
+                    },
+                )
+            )
+        )
+        handler = AttrFilteredLoggingHandler(logger_provider=_logger_provider)
+        handler.setFormatter(OTLPFormatter("%(message)s", None, "%"))
+        logging.getLogger().addHandler(handler)
+
+        logger.info(
+            "Self-hosted logs initialized successfully",
+            endpoint=config.LANGGRAPH_LOGS_ENDPOINT,
+        )
+    except Exception as e:
+        logger.exception("Failed to initialize self-hosted logs", exc_info=e)
+
+
+def shutdown_self_hosted_logs() -> None:
+    global _logger_provider
+
+    if _logger_provider:
+        try:
+            logger.info("Shutting down self-hosted logs")
+            _logger_provider.shutdown()
+            _logger_provider = None
+        except Exception as e:
+            logger.exception("Failed to shutdown self-hosted logs", exc_info=e)