uncompose-engine 0.1.0__tar.gz

uncompose_engine-0.1.0/.gitignore

@@ -0,0 +1,4 @@
+/target
+engine/.venv/
+__pycache__/
+node_modules/

uncompose_engine-0.1.0/PKG-INFO

@@ -0,0 +1,7 @@
+Metadata-Version: 2.4
+Name: uncompose-engine
+Version: 0.1.0
+Summary: Separation engine shim: JSONL Engine Contract on one side, audio-separator on the other
+License-Expression: MIT
+Requires-Python: >=3.10
+Requires-Dist: audio-separator[gpu]>=0.44.5

uncompose_engine-0.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[project]
+name = "uncompose-engine"
+version = "0.1.0"
+description = "Separation engine shim: JSONL Engine Contract on one side, audio-separator on the other"
+# Floor matches audio-separator; the runtime Engine Environment is pinned to
+# 3.10 specifically because diffq (via demucs) ships binary wheels only up to
+# cp310 — any newer interpreter forces a C build, which a clean user machine
+# cannot do (ADR-0004).
+requires-python = ">=3.10"
+license = "MIT"
+dependencies = ["audio-separator[gpu]>=0.44.5"]
+
+[dependency-groups]
+dev = ["pytest>=8"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/uncompose_engine"]

uncompose_engine-0.1.0/src/uncompose_engine/__init__.py

@@ -0,0 +1,5 @@
+"""uncompose-engine: the Python side of the Engine Contract (ADR-0001).
+
+Spawned by the core, never imported by it. Request JSON on stdin, JSONL
+events on stdout, all human logging on stderr.
+"""

uncompose_engine-0.1.0/src/uncompose_engine/__main__.py

@@ -0,0 +1,117 @@
+"""Engine Contract entry point: `python -m uncompose_engine`.
+
+Reads one JSON request from stdin, runs the model via audio-separator, and
+emits JSONL events on stdout. Everything else (library logging, tqdm bars,
+stray prints) is forced onto stderr so the event stream stays parseable.
+"""
+
+import importlib.metadata
+import json
+import logging
+import os
+import sys
+import time
+
+import torch
+from audio_separator.separator import Separator
+
+# Models known to this engine: audio-separator filename plus the mapping
+# from audio-separator's stem names to Uncompose's preset-level stem names
+# (keys.wav, not piano.wav — the model is piano-trained, the name is stable).
+MODELS = {
+    "mel_band_roformer_kim": {
+        "filename": "vocals_mel_band_roformer.ckpt",
+        # audio-separator calls this model's non-vocal stem "Other".
+        "output_names": {
+            "Vocals": "vocals",
+            "Other": "instrumental",
+        },
+    },
+    "htdemucs_6s": {
+        "filename": "htdemucs_6s.yaml",
+        "output_names": {
+            "Vocals": "vocals",
+            "Drums": "drums",
+            "Bass": "bass",
+            "Guitar": "guitar",
+            "Piano": "keys",
+            "Other": "other",
+        },
+    },
+}
+
+
+def main() -> int:
+    # Keep a private handle to the real stdout for events, then point fd 1
+    # at stderr so nothing the ML stack prints can corrupt the JSONL stream.
+    events = os.fdopen(os.dup(1), "w", buffering=1)
+    os.dup2(2, 1)
+    sys.stdout = sys.stderr
+
+    def emit(event: dict) -> None:
+        events.write(json.dumps(event) + "\n")
+
+    try:
+        request = json.load(sys.stdin)
+        return run(request, emit)
+    except Exception as exc:  # terminal: report on the contract, exit nonzero
+        logging.exception("engine failed")
+        emit({"event": "error", "message": str(exc)})
+        return 1
+
+
+def run(request: dict, emit) -> int:
+    model = MODELS.get(request["model_id"])
+    if model is None:
+        raise ValueError(f"unknown model id: {request['model_id']}")
+
+    logging.basicConfig(stream=sys.stderr, level=logging.INFO)
+
+    emit({"event": "stage", "stage": "model_load", "message": request["model_id"]})
+    t0 = time.monotonic()
+    separator = Separator(
+        output_dir=request["output_dir"],
+        model_file_dir=request["model_dir"],
+        output_format="wav",
+    )
+    separator.load_model(model_filename=model["filename"])
+    model_load_secs = time.monotonic() - t0
+
+    emit({"event": "stage", "stage": "separate"})
+    t1 = time.monotonic()
+    separator.separate(request["audio_path"], custom_output_names=model["output_names"])
+    separate_secs = time.monotonic() - t1
+
+    # audio-separator can swallow decode failures and return with nothing
+    # written; missing stems are a failed job, not a quiet success. Each stem
+    # is staged as `<stem>.wav.partial`; the core promotes it to its final
+    # name when it sees the stem event, so a crash leaves partials behind.
+    missing = []
+    for stem_name in model["output_names"].values():
+        final = os.path.join(request["output_dir"], f"{stem_name}.wav")
+        if os.path.exists(final):
+            partial = final + ".partial"
+            os.replace(final, partial)
+            emit({"event": "stem", "name": stem_name, "path": partial})
+        else:
+            missing.append(stem_name)
+    if missing:
+        raise RuntimeError(f"separation produced no output for: {', '.join(missing)}")
+
+    emit(
+        {
+            "event": "done",
+            "model_id": request["model_id"],
+            "engine_version": importlib.metadata.version("uncompose-engine"),
+            "device": "cuda" if torch.cuda.is_available() else "cpu",
+            "timings": {
+                "model_load_secs": round(model_load_secs, 2),
+                "separate_secs": round(separate_secs, 2),
+            },
+        }
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

uncompose_engine-0.1.0/tests/conftest.py

@@ -0,0 +1,8 @@
+"""Shim contract tests run with audio-separator and torch faked at their
+Python interface (Testing Decisions in #22): the fakes dir must shadow any
+real install before the module under test is imported."""
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent / "fakes"))

