feat(modes): add generate mode handler with input validation

modes.py

@@ -0,0 +1,40 @@
+"""Pure mode handlers — one function per generation mode.
+
+Each handler validates inputs, builds the ACE-Step kwargs for its mode, and
+hands off to `backend.dispatch(...)`. Backend ownership of @spaces.GPU and
+pipeline lifecycle keeps these handlers cheap to test.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def _require(params: dict[str, Any], field: str) -> Any:
+    v = params.get(field)
+    if v is None or (isinstance(v, str) and not v.strip()):
+        raise ValueError(f"Missing required field: {field}")
+    return v
+
+
+def generate(backend, params: dict[str, Any]) -> tuple[str, dict[str, Any]]:
+    """Text → song. Vocals + instruments in one stream."""
+    prompt = _require(params, "prompt")
+    lyrics = params.get("lyrics", "")
+    duration_s = int(params.get("duration_s", 30))
+    instrumental = bool(params.get("instrumental", False))
+
+    return backend.dispatch(
+        mode="generate",
+        params={
+            "prompt": prompt,
+            "lyrics": lyrics,
+            "duration_s": duration_s,
+            "instrumental": instrumental,
+            "seed": params.get("seed"),
+            "loras": params.get("loras", []),
+            "advanced": params.get("advanced", {}),
+            "lm": params.get("lm", {}),
+            "dcw": params.get("dcw", {}),
+        },
+    )

tests/test_modes_generate.py

@@ -0,0 +1,38 @@
+"""L2 tests for the generate mode handler — backend is mocked at the pipeline boundary."""
+
+from __future__ import annotations
+
+from unittest.mock import MagicMock
+
+import pytest
+
+import modes
+
+
+def test_generate_validates_prompt_required():
+    backend = MagicMock()
+    with pytest.raises(ValueError, match="prompt"):
+        modes.generate(backend, params={"prompt": "", "lyrics": "[verse] x", "duration_s": 10})
+
+
+def test_generate_passes_params_to_backend(monkeypatch):
+    backend = MagicMock()
+    backend.dispatch.return_value = ("/tmp/audio.wav", {"seed": 42})
+    out_path, meta = modes.generate(
+        backend,
+        params={
+            "prompt": "psytrance",
+            "lyrics": "[verse] x",
+            "duration_s": 30,
+            "instrumental": False,
+            "seed": 42,
+        },
+    )
+
+    assert out_path == "/tmp/audio.wav"
+    assert meta["seed"] == 42
+    backend.dispatch.assert_called_once()
+    call_kwargs = backend.dispatch.call_args.kwargs
+    assert call_kwargs["mode"] == "generate"
+    # Cover-style params must be absent for the generate mode
+    assert "audio_cover_strength" not in call_kwargs["params"]