feat(ui): add seeded random sort option to model pages (#1049)

py/services/base_model_service.py

@@ -1,6 +1,7 @@
 from abc import ABC, abstractmethod
 import asyncio
 import re
+import random
 from typing import Any, Dict, List, Optional, Type, Union, TYPE_CHECKING
 import logging
 import os
@@ -390,6 +391,12 @@ class BaseModelService(ABC):
                 (item.get("model_name") or item.get("file_name") or "").lower(),
                 item.get("file_path", "").lower(),
             )
+        elif key_name == "random":
+            # Seeded random shuffle: same seed -> same order (stable pagination)
+            rng = random.Random(sort_params.seed or "random")
+            result = list(data)
+            rng.shuffle(result)
+            return result
         elif key_name == "size":
             key_fn = lambda item: (
                 int(item.get("size", 0) or 0),

py/services/model_cache.py

@@ -1,6 +1,7 @@
 import asyncio
 import time
 import logging
+import random
 
 logger = logging.getLogger(__name__)
 from typing import Any, Dict, List, Optional, Tuple
@@ -38,8 +39,8 @@ class ModelCache:
 
     def __post_init__(self):
         self._lock = asyncio.Lock()
-        # Cache for last sort: (sort_key, order) -> sorted list
-        self._last_sort: Tuple[str, str] = (None, None)
+        # Cache for last sort: (sort_key, order, seed) -> sorted list
+        self._last_sort: Tuple[Optional[str], str, Optional[str]] = (None, "asc", None)
         self._last_sorted_data: List[Dict] = []
         self._normalize_raw_data()
         self.name_display_mode = self._normalize_display_mode(self.name_display_mode)
@@ -203,9 +204,9 @@ class ModelCache:
     async def resort(self):
         """Resort cached data according to last sort mode if set"""
         async with self._lock:
-            if self._last_sort != (None, None):
-                sort_key, order = self._last_sort
-                sorted_data = self._sort_data(self.raw_data, sort_key, order)
+            if self._last_sort[0] is not None:
+                sort_key, order, seed = self._last_sort
+                sorted_data = self._sort_data(self.raw_data, sort_key, order, seed)
                 self._last_sorted_data = sorted_data
                 # Update folder list
             # else: do nothing
@@ -218,7 +219,7 @@ class ModelCache:
             self.folders = sorted(list(all_folders), key=lambda x: x.lower())
             self.rebuild_version_index()
 
-    def _sort_data(self, data: List[Dict], sort_key: str, order: str) -> List[Dict]:
+    def _sort_data(self, data: List[Dict], sort_key: str, order: str, seed: Optional[str] = None) -> List[Dict]:
         """Sort data by sort_key and order"""
         start_time = time.perf_counter()
         reverse = (order == 'desc')
@@ -265,6 +266,13 @@ class ModelCache:
                 ),
                 reverse=reverse
             )
+        elif sort_key == 'random':
+            # Random shuffle seeded for stable pagination: the same seed
+            # always yields the same order, so successive page requests
+            # stay consistent while browsing.
+            rng = random.Random(seed or 'random')
+            result = list(data)
+            rng.shuffle(result)
         elif sort_key == 'versions_count':
             # Pre-dedup sort: fall back to name sort.
             # Actual re-sort by version_count happens in get_paginated_data after dedup.
@@ -285,15 +293,16 @@ class ModelCache:
             logger.debug("ModelCache._sort_data(%s, %s) for %d items took %.3fs", sort_key, order, len(data), duration)
         return result
 
-    async def get_sorted_data(self, sort_key: str = 'name', order: str = 'asc') -> List[Dict]:
+    async def get_sorted_data(self, sort_key: str = 'name', order: str = 'asc', seed: Optional[str] = None) -> List[Dict]:
         """Get sorted data by sort_key and order, using cache if possible"""
         async with self._lock:
-            if (sort_key, order) == self._last_sort:
+            cache_key = (sort_key, order, seed)
+            if cache_key == self._last_sort:
                 return self._last_sorted_data
             
             start_time = time.perf_counter()
-            sorted_data = self._sort_data(self.raw_data, sort_key, order)
-            self._last_sort = (sort_key, order)
+            sorted_data = self._sort_data(self.raw_data, sort_key, order, seed)
+            self._last_sort = cache_key
             self._last_sorted_data = sorted_data
             
             duration = time.perf_counter() - start_time
@@ -313,8 +322,8 @@ class ModelCache:
             self.name_display_mode = normalized
 
             if self._last_sort[0] == 'name':
-                sort_key, order = self._last_sort
-                self._last_sorted_data = self._sort_data(self.raw_data, sort_key, order)
+                sort_key, order, seed = self._last_sort
+                self._last_sorted_data = self._sort_data(self.raw_data, sort_key, order, seed)
 
     async def update_preview_url(self, file_path: str, preview_url: str, preview_nsfw_level: int) -> bool:
         """Update preview_url for a specific model in all cached data

py/services/model_query.py

@@ -85,6 +85,7 @@ class SortParams:
 
     key: str
     order: str
+    seed: Optional[str] = None
 
 
 @dataclass(frozen=True)
@@ -116,7 +117,7 @@ class ModelCacheRepository:
     async def fetch_sorted(self, params: SortParams) -> List[Dict[str, Any]]:
         """Fetch cached data pre-sorted according to ``params``."""
         cache = await self.get_cache()
-        return await cache.get_sorted_data(params.key, params.order)
+        return await cache.get_sorted_data(params.key, params.order, params.seed)
 
     @staticmethod
     def parse_sort(sort_by: str) -> SortParams:
@@ -132,10 +133,17 @@ class ModelCacheRepository:
             sort_key = sort_by.strip().lower() or "name"
             order = "asc"
 
-        if order not in ("asc", "desc"):
+        seed = None
+        if sort_key == "random":
+            # Random sort: the portion after ':' is the shuffle seed.
+            # A stable seed keeps paginated requests consistent; order is
+            # meaningless for a random shuffle.
+            seed = order if order and order not in ("asc", "desc") else None
+            order = "asc"
+        elif order not in ("asc", "desc"):
             order = "asc"
 
-        return SortParams(key=sort_key, order=order)
+        return SortParams(key=sort_key, order=order, seed=seed)
 
 
 class ModelFilterSet:

py/services/model_scanner.py

@@ -1752,7 +1752,7 @@ class ModelScanner:
         # ---- Conditional resort (only when sort-key fields changed) ----
         need_resort = False
         _last = cache._last_sort
-        sort_key: Optional[str] = _last[0] if _last != (None, None) else None
+        sort_key: Optional[str] = _last[0] if _last[0] is not None else None
         if sort_key == "name":
             if (
                 old_model_name != desired_entry.get("model_name", "")