Files
Andrew Beveridge ☄️andClaude Opus 5.5 f4f0f6af77 feat(review): only show the review button once the job is fully prepared (v0.298.0) (#1273)
## Summary

The review button now appears only once a job is fully prepared: stems
separated, auto-approval re-scored with them, AI lyric corrections
generated and applied on the server, and review audio + waveforms
cached. The browser no longer applies AI corrections by itself, so there
is one code path.

Prompted by job ae995697 (a Made For You order): the review button
showed at 18:29, but the stems, backing verdict and vocal waveform only
existed from 18:32, and the server pre-apply had aborted on a
duplicate-word check, leaving the browser to apply corrections on load.

## Changes

- **Hold every job until stems land**
(`review_gate.route_after_scoring`). Before, only jobs whose lyrics
would auto-ship were held, so Made For You and lyrics-gated jobs opened
review early. Same kill switch (`AUTO_APPROVAL_AUDIO_HOLD_ENABLED`) and
20-minute backstop.
- **Generate AI suggestions on the API service before parking.** The
hold is released inside the audio-separation job, which has no LLM
credentials, so that job only applies an existing cache.
- **`enter_human_review` prepares everything before AWAITING_REVIEW**:
pre-apply (generating on a cache miss), then
`review_assets.prepare_review_assets` (OGG transcodes, backing waveform,
vocal peak envelope), then the transition.
- **Non-strict pre-apply for human review**
(`build_applied_segments(strict=False)`): what "Accept All" produces.
Stale/duplicate signals are recorded as `warnings`. The auto-ship path
stays strict.
- **Removed the browser's on-load auto-run/auto-apply** from
`useAutoCorrect`.
- **Job card shows "[5/10] Preparing review"** while held (new summary
field + 33 locales).
- Docs: ARCHITECTURE review-gate step,
`docs/archive/2026-11-19-review-ready-gate.md`.

Trade-off: Made For You and lyrics-gated jobs reach review (and send the
review-ready notification) ~3 minutes later.

## Testing

- Backend unit suite: 7294 passed. Locally failing: 8
emulator-integration tests (something unrelated listens on :8080 so they
don't skip; CI runs them against real emulators) and 1 locale test that
tripped on a gitignored translation snapshot (passes once removed).
- New/updated tests: review gate (review-verdict jobs held, kill switch,
prepare-before-transition order, suggestions generated before parking,
no double wait, missing job), non-strict apply, duplicate-word pre-apply
(ae995697 case), review_assets.
- Frontend Jest: 1834 passed; no type errors in touched files.
- Local CodeRabbit: 2 minor findings fixed, re-review clean.

@coderabbitai ignore

🤖 Generated with [Claude Code](https://claude.com/claude-code)

https://claude.ai/code/session_012RYLVVdAxGitbw1FhYP4e4

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-19 16:12:58 -05:00
..

Backend Development Setup

One-Time Setup

1. Create Virtual Environment

cd /Users/andrew/Projects/karaoke-gen
python3 -m venv backend/venv

2. Activate Virtual Environment

source backend/venv/bin/activate

3. Install Dependencies

IMPORTANT: Use Python 3.12 (not 3.13/3.14 - pydantic has compatibility issues)

# Backend dependencies
pip install -r backend/requirements.txt

# Install karaoke_gen in development mode
pip install -e .

# Install lyrics_transcriber submodule
pip install -e lyrics_transcriber_local/

# Install Google API client (for YouTube upload)
pip install google-api-python-client google-auth-httplib2 google-auth-oauthlib

4. Add Shell Alias (Optional)

Add to ~/.zshrc:

alias backend='cd /Users/andrew/Projects/karaoke-gen && source backend/venv/bin/activate'

Then you can just run:

backend
# Now you're in the project directory with venv activated!

Daily Workflow

Before Making Changes

# Activate venv
source backend/venv/bin/activate

# Or if you set up the alias:
backend

After Making Changes

# 1. Run full validation (catches import errors!)
python3 backend/validate.py

# 2. If validation passes, deploy
./scripts/deploy.sh

Validation Options

source backend/venv/bin/activate
python3 backend/validate.py

Catches:

  • ✅ Syntax errors
  • ✅ Import errors (like the processing_service issue!)
  • ✅ Configuration issues
  • ✅ FastAPI app creation problems
  • ✅ Missing dependencies

This would have caught the ModuleNotFoundError!

Quick Check (No venv needed)

./backend/quick-check.sh

Catches:

  • ✅ Syntax errors
  • ✅ Missing files
  • ✅ Some obvious import issues

Good for quick checks, but won't catch all import errors


Example: Complete Development Session

# 1. Activate environment
backend  # or: source backend/venv/bin/activate

# 2. Make your changes
vim backend/api/routes/jobs.py

# 3. Validate (catches import errors!)
python3 backend/validate.py
# ✅ All validations passed!

# 4. Deploy
./scripts/deploy.sh

# 5. Test
export BACKEND_URL="https://karaoke-backend-ipzqd2k4yq-uc.a.run.app"
export AUTH_TOKEN=$(gcloud auth print-identity-token)
curl -H "Authorization: Bearer $AUTH_TOKEN" $BACKEND_URL/api/health

What About karaoke_gen Imports?

The backend imports from karaoke_gen (the CLI package):

from karaoke_gen.karaoke_gen import KaraokePrep
from karaoke_gen.audio_processor import AudioProcessor

Options:

source backend/venv/bin/activate
pip install -e .

This makes karaoke_gen available in the venv without copying files.

Option 2: Use system Python

Your system Python already has karaoke_gen installed, so validation will work even if the venv doesn't have it (Python will fall back to system packages).


Running the Backend Locally

# Activate venv
source backend/venv/bin/activate

# Set required environment variables
export GOOGLE_CLOUD_PROJECT="nomadkaraoke"
export GCS_BUCKET_NAME="karaoke-gen-storage-nomadkaraoke"

# Optional: Point to local credentials
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account-key.json"

# Run the server
cd backend
uvicorn main:app --reload --port 8080

Visit: http://localhost:8080/api/health


Troubleshooting

"No module named 'fastapi'"

Fix:

source backend/venv/bin/activate
pip install -r backend/requirements.txt

"No module named 'karaoke_gen'"

Fix:

source backend/venv/bin/activate
cd /Users/andrew/Projects/karaoke-gen
pip install -e .

Validation passes locally but fails in Cloud Run

Check:

  1. Is requirements.txt up to date?
  2. Did you add a new dependency without adding it to requirements.txt?
  3. Run: pip freeze | grep <package-name>

Updating Dependencies

When you add new packages:

# 1. Install in venv
source backend/venv/bin/activate
pip install new-package

# 2. Update requirements.txt
pip freeze > backend/requirements.txt

# 3. Or manually add just the new package:
echo "new-package==1.2.3" >> backend/requirements.txt

# 4. Validate
python3 backend/validate.py

# 5. Deploy
./scripts/deploy.sh

Summary

Best practice workflow:

  1. One-time setup: Create venv and install dependencies
  2. Daily: Activate venv when working on backend
  3. Before deploy: Run python3 backend/validate.py (catches import errors!)
  4. Deploy: Use ./scripts/deploy.sh

The import error would have been caught if you ran validation in a venv! ✅