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

tests/services/test_base_model_service.py

@@ -183,7 +183,7 @@ class FakeCache:
     def __init__(self, items):
         self.items = list(items)
 
-    async def get_sorted_data(self, sort_key, order):
+    async def get_sorted_data(self, sort_key, order, seed=None):
         if sort_key == "name":
             data = sorted(self.items, key=lambda x: x["model_name"].lower())
             if order == "desc":

tests/services/test_model_scanner.py

@@ -884,7 +884,7 @@ async def test_sync_cache_conditional_resort_skipped(tmp_path: Path, monkeypatch
         raw_data=[dict(entry)], folders=[], name_display_mode="model_name"
     )
     await scanner._cache.resort()
-    scanner._cache._last_sort = ("name", "asc")  # name sort is active
+    scanner._cache._last_sort = ("name", "asc", None)  # name sort is active
     scanner._tags_count = {"alpha": 1}
     scanner._hash_index.add_entry("abc123", "/m/a.safetensors")
 
@@ -935,7 +935,7 @@ async def test_sync_cache_conditional_resort_triggered(tmp_path: Path, monkeypat
         raw_data=[dict(entry)], folders=[], name_display_mode="model_name"
     )
     await scanner._cache.resort()
-    scanner._cache._last_sort = ("name", "asc")
+    scanner._cache._last_sort = ("name", "asc", None)
     scanner._tags_count = {"alpha": 1}
     scanner._hash_index.add_entry("abc123", "/m/a.safetensors")
 

tests/services/test_model_sort.py

@@ -0,0 +1,97 @@
+"""Tests for sort parsing and the seeded random sort mode."""
+
+import asyncio
+
+import pytest
+
+from py.services.model_cache import ModelCache
+from py.services.model_query import ModelCacheRepository, SortParams
+
+
+def _make_cache(items):
+    return ModelCache(
+        raw_data=[
+            {
+                "file_path": f"/models/{name}.safetensors",
+                "file_name": f"{name}.safetensors",
+                "model_name": name,
+                "folder": "",
+                "size": 100,
+                "modified": 0.0,
+            }
+            for name in items
+        ],
+        folders=[],
+    )
+
+
+class TestParseSort:
+    def test_random_with_seed(self):
+        params = ModelCacheRepository.parse_sort("random:abc123")
+        assert params == SortParams(key="random", order="asc", seed="abc123")
+
+    def test_random_without_seed(self):
+        params = ModelCacheRepository.parse_sort("random")
+        assert params == SortParams(key="random", order="asc", seed=None)
+
+    def test_random_empty_seed_falls_back_to_none(self):
+        params = ModelCacheRepository.parse_sort("random:")
+        assert params.seed is None
+
+    def test_regular_sorts_unaffected(self):
+        params = ModelCacheRepository.parse_sort("name:desc")
+        assert params == SortParams(key="name", order="desc", seed=None)
+
+
+class TestRandomShuffle:
+    @pytest.mark.asyncio
+    async def test_same_seed_yields_same_order(self):
+        cache = _make_cache(["a", "b", "c", "d", "e"])
+        await asyncio.sleep(0)  # allow background resort task to run
+
+        first = await cache.get_sorted_data("random", "asc", "seed1")
+        second = await cache.get_sorted_data("random", "asc", "seed1")
+
+        assert [item["model_name"] for item in first] == [
+            item["model_name"] for item in second
+        ]
+
+    @pytest.mark.asyncio
+    async def test_different_seeds_yield_different_orders(self):
+        cache = _make_cache([f"m{i}" for i in range(20)])
+        await asyncio.sleep(0)
+
+        first = await cache.get_sorted_data("random", "asc", "seed-a")
+        second = await cache.get_sorted_data("random", "asc", "seed-b")
+
+        assert [item["model_name"] for item in first] != [
+            item["model_name"] for item in second
+        ]
+
+    @pytest.mark.asyncio
+    async def test_shuffle_is_a_permutation(self):
+        cache = _make_cache(["a", "b", "c", "d", "e"])
+        await asyncio.sleep(0)
+
+        shuffled = await cache.get_sorted_data("random", "asc", "seed")
+
+        assert sorted(item["model_name"] for item in shuffled) == [
+            "a",
+            "b",
+            "c",
+            "d",
+            "e",
+        ]
+        assert len({item["file_path"] for item in shuffled}) == 5
+
+    @pytest.mark.asyncio
+    async def test_missing_seed_is_stable(self):
+        cache = _make_cache(["a", "b", "c", "d", "e"])
+        await asyncio.sleep(0)
+
+        first = await cache.get_sorted_data("random", "asc")
+        second = await cache.get_sorted_data("random", "asc")
+
+        assert [item["model_name"] for item in first] == [
+            item["model_name"] for item in second
+        ]