# Coding Standards & Architecture Constraints This document defines the coding standards, project invariants, and architectural anti-patterns enforced in **RLD UVR-Opt**. --- ## 1. Technical Invariants & Anti-Patterns ### A. Deferred & Lazy Imports Heavy machine learning dependencies (`torch`, `onnxruntime`, `tensorrt_rtx`) must **not** be imported at module root level during application startup. Importing heavy DLLs during root load slows down CLI command dispatch (`uvr_cli --help`, `list-models`) and causes unnecessary cold-start latency. #### Bad (Root-Level Eager Import) ```python # BAD: Imported when module is evaluated, slowing CLI launch import torch import onnxruntime as ort def process_audio(audio_path: str) -> None: session = ort.InferenceSession("model.onnx") ... ``` #### Good (Deferred Local Import) ```python # GOOD: Imports are deferred until the inference function is actually called def process_audio(audio_path: str) -> None: import torch import onnxruntime as ort from engine.tensorrt_rtx.session import create_trt_rtx_session session = create_trt_rtx_session("model.onnx") ... ``` --- ### B. Context Lock Prevention Initializing CUDA context or calling `torch.cuda.init()` in the main thread before Execution Provider resolution locks GPU device context. This can cause ONNX Runtime providers (especially TensorRT) to fail or run into resource contention. #### Bad (Premature CUDA Initialization) ```python # BAD: Eagerly queries device before user or CLI arguments select EP device = "cuda:0" if torch.cuda.is_available() else "cpu" torch.cuda.init() ``` #### Good (Deferred Device Binding) ```python # GOOD: Defer device context initialization until model session is instantiated def resolve_inference_device(device_arg: str) -> str: # Validate string argument without initializing CUDA driver context if device_arg.startswith("cuda") or device_arg.startswith("trt_rtx"): return device_arg return "cpu" ``` --- ### C. Pure Pipeline Decoupling Inference routines in `separate.py`, `engine/tensorrt_rtx/`, and `uvr_cli/` must remain completely decoupled from GUI presentation widgets (Tkinter, `ttk`). - **Forbidden**: Passing `tk.Tk`, `ttk.Progressbar`, or referencing GUI global state inside model runner functions. - **Allowed**: Standard function signatures accepting primitive arguments (`str`, `Path`, `float`, `int`, `dict`) and reporting progress through callable callbacks: ```python def run_separation( audio_path: Path, model_path: Path, progress_callback: Optional[Callable[[float, str], None]] = None, ) -> Tuple[Dict[str, np.ndarray], bool]: ... if progress_callback: progress_callback(0.5, "Processing chunk 2/4...") ``` --- ### D. PowerShell Invariants & Error Handling All scripts in [install/](../../install/) must maintain strict compatibility with **Windows PowerShell 5.1**: 1. **Strict Mode**: Every `.ps1` file must begin with: ```powershell Set-StrictMode -Version Latest ``` 2. **Native Process Invocation**: Every external command (`python.exe`, `uv.exe`, `git.exe`) must verify exit codes: ```powershell # Use the shared Invoke-Native helper or check $LASTEXITCODE explicitly $res = Invoke-Native -FilePath 'uv.exe' -ArgumentList @('pip', 'install', '-r', $reqFile) if (-not $res.Success) { throw "Command failed with exit code $($res.ExitCode): $($res.StdErr)" } ``` 3. **No PS7 Syntactic Sugar**: Do not use PowerShell 7+ features: - Ternary operator (`?:`) → use `if (...) { } else { }`. - Null-coalescing (`??`) → use `if ($null -eq $x) { $x = ... }`. - Pipeline chaining (`&&`, `||`) → use explicit conditional statements. 4. **Encoding**: Save PowerShell scripts as UTF-8 without BOM or ASCII. --- ### E. Installer Architectural Invariants 1. **Zero Side-Effects in Early Phases**: - `Detect.ps1` (Phase 1), `Plan.ps1` (Phase 2), and `Verify.ps1` (Phase 3) must be strictly read-only. - `-DryRun` must exit at Phase 3 with zero modifications to filesystem, registry, or environment. 2. **Single Source of Truth**: - All version pins (PyTorch, ONNX Runtime, plugins, driver thresholds) must reside exclusively in [install/lib/Config.ps1](../../install/lib/Config.ps1). 3. **Additive Record Schema**: - Changes to [install/install_record.json](../../install/install_record.json) must be purely additive to preserve backward compatibility with `install_record.py inspect-stack`. 4. **No Silent EP Fallbacks**: - Inference sessions must explicitly inspect `session.get_providers()` and log the active provider. --- ## 2. Python Code Standards - **Formatting**: Adhere to PEP 8 with 4-space indentation. - **Type Annotations**: Provide type hints for public module functions and classes. - **Logging vs Print**: In library code (`engine/`, `uvr_cli/`), use structured logging or verbose flags rather than raw `print()` statements. - **Error Handling**: Catch specific exceptions rather than bare `except:`. Provide descriptive error messages. --- ## 3. Git Commit & Branch Conventions ### Commit Messages We follow the [Conventional Commits](https://www.conventionalcommits.org/) specification: ```text (): [optional body explaining context and rationale] [optional footer(s)] ``` #### Allowed Types: - `feat`: A new feature (e.g., new Execution Provider, CLI flag). - `fix`: A bug fix (e.g., resolver error, memory leak). - `docs`: Documentation updates. - `refactor`: Code restructuring without functional changes. - `perf`: A code change that improves performance. - `test`: Adding or correcting tests. - `chore`: Maintenance tasks (release metadata, config updates). #### Example: ```text feat(engine): add Ampere architecture guard for TensorRT-RTX - Check compute capability >= 8.0 via pynvml - Fall back gracefully to CUDAExecutionProvider on Turing GPUs - Add unit test coverage in tests/test_tensorrt_rtx.py ``` ### Branch Naming - Features: `feat/` - Bugfixes: `fix/` - Documentation: `docs/`