The open-source AI voice studio. Clone, dictate, create.
rewrite backend README, remove completed refactor plan, update style guide
James Pine7b0fbfb567f5
diff --git a/backend/README.md b/backend/README.mdindex bfbb4ac1..170cab1c 100644--- a/backend/README.md+++ b/backend/README.md@@ -1,473 +1,135 @@-# voicebox Backend+# Voicebox Backend-Production-quality FastAPI backend for Qwen3-TTS voice cloning.+FastAPI server powering voice cloning, speech generation, and audio processing. Runs locally as a Tauri sidecar or standalone via `python -m backend.main`.-## Features+## Running-- ✅ **Voice Profile Management** - Create, update, delete voice profiles with multi-sample support-- ✅ **Voice Cloning** - Generate speech using voice profiles with caching-- ✅ **Generation History** - Full history tracking with search and filtering-- ✅ **Transcription** - Whisper-based audio transcription-- ✅ **Multi-Sample Profiles** - Combine multiple reference samples for better quality-- ✅ **Voice Prompt Caching** - Dual memory + disk caching for fast generation-- ✅ **Audio Validation** - Automatic validation of reference audio quality-- ✅ **Model Management** - Lazy loading and VRAM management--## Architecture--```-backend/-├── main.py # FastAPI app with all routes-├── server.py # PyInstaller entry point, CLI arg parsing-├── models.py # Pydantic request/response models-├── config.py # Data directory configuration-├── database.py # SQLAlchemy ORM models + migrations-├── platform_detect.py # Platform detection for backend selection-├── tts.py # TTS backend facade-├── transcribe.py # STT backend facade-├── profiles.py # Voice profile CRUD-├── history.py # Generation history CRUD-├── channels.py # Audio channel management-├── stories.py # Story/timeline management + audio export-├── effects.py # Effect preset CRUD-├── versions.py # Generation version management-├── export_import.py # ZIP export/import for profiles and generations-├── backends/ # Backend implementations-│ ├── __init__.py # Protocols, model config registry, factory functions-│ ├── mlx_backend.py # MLX backend (Apple Silicon)-│ ├── pytorch_backend.py # PyTorch backend (Windows/Linux/Intel)-│ ├── chatterbox_backend.py # Chatterbox Multilingual TTS-│ ├── chatterbox_turbo_backend.py # Chatterbox Turbo TTS-│ └── luxtts_backend.py # LuxTTS backend-└── utils/- ├── audio.py # Audio load/save/normalize/validate/trim- ├── cache.py # Voice prompt caching (memory + disk)- ├── effects.py # Audio effects engine (pedalboard)- ├── chunked_tts.py # Text chunking + audio concatenation- ├── progress.py # SSE progress tracking- ├── tasks.py # Active task tracking- ├── hf_progress.py # HuggingFace download progress tracking- ├── hf_offline_patch.py # HuggingFace offline mode patch (MLX)- └── images.py # Avatar image processing-```--### Backend Selection--Voicebox automatically selects the best backend based on platform:--- **Apple Silicon (M1/M2/M3)**: Uses MLX backend with native Metal acceleration (4-5x faster)-- **Windows/Linux/Intel Mac**: Uses PyTorch backend (CUDA GPU if available, CPU fallback)--The backend is detected at runtime via `platform_detect.py`. Both backends implement the same interface, so the API remains consistent across platforms.--## API Endpoints--### Health & Info--#### `GET /`-Root endpoint with version info.--#### `GET /health`-Health check with model status.--**Response:**-```json-{- "status": "healthy",- "model_loaded": true,- "gpu_available": true,- "gpu_type": "Metal (Apple Silicon via MLX)",- "backend_type": "mlx",- "vram_used_mb": null-}-```--**Backend Types:**-- `"mlx"` - MLX backend (Apple Silicon with Metal acceleration)-- `"pytorch"` - PyTorch backend (Windows/Linux/Intel Mac)--### Voice Profiles--**Note:** The database is automatically initialized when the server starts. No manual setup required.--#### `POST /profiles`-Create a new voice profile.--**Request:**-```json-{- "name": "My Voice",- "description": "Optional description",- "language": "en"-}-```--**Response:**-```json-{- "id": "uuid",- "name": "My Voice",- "description": "Optional description",- "language": "en",- "created_at": "2024-01-01T00:00:00Z",- "updated_at": "2024-01-01T00:00:00Z"-}-```--#### `GET /profiles`-List all voice profiles.--#### `GET /profiles/{profile_id}`-Get a specific profile.--#### `PUT /profiles/{profile_id}`-Update a profile.--#### `DELETE /profiles/{profile_id}`-Delete a profile and all associated samples.--#### `POST /profiles/{profile_id}/samples`-Add a sample to a profile.--**Form Data:**-- `file`: Audio file (WAV, MP3, etc.)-- `reference_text`: Transcript of the audio--**Response:**-```json-{- "id": "sample-uuid",- "profile_id": "profile-uuid",- "audio_path": "/path/to/sample.wav",- "reference_text": "This is my voice"-}-```--#### `GET /profiles/{profile_id}/samples`-List all samples for a profile.--#### `DELETE /profiles/samples/{sample_id}`-Delete a specific sample.--### Generation--#### `POST /generate`-Generate speech from text using a voice profile.--**Request:**-```json-{- "profile_id": "uuid",- "text": "Hello, this is a test.",- "language": "en",- "seed": 42-}-```--**Response:**-```json-{- "id": "generation-uuid",- "profile_id": "profile-uuid",- "text": "Hello, this is a test.",- "language": "en",- "audio_path": "/path/to/audio.wav",- "duration": 2.5,- "seed": 42,- "created_at": "2024-01-01T00:00:00Z"-}-```--### History--#### `GET /history`-List generation history with optional filters.--**Query Parameters:**-- `profile_id` (optional): Filter by profile-- `search` (optional): Search in text content-- `limit` (default: 50): Results per page-- `offset` (default: 0): Pagination offset--#### `GET /history/{generation_id}`-Get a specific generation.--#### `DELETE /history/{generation_id}`-Delete a generation.+```bash+# Via justfile (recommended)+just dev:server-#### `GET /history/stats`-Get generation statistics.+# Standalone+python -m backend.main --host 127.0.0.1 --port 17493-**Response:**-```json-{- "total_generations": 100,- "total_duration_seconds": 250.5,- "generations_by_profile": {- "profile-uuid-1": 50,- "profile-uuid-2": 50- }-}+# With custom data directory+python -m backend.main --data-dir /path/to/data```-### Audio Files--#### `GET /audio/{generation_id}`-Download generated audio file.--Returns WAV file with appropriate headers.+The server auto-initializes the SQLite database on first startup. Models are downloaded from HuggingFace on first use.-### Transcription--#### `POST /transcribe`-Transcribe audio file to text.--**Form Data:**-- `file`: Audio file-- `language` (optional): Language hint (en or zh)+## Architecture-**Response:**-```json-{- "text": "Transcribed text here",- "duration": 5.5-}```+backend/+ app.py # FastAPI app factory, CORS, lifecycle events+ main.py # Entry point (imports app, runs uvicorn)+ config.py # Data directory paths and configuration+ models.py # Pydantic request/response schemas+ server.py # Tauri sidecar launcher, parent-pid watchdog-### Model Management--#### `POST /models/load`-Manually load TTS model.--**Query Parameters:**-- `model_size`: Model size (1.7B or 0.6B)--#### `POST /models/unload`-Unload TTS model to free memory.--## Database Schema--### profiles-- `id`: UUID primary key-- `name`: Profile name (unique)-- `description`: Optional description-- `language`: Language code (en/zh)-- `created_at`: Creation timestamp-- `updated_at`: Last update timestamp--### profile_samples-- `id`: UUID primary key-- `profile_id`: Foreign key to profiles-- `audio_path`: Path to audio file-- `reference_text`: Transcript--### generations-- `id`: UUID primary key-- `profile_id`: Foreign key to profiles-- `text`: Generated text-- `language`: Language code-- `audio_path`: Path to audio file-- `duration`: Duration in seconds-- `seed`: Random seed (optional)-- `created_at`: Creation timestamp--### projects-- `id`: UUID primary key-- `name`: Project name-- `data`: JSON data-- `created_at`: Creation timestamp-- `updated_at`: Last update timestamp--## File Structure--```-data/-├── profiles/-│ └── {profile_id}/-│ ├── {sample_id}.wav-│ └── ...-├── generations/-│ └── {generation_id}.wav-├── cache/-│ └── {hash}.prompt-├── projects/-│ └── {project_id}.json-└── voicebox.db+ routes/ # Thin HTTP handlers — validation, delegation, response formatting+ services/ # Business logic, CRUD, orchestration+ backends/ # TTS/STT engine implementations (MLX, PyTorch, etc.)+ database/ # ORM models, session management, migrations, seed data+ utils/ # Shared utilities (audio, effects, caching, progress tracking)```-## Setup--### 1. Install Dependencies+### Request flow-```bash-pip install -r requirements.txt```--**Note:** On Apple Silicon, also install MLX dependencies for faster inference:-```bash-pip install -r requirements-mlx.txt+HTTP request+ -> routes/ (validate input, parse params)+ -> services/ (business logic, database queries, orchestration)+ -> backends/ (TTS/STT inference)+ -> utils/ (audio processing, effects, caching)```-### 2. Download Models (Automatic)+Route handlers are intentionally thin. They validate input, delegate to a service function, and format the response. All business logic lives in `services/`.-The Qwen3-TTS models are automatically downloaded from HuggingFace Hub on first use, similar to how Whisper models work.+### Key modules-**No manual download required!** The models will be cached locally after the first download.+**services/generation.py** -- Single `run_generation()` function that handles all three generation modes (generate, retry, regenerate). Manages model loading, voice prompt creation, chunked inference, normalization, effects, and version persistence.-Available models:-- **1.7B** (recommended): `Qwen/Qwen3-TTS-12Hz-1.7B-Base` (~4GB)-- **0.6B** (faster): `Qwen/Qwen3-TTS-12Hz-0.6B-Base` (~2GB)+**services/task_queue.py** -- Serial generation queue. Ensures only one GPU inference runs at a time. Background tasks are tracked to prevent garbage collection.-**Note:** The first generation will take longer as the model downloads. Subsequent generations will use the cached model.+**backends/__init__.py** -- Protocol definitions (`TTSBackend`, `STTBackend`), model config registry, and factory functions. Adding a new engine means implementing the protocol and registering a config entry.-#### Manual Download (Optional)+**backends/base.py** -- Shared utilities used across all engine implementations: HuggingFace cache checks, device detection, voice prompt combination, progress tracking.-If you prefer to download models manually or have limited internet during runtime:+**database/** -- SQLAlchemy ORM models with a re-exporting `__init__.py` for backward compatibility. Migrations run automatically on startup.-```bash-# Install huggingface-cli-pip install huggingface_hub+### Backend selection-# Download 1.7B model-huggingface-cli download Qwen/Qwen3-TTS-12Hz-1.7B-Base+The server detects the best inference backend at startup:-# Or use Python-python -c "from huggingface_hub import snapshot_download; snapshot_download('Qwen/Qwen3-TTS-12Hz-1.7B-Base')"-```+| Platform | Backend | Acceleration |+|----------|---------|-------------|+| macOS (Apple Silicon) | MLX | Metal / Neural Engine |+| Windows / Linux (NVIDIA) | PyTorch | CUDA |+| Linux (AMD) | PyTorch | ROCm |+| Intel Arc | PyTorch | IPEX / XPU |+| Windows (any GPU) | PyTorch | DirectML |+| Any | PyTorch | CPU fallback |-Models are cached in `~/.cache/huggingface/hub/` by default.+Detection is handled by `utils/platform_detect.py`. Both backends implement the same `TTSBackend` protocol, so the API layer is engine-agnostic.-### 4. Run Server+## API-```bash-# Development (local only)-python -m backend.main+90 endpoints organized by domain. Full interactive documentation available at `http://localhost:17493/docs` when the server is running.-# Production (allow remote access)-python -m backend.main --host 0.0.0.0 --port 8000-```+| Domain | Prefix | Description |+|--------|--------|-------------|+| Health | `/`, `/health` | Server status, GPU info, filesystem checks |+| Profiles | `/profiles` | Voice profile CRUD, samples, avatars, import/export |+| Channels | `/channels` | Audio channel management and voice assignment |+| Generation | `/generate` | TTS generation, retry, regenerate, status SSE |+| History | `/history` | Generation history, search, favorites, export |+| Transcription | `/transcribe` | Whisper-based audio-to-text |+| Stories | `/stories` | Multi-track timeline editor, audio export |+| Effects | `/effects` | Effect presets, preview, version management |+| Audio | `/audio`, `/samples` | Audio file serving |+| Models | `/models` | Load, unload, download, migrate, status |+| Tasks | `/tasks`, `/cache` | Active task tracking, cache management |+| CUDA | `/backend/cuda-*` | CUDA binary download and management |-## Usage Examples--The desktop app, web client, and current development workflow use `http://localhost:17493` by default.-If you launch the backend manually with a different host or port, substitute that address in the examples below.--### Creating a Voice Profile--```bash-# 1. Create profile-curl -X POST http://localhost:17493/profiles \- -H "Content-Type: application/json" \- -d '{"name": "My Voice", "language": "en"}'--# Response: {"id": "abc-123", ...}--# 2. Add sample-curl -X POST http://localhost:17493/profiles/abc-123/samples \- -F "[email protected]" \- -F "reference_text=This is my voice sample"-```--### Generating Speech+### Quick examples```bash+# Generate speechcurl -X POST http://localhost:17493/generate \-H "Content-Type: application/json" \- -d '{- "profile_id": "abc-123",- "text": "Hello, this is a test.",- "language": "en",- "seed": 42- }'+ -d '{"text": "Hello world", "profile_id": "...", "language": "en"}'-# Response: {"id": "gen-456", "audio_path": "/path/to/audio.wav", ...}+# List profiles+curl http://localhost:17493/profiles-# Download audio-curl http://localhost:17493/audio/gen-456 -o output.wav+# Stream generation status (SSE)+curl http://localhost:17493/generate/{id}/status```-### Transcribing Audio+## Data directory-```bash-curl -X POST http://localhost:17493/transcribe \- -F "[email protected]" \- -F "language=en"--# Response: {"text": "Transcribed text", "duration": 5.5}```--## Advanced Features--### Multi-Sample Profiles--Add multiple samples to a profile for better quality:--```bash-# Add first sample-curl -X POST http://localhost:17493/profiles/abc-123/samples \- -F "[email protected]" \- -F "reference_text=First sample"--# Add second sample-curl -X POST http://localhost:17493/profiles/abc-123/samples \- -F "[email protected]" \- -F "reference_text=Second sample"--# Generation will automatically combine all samples+{data_dir}/+ voicebox.db # SQLite database+ profiles/{id}/ # Voice samples per profile+ generations/ # Generated audio files+ cache/ # Voice prompt cache (memory + disk)+ backends/ # Downloaded CUDA binary (if applicable)```-### Voice Prompt Caching--Voice prompts are automatically cached for faster generation:-- First generation: ~5-10 seconds (creates prompt)-- Subsequent generations: ~1-2 seconds (uses cached prompt)+Default location is the OS-specific app data directory. Override with `--data-dir` or the `VOICEBOX_DATA_DIR` environment variable.-Cache is stored in `data/cache/` and persists across server restarts.+## Code quality-### VRAM Management--Models are lazy-loaded and can be manually unloaded:+Linting and formatting are enforced by [ruff](https://docs.astral.sh/ruff/), configured in `pyproject.toml`. See `STYLE_GUIDE.md` for conventions.```bash-# Unload TTS model-curl -X POST http://localhost:17493/models/unload--# Load specific model size-curl -X POST "http://localhost:17493/models/load?model_size=0.6B"-```--## Error Handling--All endpoints return proper HTTP status codes:--- `200 OK`: Success-- `400 Bad Request`: Invalid input-- `404 Not Found`: Resource not found-- `500 Internal Server Error`: Server error--Error responses include details:--```json-{- "detail": "Profile not found"-}+just check-python # lint + format check+just fix-python # auto-fix lint issues + reformat+just test # run pytest```-## Performance Tips--1. **Use multi-sample profiles** - Better quality than single sample-2. **Let caching work** - Voice prompts are cached automatically-3. **Use 0.6B model on CPU** - Faster than 1.7B with acceptable quality-4. **Use 1.7B model on GPU** - Best quality, still fast-5. **Unload Whisper after transcription** - Frees VRAM for TTS--## TODO--- [ ] WebSocket support for generation progress-- [ ] Batch generation endpoint-- [ ] Voice design (text-to-voice)-- [ ] Authentication & rate limiting--## License+## Dependencies-See main project LICENSE.+Runtime dependencies are in `requirements.txt`. macOS-only MLX dependencies are in `requirements-mlx.txt`. Dev tools (ruff, pytest) are installed automatically by `just setup-python`.diff --git a/backend/REFACTOR_PLAN.md b/backend/REFACTOR_PLAN.mddeleted file mode 100644index c5304d4b..00000000--- a/backend/REFACTOR_PLAN.md+++ /dev/null@@ -1,177 +0,0 @@-# Backend Refactor Plan--## Current State--`main.py` is still a ~2,800-line god file with 72 routes, 3x duplicated generation orchestration, fake async CRUD modules, and scattered constants. The backend dedup is done — adding new engines is now trivial.-------## Phase 1: Dead Code & Low-Hanging Fruit ✓--Deleted `studio.py`, `migrate_add_instruct.py`, `utils/validation.py`. Removed duplicate `_profile_to_response`, duplicate `import asyncio`, pointless wrapper functions. Consolidated `LANGUAGE_CODE_TO_NAME` and `WHISPER_HF_REPOS` into `backends/__init__.py`. Updated README.-------## Phase 2: Backend Deduplication ✓--Created `backends/base.py` with shared utilities:-- `is_model_cached()` — parameterized HF cache check (replaced 7 copies)-- `get_torch_device()` — parameterized device detection (replaced 5 copies)-- `combine_voice_prompts()` — load + normalize + concatenate (replaced 5 copies)-- `model_load_progress()` — context manager for progress tracking lifecycle (replaced 7 copies)-- `patch_chatterbox_f32()` — shared dtype monkey-patches (replaced 2 copies)--Net result: -1,078 lines across the backend.-------## Phase 3: Generation Service ✓--Extracted the three near-identical generation closures (`_run_generation`, `_run_retry`, `_run_regenerate`) and the background queue machinery from `main.py` into a new `services/` layer:--- `services/task_queue.py` — `create_background_task()`, `enqueue_generation()`, `init_queue()`, and the serial `_generation_worker`. Replaces the module-level globals and helpers that were in `main.py:63-92`.-- `services/generation.py` — single `run_generation()` function with a `mode` parameter (`"generate"`, `"retry"`, `"regenerate"`). Mode-specific persistence is handled by three small sync helpers (`_save_generate`, `_save_retry`, `_save_regenerate`). The shared pipeline (model loading, voice prompt creation, chunked inference, normalization, error handling, task manager lifecycle) is written once.--Route handlers in `main.py` are now thin: validate input, create/update DB row, resolve effects chain, then `enqueue_generation(run_generation(...))`.--Net result: ~240 lines of duplicated closure code replaced by a single 230-line service module + 50-line queue module.-------## Phase 4: Route Extraction--Split `main.py` (72 routes) into domain-specific routers. After Phase 3, the route handlers should be thin — just validation, delegation, and response formatting.--### Target structure--```-backend/- app.py # FastAPI app creation, middleware, startup/shutdown- routes/- __init__.py- health.py # GET /, /health, /health/filesystem, /shutdown, /watchdog/disable (5 routes)- profiles.py # All /profiles/* routes (17 routes)- channels.py # All /channels/* routes (7 routes)- generations.py # /generate, /generate/stream, /generate/*/retry, regenerate, status (5 routes)- history.py # All /history/* routes (8 routes)- stories.py # All /stories/* routes (15 routes)- effects.py # All /effects/* routes + /generations/*/versions/* (11 routes)- audio.py # /audio/*, /samples/* (2 routes)- models.py # All /models/* routes (11 routes)- tasks.py # /tasks/*, /cache/* (3 routes)- cuda.py # /backend/cuda-* (4 routes)- services/- generation.py # TTS orchestration (from Phase 3)- model_status.py # HF cache inspection logic (currently inline at main.py:2251-2431)-```--`main.py` becomes a thin entry point that imports the app from `app.py` and runs uvicorn (preserving backward compat for `python -m backend.main`).--### Model status extraction--The `get_model_status` endpoint (`main.py:2251-2431`) is 180 lines of HuggingFace cache inspection that duplicates logic from `_is_model_cached` in the backends. Extract to `services/model_status.py` and reuse the shared `is_model_cached` from Phase 2 where possible.-------## Phase 5: Database Cleanup--### Adopt Alembic--Replace the hand-rolled `_run_migrations()` (200 lines of manual ALTER TABLE + column existence checks) with Alembic.--**Why:**-- Current approach has no migration tracking — checks column existence on every startup-- Can't express complex migrations (data transforms, renames) safely-- No rollback path-- Already at 12 migration blocks and growing--**Migration steps:**--1. `pip install alembic` and add to `requirements.txt`-2. Run `alembic init alembic` to scaffold the config-3. Point `alembic/env.py` at the existing SQLAlchemy `Base.metadata` and engine-4. Create a baseline migration stamped as the current schema — this tells Alembic "the DB already has all this, don't recreate it":- ```bash- alembic revision --autogenerate -m "baseline"- # Then stamp existing DBs so they skip the baseline:- alembic stamp head- ```-5. Replace `_run_migrations()` in `init_db()` with `alembic.command.upgrade(config, "head")`-6. Move `_backfill_generation_versions` and `_seed_builtin_presets` into a post-migration hook or a dedicated seed step in `init_db()`-7. Delete the 200 lines of manual migration code--**Going forward**, new schema changes become:-```bash-# Auto-generate from model diff-alembic revision --autogenerate -m "add_whatever_column"-# Review the generated file, then it runs on next startup-```--**Target structure:**--```-backend/- alembic/- versions/- 001_baseline.py- env.py- alembic.ini- database/- __init__.py # re-exports for backward compat- models.py # ORM model definitions (11 models, ~140 lines)- session.py # engine creation, init_db(), get_db()- seed.py # _backfill_generation_versions + _seed_builtin_presets-```--### Fix async-over-sync CRUD modules--`channels.py`, `history.py`, `stories.py`, `effects.py`, `versions.py`, `profiles.py` all declare `async def` but never `await`. They run synchronous SQLAlchemy queries directly, blocking the event loop. Two options:--- **Option A**: Drop `async` keyword, wrap calls in `asyncio.to_thread()` at the route layer-- **Option B**: Switch to async SQLAlchemy (`create_async_engine` + `AsyncSession`)--Option A is simpler and non-disruptive. Option B is cleaner long-term but touches every query.-------## Phase 6: Polish--- Consolidate hardcoded constants (`24000` sample rate, `100MB`/`50MB` max file sizes, `HSA_OVERRIDE_GFX_VERSION`, CORS origins) into `config.py` or a `constants.py`-- Fix `hf_offline_patch.py` side-effect-on-import (runs patching twice — once on import, once explicitly in `mlx_backend.py`)-- Standardize error handling across routes (currently three different patterns)-- Rename `effects.py` (preset CRUD) to avoid confusion with `utils/effects.py` (DSP engine) — either rename to `effect_presets.py` or fold into routes-- Clean up test suite — the 4 manual integration scripts in `tests/` should either be converted to pytest or moved to a `scripts/` dir-------## Phase 7: Style Guide & Tooling ✓--Added a Python style guide (`backend/STYLE_GUIDE.md`) and automated linting/formatting with ruff. Removed the redundant Makefile — the justfile is now the single task runner.--### Style guide--Codifies conventions for the refactor: Google-style docstrings, native 3.12 type syntax (`list[str]`, `X | None` — no `from __future__` or `typing.List`), `logging` module instead of `print()`, two-layer error handling (domain exceptions + route-layer HTTPException), import grouping (stdlib / third-party / local with isort enforcement), 120-char line length.--### Ruff config (`pyproject.toml`)--Added project-root `pyproject.toml` with ruff linter + formatter config. Rule sets: `F`, `E`, `W`, `I` (isort), `N` (naming), `UP` (pyupgrade to 3.12), `B` (bugbear), `SIM`, `RET`, `T20` (print detection), `PT` (pytest style), `RUF`. `T201` (print) is ignored during migration — remove once logging conversion is done.--Initial scan: 1,103 lint violations (879 auto-fixable), 38 files needing reformatting. Mostly whitespace (W293), type annotation modernization (UP045/UP006), and import sorting (I001). To be fixed file-by-file as files are touched, not in a big-bang pass.--### Justfile updates--- `just check` now runs both JS (Biome) and Python (ruff) checks-- Added `just check-python`, `just lint-python`, `just format-python`, `just fix-python`, `just test`-- `just setup-python` installs `ruff`, `pytest`, `pytest-asyncio` as dev tools-- Deleted `Makefile` and updated all references in `CHANGELOG.md`, `PATCH_NOTES.md`, `docs/plans/ADDING_TTS_ENGINES.md`-------## Notes--- Each phase is independently shippable and testable-- Phase 1 is zero-risk deletion-- Phase 2 is self-contained within `backends/`-- Phase 3 sets up the extraction pattern needed for Phase 4-- Phase 4 is the largest change but should be mostly mechanical after Phase 3-- Phase 5 can run in parallel with Phase 4 since it touches different filesdiff --git a/backend/STYLE_GUIDE.md b/backend/STYLE_GUIDE.mdindex c6a75672..693b5308 100644--- a/backend/STYLE_GUIDE.md+++ b/backend/STYLE_GUIDE.md@@ -275,7 +275,7 @@ async def create_profile(data: VoiceProfileCreate, db: Session = Depends(get_db)### Rules for the refactor-1. **Don't declare `async def` unless the function awaits something.** The current CRUD modules break this -- they will be fixed per REFACTOR_PLAN Phase 5.+1. **Don't declare `async def` unless the function awaits something.** Several service modules still declare `async def` without awaiting -- these should be migrated to sync functions with `asyncio.to_thread()` at the route layer, or to real async SQLAlchemy.2. **CPU-bound work** (audio processing, numpy operations) goes through `asyncio.to_thread()`:```pythonaudio, sr = await asyncio.to_thread(load_audio, source_path)@@ -367,68 +367,28 @@ Framework: **pytest** with `pytest-asyncio`.----## Project Layout (Post-Refactor Target)--From REFACTOR_PLAN.md Phase 4:+## Project Layout```backend/- app.py # FastAPI app, middleware, startup/shutdown- main.py # Entry point (imports app, runs uvicorn)- config.py # Data dirs, shared constants- errors.py # Custom exception classes- routes/- __init__.py- health.py- profiles.py- channels.py- generations.py- history.py- stories.py- effects.py- audio.py- models.py- tasks.py- cuda.py- services/- generation.py- task_queue.py- model_status.py- database/- __init__.py- models.py- session.py- seed.py- backends/- __init__.py- base.py- pytorch_backend.py- mlx_backend.py- luxtts_backend.py- chatterbox_backend.py- chatterbox_turbo_backend.py- utils/- audio.py- effects.py- progress.py- tasks.py- hf_progress.py- hf_offline_patch.py- cache.py- images.py- chunked_tts.py- tests/- conftest.py- test_cors.py- test_profiles.py- ...+ app.py # FastAPI app factory, CORS, lifecycle events+ main.py # Entry point (imports app, runs uvicorn)+ config.py # Data directory paths+ models.py # Pydantic request/response schemas+ server.py # Tauri sidecar launcher, parent-pid watchdog+ routes/ # Thin HTTP handlers (validation, delegation, response formatting)+ services/ # Business logic, CRUD, orchestration+ backends/ # TTS/STT engine implementations+ database/ # ORM models, session management, migrations, seeds+ utils/ # Shared utilities (audio, effects, caching, progress)+ tests/ # pytest suite```---## Ruff Adoption-The `pyproject.toml` at the project root configures ruff for linting and formatting. Run:+`pyproject.toml` configures ruff for linting and formatting. Run:```bash# Lint (check)@@ -441,20 +401,4 @@ ruff check backend/ --fixruff format backend/```-During the refactor, introduce ruff fixes file-by-file as you touch them. Don't run `--fix` across the entire codebase in one shot -- that creates unreviewable diffs.-------## Summary of Changes from Current State--| Area | Before | After |-|------|--------|-------|-| Line length | Uncontrolled (up to 160) | 120, enforced by ruff |-| Import order | Ad-hoc | isort-grouped, enforced |-| Type syntax | Mixed `List`/`list`, sporadic `__future__` | Native `list[]`, `X \| None`, no `__future__` |-| Logging | ~80% `print()` | `logging` module everywhere |-| Error handling | 3 inconsistent patterns | Domain exceptions + route-layer HTTPException |-| Async CRUD | Fake `async def` | Sync functions (Phase 5) or real async |-| Linting | None | Ruff with auto-fix |-| Formatting | None | Ruff format (Black-compatible) |-| Tests | Mix of pytest + manual scripts | pytest throughout, shared conftest |+Introduce ruff fixes file-by-file as you touch them. Don't run `--fix` across the entire codebase in one shot -- that creates unreviewable diffs.