Skip to content
SoundverseSoundverse 2.0 — Engineering Docs

Test unmerged soundverse-py SDK changes

Every tool worker pins the SDK to git main, not a local path. In each tool repo’s pyproject.toml the dependency reads "soundverse @ git+https://github.com/soundversegit/soundverse-py.git@main" (the distribution name is soundverse; the repo on disk is soundverse-py). That pin is deliberate — it is what the auto-update PR bot bumps when the SDK’s main moves — but it means a plain uv run (or any make target) re-syncs the environment back to the pinned main and silently discards local edits you made to your sibling soundverse-py checkout.

So to test SDK work that hasn’t merged yet, you overlay your local checkout as an editable install and then run every command with --no-sync so uv leaves the overlay alone.

The recipe

Section titled “The recipe”

Run this from inside the tool repo whose worker you want to exercise (e.g. core-tool-sansaarm or core-tool-stitch). Both it and soundverse-py are submodules directly under core/, so the checkout is one level up at ../soundverse-py.

  1. Sync the base env first, so the pinned deps are in place before you overlay:

    core-tool-<name>/
    uv sync

  2. Overlay your local checkout as an editable install. This rewrites only the .venv; it does not touch pyproject.toml or uv.lock, so there is nothing to accidentally commit:

    core-tool-<name>/
    uv pip install -e ../soundverse-py

  3. Confirm the overlay is live — the location should point at your checkout, not a git cache:

    core-tool-<name>/
    uv pip show soundverse   # look for: Editable project location: .../soundverse-py

  4. Run your test loop with --no-sync on every command. This is the whole trick: it tells uv not to reconcile the env to the lockfile, which is what would otherwise reinstall soundverse from git main and wipe your overlay:

    core-tool-<name>/
    uv run --no-sync ruff check . \
      && uv run --no-sync pyright \
      && uv run --no-sync pytest -q

    To run the worker itself against the overlaid SDK, same flag:

    core-tool-<name>/
    uv run --no-sync python -m app.main

After your change lands

Section titled “After your change lands”

Once the SDK edit merges to soundverse-py’s main, the cascade fires the soundverse_updated dispatch and opens a uv.lock bump PR against each tool repo. From then on the pinned main already carries your change, so drop the overlay and go back to the normal flow:

core-tool-<name>/
uv sync        # re-pins to git main (now includes your change)
make check     # plain uv run works again
Section titled “Related”