uncompose_engine-0.1.0/tests/fakes/audio_separator/separator.py

@@ -0,0 +1,50 @@
+"""Fake audio-separator, substituted at its Python interface.
+
+The shim under test imports `Separator` from here (the fakes dir shadows any
+real install on sys.path). Behavior is steered by env vars so it works the
+same in-process and across the subprocess tests:
+
+- FAKE_SEPARATOR_CALL_LOG: path to write a JSON log of calls for assertions
+- FAKE_SEPARATOR_SKIP_STEMS: comma-separated output names to *not* write,
+  simulating audio-separator swallowing a decode failure
+"""
+
+import json
+import os
+
+
+class Separator:
+    def __init__(self, **kwargs):
+        self.kwargs = kwargs
+        self.calls = []
+        self.loaded = None
+
+    def load_model(self, model_filename):
+        self.loaded = model_filename
+        self.calls.append({"method": "load_model", "model_filename": model_filename})
+
+    def separate(self, audio_path, custom_output_names=None):
+        # Anything the real library prints or bars through stdout must not
+        # corrupt the JSONL stream; the purity test relies on this print.
+        print("fake audio-separator chatter on stdout")
+        self.calls.append(
+            {
+                "method": "separate",
+                "audio_path": audio_path,
+                "custom_output_names": custom_output_names,
+            }
+        )
+        skip = set(filter(None, os.environ.get("FAKE_SEPARATOR_SKIP_STEMS", "").split(",")))
+        for name in (custom_output_names or {}).values():
+            if name in skip:
+                continue
+            path = os.path.join(self.kwargs["output_dir"], f"{name}.wav")
+            with open(path, "wb") as f:
+                f.write(b"RIFF")
+        self._write_call_log()
+
+    def _write_call_log(self):
+        log_path = os.environ.get("FAKE_SEPARATOR_CALL_LOG")
+        if log_path:
+            with open(log_path, "w") as f:
+                json.dump({"init": self.kwargs, "calls": self.calls}, f)

uncompose_engine-0.1.0/tests/fakes/torch.py

@@ -0,0 +1,5 @@
+"""Fake torch: just enough surface for the shim's device report."""
+
+from types import SimpleNamespace
+
+cuda = SimpleNamespace(is_available=lambda: False)

uncompose_engine-0.1.0/tests/test_contract.py

