docs: describe API search filter field

src/memos/api/product_models.py

@@ -478,18 +478,16 @@ class APISearchRequest(BaseRequest):
     )
 
     # ==== Filter conditions ====
-    # TODO: maybe add detailed description later
     filter: dict[str, Any] | None = Field(
         None,
-        description="""
-        Filter for the memory, example:
-        {
-            "`and` or `or`": [
-                {"id": "uuid-xxx"},
-                {"created_at": {"gt": "2024-01-01"}},
-            ]
-        }
-        """,
+        description=(
+            "Optional metadata filter applied to retrieved memories. "
+            "Use memory metadata fields such as id, created_at, user_id, or session_id. "
+            "Combine clauses with `and` / `or`, and use comparison operators such as "
+            "`gt`, `gte`, `lt`, `lte`, `eq`, or `ne` when supported by the backend. "
+            "Example: {'and': [{'session_id': 'session-1'}, "
+            "{'created_at': {'gt': '2024-01-01'}}]}."
+        ),
     )
 
     # ==== Extended capabilities ====

tests/api/test_product_model_descriptions.py

@@ -0,0 +1,42 @@
+import ast
+from pathlib import Path
+from typing import List
+
+
+PRODUCT_MODELS = Path(__file__).resolve().parents[2] / "src/memos/api/product_models.py"
+
+
+def _class_body(name: str) -> List[ast.stmt]:
+    module = ast.parse(PRODUCT_MODELS.read_text())
+    for node in module.body:
+        if isinstance(node, ast.ClassDef) and node.name == name:
+            return node.body
+    raise AssertionError(f"{name} class not found")
+
+
+def _field_description(class_name: str, field_name: str) -> str:
+    for node in _class_body(class_name):
+        if not isinstance(node, ast.AnnAssign) or not isinstance(node.target, ast.Name):
+            continue
+        if node.target.id != field_name:
+            continue
+        if not isinstance(node.value, ast.Call):
+            raise AssertionError(f"{class_name}.{field_name} is not declared with Field")
+        for keyword in node.value.keywords:
+            if keyword.arg == "description":
+                value = ast.literal_eval(keyword.value)
+                return value.strip()
+    raise AssertionError(f"{class_name}.{field_name} description not found")
+
+
+def test_api_search_filter_description_is_explicit():
+    source = PRODUCT_MODELS.read_text()
+
+    assert "TODO: maybe add detailed description later" not in source
+
+    description = _field_description("APISearchRequest", "filter")
+    assert "metadata fields" in description
+    assert "and" in description
+    assert "or" in description
+    assert "comparison operators" in description
+    assert "session_id" in description