From ea0aebaa2e09131b5ed20b032b34a8919550690f Mon Sep 17 00:00:00 2001
From: "Parker J. Rule" <pjrule@users.noreply.github.com>
Date: Thu, 25 Sep 2025 15:58:35 -0400
Subject: [PATCH] chore(sdk-py): refine FilterType, add subset containment to
 $contains docs (#6200)

The `$contains` auth operator supports subset containment checks, but
this has previously been undocumented. This updates `FilterType` and its
associated docstring to reflect this support.
---
 libs/sdk-py/langgraph_sdk/auth/types.py | 26 ++++++++++++++++++++-----
 1 file changed, 21 insertions(+), 5 deletions(-)

diff --git a/libs/sdk-py/langgraph_sdk/auth/types.py b/libs/sdk-py/langgraph_sdk/auth/types.py
index 4a7912ea3..097af5a2a 100644
--- a/libs/sdk-py/langgraph_sdk/auth/types.py
+++ b/libs/sdk-py/langgraph_sdk/auth/types.py
@@ -58,7 +58,14 @@ Values:
 """
 
 FilterType = typing.Union[
-    dict[str, typing.Union[str, dict[typing.Literal["$eq", "$contains"], str]]],
+    dict[
+        str,
+        typing.Union[
+            str,
+            dict[typing.Literal["$eq", "$contains"], str],
+            dict[typing.Literal["$contains"], list[str]],
+        ],
+    ],
     dict[str, str],
 ]
 """Response type for authorization handlers.
@@ -66,24 +73,33 @@ FilterType = typing.Union[
 Supports exact matches and operators:
     - Exact match shorthand: {"field": "value"}
     - Exact match: {"field": {"$eq": "value"}}
-    - Contains: {"field": {"$contains": "value"}}
+    - Contains (membership): {"field": {"$contains": "value"}}
+    - Contains (subset containment): {"field": {"$contains": ["value1", "value2"]}}
+
+Subset containment is only supported by newer versions of the LangGraph dev server;
+install langgraph-runtime-inmem >= 0.14.1 to use this filter variant.
 
 ???+ example "Examples"
     Simple exact match filter for the resource owner:
     ```python
     filter = {"owner": "user-abcd123"}
     ```
-    
+
     Explicit version of the exact match filter:
     ```python
     filter = {"owner": {"$eq": "user-abcd123"}}
     ```
-    
-    Containment:
+ 
+    Containment (membership of a single element):
     ```python
     filter = {"participants": {"$contains": "user-abcd123"}}
     ```
 
+    Containment (subset containment; all values must be present, but order doesn't matter):
+    ```python
+    filter = {"participants": {"$contains": ["user-abcd123", "user-efgh456"]}}
+    ```
+
     Combining filters (treated as a logical `AND`):
     ```python
     filter = {"owner": "user-abcd123", "participants": {"$contains": "user-efgh456"}}