refactor(api): enhance APISearchRequest model with improved structure and documentation

- Reorganize fields with clear section comments (Basic inputs, Cube scoping, Search mode, etc.)
- Add comprehensive field descriptions for better API documentation
- Add new 'filter' field for structured filter conditions with support for logical operators, comparisons, and string operations
- Add 'pref_top_k' and 'include_preference' fields for preference memory handling
- Mark 'mem_cube_id' as deprecated, recommend 'readable_cube_ids' for multi-cube search
- Make 'user_id' required field (was optional)
- Add validation constraints (e.g., top_k >= 1)
- Improve backward compatibility notes and internal field descriptions
- Add 'threshold' field for internal similarity threshold control

Author: CaralHsi

src/memos/api/product_models.py

@@ -1,7 +1,7 @@
 import os
 import uuid
 
-from typing import Generic, Literal, TypeVar
+from typing import Any, Generic, Literal, TypeVar
 
 from pydantic import BaseModel, Field
 
@@ -175,25 +175,117 @@ class SearchRequest(BaseRequest):
 class APISearchRequest(BaseRequest):
     """Request model for searching memories."""
 
-    query: str = Field(..., description="Search query")
-    user_id: str = Field(None, description="User ID")
-    mem_cube_id: str | None = Field(None, description="Cube ID to search in")
+    # ==== Basic inputs ====
+    query: str = Field(
+        ...,
+        description=("User search query"),
+    )
+    user_id: str = Field(..., description="User ID")
+
+    # ==== Cube scoping ====
+    mem_cube_id: str | None = Field(
+        None,
+        description=(
+            "(Deprecated) Single cube ID to search in. "
+            "Prefer `readable_cube_ids` for multi-cube search."
+        ),
+    )
     readable_cube_ids: list[str] | None = Field(
-        None, description="List of cube IDs user can read for multi-cube search"
+        None,
+        description=(
+            "List of cube IDs that are readable for this request. "
+            "Required for algorithm-facing API; optional for developer-facing API."
+        ),
     )
+
+    # ==== Search mode ====
     mode: SearchMode = Field(
-        os.getenv("SEARCH_MODE", SearchMode.FAST), description="search mode: fast, fine, or mixture"
+        os.getenv("SEARCH_MODE", SearchMode.FAST),
+        description="Search mode: FAST, FINE, or MIXTURE.",
     )
-    internet_search: bool = Field(False, description="Whether to use internet search")
-    moscube: bool = Field(False, description="Whether to use MemOSCube")
-    top_k: int = Field(10, description="Number of results to return")
-    chat_history: list[MessageDict] | None = Field(None, description="Chat history")
-    session_id: str | None = Field(None, description="Session ID for soft-filtering memories")
+
+    session_id: str | None = Field(
+        None,
+        description=(
+            "Session ID used as a soft signal to prioritize more relevant memories. "
+            "Only used for weighting, not as a hard filter."
+        ),
+    )
+
+    # ==== Result control ====
+    top_k: int = Field(
+        10,
+        ge=1,
+        description="Number of textual memories to retrieve (top-K). Default: 10.",
+    )
+
+    pref_top_k: int = Field(
+        6,
+        ge=0,
+        description="Number of preference memories to retrieve (top-K). Default: 6.",
+    )
+
+    include_preference: bool = Field(
+        True,
+        description=(
+            "Whether to retrieve preference memories along with general memories. "
+            "If enabled, the system will automatically recall user preferences "
+            "relevant to the query. Default: True."
+        ),
+    )
+
+    # ==== Filter conditions ====
+    filter: dict[str, Any] | None = Field(
+        None,
+        description=(
+            "Structured filter conditions for searching memories. "
+            "Supports logical operators: AND, OR, NOT; "
+            "comparison: E (==), NE (!=), GT (>), LT (<), GTE (>=), LTE (<=); "
+            "arithmetic: +, -, *, /, %, **; "
+            "set: IN, CONTAINS, ICONTAINS; "
+            "string: LIKE. "
+            "This nested dict will be converted into an internal expression tree."
+        ),
+    )
+
+    # ==== Extended capabilities ====
+    internet_search: bool = Field(
+        False,
+        description=(
+            "Whether to enable internet search in addition to memory search. "
+            "Primarily used by internal algorithms. Default: False."
+        ),
+    )
+
+    # Inner user, not supported in API yet
+    threshold: float | None = Field(
+        None,
+        description=(
+            "Internal similarity threshold for searching plaintext memories. "
+            "If None, default thresholds will be applied."
+        ),
+    )
+
+    # ==== Context ====
+    chat_history: list[MessageDict] | None = Field(
+        None,
+        description=(
+            "Historical chat messages used internally by algorithms. "
+            "If None, internal stored history may be used; "
+            "if provided (even an empty list), this value will be used as-is."
+        ),
+    )
+
+    # ==== Backward compatibility ====
+    moscube: bool = Field(
+        False,
+        description="(Deprecated / internal) Whether to use legacy MemOSCube path.",
+    )
+
     operation: list[PermissionDict] | None = Field(
-        None, description="operation ids for multi cubes"
+        None,
+        description="(Internal) Operation definitions for multi-cube read permissions.",
     )
-    include_preference: bool = Field(True, description="Whether to handle preference memory")
-    pref_top_k: int = Field(6, description="Number of preference results to return")
 
 
 class APIADDRequest(BaseRequest):