up step

apps/schemas.py

@@ -6,6 +6,28 @@ from pydantic import BaseModel, Field, field_validator
 
 
 class AiUserCreate(BaseModel):
+    r"""Schema for creating a new AI user.
+
+    Validates user data for the POST /ai/admin/users endpoint.
+
+    Attributes:
+        id (str, optional): User UUID. Auto-generated if not provided.
+        name (str): User's full name. Required, 1-128 characters.
+        email (str): User's email address. Required, max 256 characters.
+            Must be a valid email format.
+        dob (date, optional): Date of birth in YYYY-MM-DD format.
+        gender (str, optional): User's gender, max 10 characters.
+
+    Example::
+
+        >>> user = AiUserCreate(
+        ...     name="John Doe",
+        ...     email="john@example.com",
+        ...     dob="1990-01-15",
+        ...     gender="male"
+        ... )
+    """
+
     id: Optional[str] = None
     name: str = Field(min_length=1, max_length=128)
     email: str = Field(..., max_length=256)
@@ -20,6 +42,31 @@ class AiUserCreate(BaseModel):
 
 
 class AiUserUpdate(BaseModel):
+    r"""Schema for updating an existing AI user.
+
+    Validates user data for the PUT /ai/admin/users/{UserID} endpoint.
+    All fields are optional for partial updates.
+
+    Attributes:
+        name (str, optional): User's full name, 1-128 characters.
+        email (str, optional): User's email address, max 256 characters.
+            Must be a valid email format if provided.
+        dob (date, optional): Date of birth in YYYY-MM-DD format.
+        gender (str, optional): User's gender, max 10 characters.
+
+    Example::
+
+        >>> # Partial update - only change name
+        >>> update = AiUserUpdate(name="Jane Doe")
+
+        >>> # Full update
+        >>> update = AiUserUpdate(
+        ...     name="Jane Doe",
+        ...     email="jane@example.com",
+        ...     gender="female"
+        ... )
+    """
+
     name: Optional[str] = Field(default=None, min_length=1, max_length=128)
     email: Optional[str] = Field(default=None, max_length=256)
     dob: Optional[date] = None
@@ -33,6 +80,36 @@ class AiUserUpdate(BaseModel):
 
 
 class AiUserFilter(BaseModel):
+    r"""Schema for filtering and paginating AI users.
+
+    Used for parsing query parameters in the GET /ai/admin/users endpoint.
+
+    Attributes:
+        q (str, optional): Search keyword for name and email fields.
+        name (str, optional): Filter by name (partial match).
+        email (str, optional): Filter by email (partial match).
+        gender (str, optional): Filter by gender (exact match).
+        dob_from (date, optional): Filter users with DOB on or after this date.
+        dob_to (date, optional): Filter users with DOB on or before this date.
+        created_from (str, optional): Filter users created on or after this datetime.
+        created_to (str, optional): Filter users created on or before this datetime.
+        page (int): Page number (0-indexed). Default: ``0``
+        size (int): Records per page, 1-200. Default: ``20``
+        sortby (str): Field to sort by. Default: ``"modified"``
+        asc (bool): Sort ascending if ``True``. Default: ``False``
+
+    Example::
+
+        >>> # Parse from query string
+        >>> filter = AiUserFilter(
+        ...     q="john",
+        ...     page=0,
+        ...     size=10,
+        ...     sortby="created",
+        ...     asc=True
+        ... )
+    """
+
     q: Optional[str] = None
     name: Optional[str] = None
     email: Optional[str] = None