feat(seed): apply_seed helper that returns the seed actually used

server/seed.py

@@ -0,0 +1,41 @@
+"""Seed helper for reproducible Chatterbox generations.
+
+`apply_seed(seed)`:
+  - if `seed` is `None` or `< 0`, draw a fresh non-negative 31-bit int
+  - call torch / cuda / mps / pyrandom seeding APIs with the chosen seed
+  - return the seed that was actually used (so the endpoint can echo it back)
+
+Failures inside platform-specific seeding (e.g. mps not present) are
+swallowed — the helper is best-effort, not a contract for determinism
+across hardware.
+"""
+from __future__ import annotations
+
+import random
+from typing import Optional
+
+import torch
+
+
+def _maybe_seed_mps(seed: int) -> None:
+    mps = getattr(torch, "mps", None)
+    if mps is None:
+        return
+    fn = getattr(mps, "manual_seed", None)
+    if fn is None:
+        return
+    fn(seed)
+
+
+def apply_seed(seed: Optional[int]) -> int:
+    if seed is None or seed < 0:
+        seed = random.randint(0, 2**31 - 1)
+    torch.manual_seed(seed)
+    if torch.cuda.is_available():
+        torch.cuda.manual_seed_all(seed)
+    try:
+        _maybe_seed_mps(seed)
+    except Exception:
+        pass
+    random.seed(seed)
+    return seed

tests/test_seed.py

@@ -0,0 +1,42 @@
+import random as pyrandom
+from unittest.mock import patch
+
+from server.seed import apply_seed
+
+
+def test_apply_seed_returns_provided_value():
+    assert apply_seed(42) == 42
+    assert apply_seed(0) == 0
+
+
+def test_apply_seed_negative_draws_random():
+    s = apply_seed(-1)
+    assert isinstance(s, int)
+    assert 0 <= s < 2**31
+
+
+def test_apply_seed_none_draws_random():
+    s = apply_seed(None)
+    assert isinstance(s, int)
+    assert 0 <= s < 2**31
+
+
+def test_apply_seed_seeds_pyrandom_so_repeats_match():
+    s = apply_seed(123)
+    a = pyrandom.random()
+    apply_seed(s)
+    b = pyrandom.random()
+    assert a == b
+
+
+def test_apply_seed_calls_torch_manual_seed():
+    with patch("server.seed.torch.manual_seed") as m:
+        apply_seed(99)
+    m.assert_called_once_with(99)
+
+
+def test_apply_seed_swallows_mps_failure():
+    with patch("server.seed._maybe_seed_mps", side_effect=RuntimeError("nope")):
+        # Should not raise
+        s = apply_seed(7)
+        assert s == 7