@@ -0,0 +1,164 @@
+"""The shim's side of the Engine Contract: given a request, it drives
+audio-separator correctly and emits valid JSONL. No model inference here or
+in CI; audio-separator is faked at its Python interface (see fakes/)."""
+
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+FAKES = Path(__file__).parent / "fakes"
+
+
+def make_request(tmp_path, model_id="htdemucs_6s"):
+    audio = tmp_path / "song.wav"
+    audio.write_bytes(b"not really audio")
+    output_dir = tmp_path / "out"
+    output_dir.mkdir()
+    return {
+        "audio_path": str(audio),
+        "model_id": model_id,
+        "output_dir": str(output_dir),
+        "model_dir": str(tmp_path / "models"),
+        "device": "cpu",
+    }
+
+
+# --- in-process: run() drives the library correctly ---
+
+
+def run_shim(request, monkeypatch, tmp_path):
+    from uncompose_engine.__main__ import run
+
+    call_log = tmp_path / "calls.json"
+    monkeypatch.setenv("FAKE_SEPARATOR_CALL_LOG", str(call_log))
+    events = []
+    code = run(request, events.append)
+    calls = json.loads(call_log.read_text()) if call_log.exists() else None
+    return code, events, calls
+
+
+def test_success_emits_stages_stems_and_done(monkeypatch, tmp_path):
+    request = make_request(tmp_path)
+    code, events, calls = run_shim(request, monkeypatch, tmp_path)
+
+    assert code == 0
+    kinds = [e["event"] for e in events]
+    assert kinds[:2] == ["stage", "stage"]
+    assert events[0]["stage"] == "model_load"
+    assert events[1]["stage"] == "separate"
+
+    stems = [e for e in events if e["event"] == "stem"]
+    # Preset-level stem names: keys.wav, never piano.wav.
+    assert sorted(e["name"] for e in stems) == sorted(
+        ["vocals", "drums", "bass", "guitar", "keys", "other"]
+    )
+    for e in stems:
+        # Stems are staged as `<stem>.wav.partial`; the core promotes them.
+        assert e["path"].endswith(".wav.partial")
+        assert os.path.exists(e["path"])
+
+    done = events[-1]
+    assert done["event"] == "done"
+    assert done["model_id"] == "htdemucs_6s"
+    assert done["device"] == "cpu"  # fake torch reports no CUDA
+    assert done["engine_version"]
+    assert set(done["timings"]) == {"model_load_secs", "separate_secs"}
+
+
+def test_success_calls_audio_separator_correctly(monkeypatch, tmp_path):
+    request = make_request(tmp_path)
+    _, _, calls = run_shim(request, monkeypatch, tmp_path)
+
+    assert calls["init"]["output_dir"] == request["output_dir"]
+    assert calls["init"]["model_file_dir"] == request["model_dir"]
+    assert calls["init"]["output_format"] == "wav"
+    load, separate = calls["calls"]
+    assert load == {"method": "load_model", "model_filename": "htdemucs_6s.yaml"}
+    assert separate["audio_path"] == request["audio_path"]
+    assert separate["custom_output_names"]["Piano"] == "keys"
+
+
+def test_roformer_splits_vocals_and_instrumental(monkeypatch, tmp_path):
+    request = make_request(tmp_path, model_id="mel_band_roformer_kim")
+    code, events, calls = run_shim(request, monkeypatch, tmp_path)
+
+    assert code == 0
+    load, separate = calls["calls"]
+    assert load == {
+        "method": "load_model",
+        "model_filename": "vocals_mel_band_roformer.ckpt",
+    }
+    # audio-separator names this model's non-vocal stem "Other"; the contract
+    # name stays `instrumental`.
+    assert separate["custom_output_names"] == {
+        "Vocals": "vocals",
+        "Other": "instrumental",
+    }
+    stems = [e for e in events if e["event"] == "stem"]
+    assert sorted(e["name"] for e in stems) == ["instrumental", "vocals"]
+
+
+def test_unknown_model_id_raises(monkeypatch, tmp_path):
+    request = make_request(tmp_path, model_id="not-a-model")
+    with pytest.raises(ValueError, match="unknown model id"):
+        run_shim(request, monkeypatch, tmp_path)
+
+
+def test_missing_stem_output_is_a_failure_not_a_quiet_success(monkeypatch, tmp_path):
+    monkeypatch.setenv("FAKE_SEPARATOR_SKIP_STEMS", "keys")
+    request = make_request(tmp_path)
+    with pytest.raises(RuntimeError, match="keys"):
+        run_shim(request, monkeypatch, tmp_path)
+
+
+# --- subprocess: the executable's stream stays parseable end to end ---
+
+
+def run_engine_process(stdin_text):
+    env = dict(os.environ)
+    env["PYTHONPATH"] = os.pathsep.join(
+        [str(FAKES)] + [p for p in [env.get("PYTHONPATH")] if p]
+    )
+    return subprocess.run(
+        [sys.executable, "-m", "uncompose_engine"],
+        input=stdin_text,
+        capture_output=True,
+        text=True,
+        timeout=60,
+        env=env,
+    )
+
+
+def parse_events(stdout):
+    return [json.loads(line) for line in stdout.splitlines() if line.strip()]
+
+
+def test_stdout_is_pure_jsonl_despite_library_chatter(tmp_path):
+    result = run_engine_process(json.dumps(make_request(tmp_path)))
+    assert result.returncode == 0, result.stderr
+    # The fake Separator prints to stdout; the shim must have routed that to
+    # stderr, leaving stdout parseable line by line.
+    events = parse_events(result.stdout)
+    assert all("event" in e for e in events)
+    assert events[-1]["event"] == "done"
+    assert "chatter" not in result.stdout
+    assert "chatter" in result.stderr
+
+
+def test_unknown_model_emits_error_event_and_exits_nonzero(tmp_path):
+    result = run_engine_process(json.dumps(make_request(tmp_path, model_id="nope")))
+    assert result.returncode == 1
+    events = parse_events(result.stdout)
+    assert events[-1]["event"] == "error"
+    assert "unknown model id" in events[-1]["message"]
+
+
+def test_garbage_stdin_emits_error_event_and_exits_nonzero(tmp_path):
+    result = run_engine_process("this is not json")
+    assert result.returncode == 1
+    events = parse_events(result.stdout)
+    assert events[-1]["event"] == "error"