Files
RLD-UVR-Opt/docs/development/coding-standards.md
T

6.0 KiB

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)

# 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)

# 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)

# 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)

# 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:
    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/ must maintain strict compatibility with Windows PowerShell 5.1:

  1. Strict Mode: Every .ps1 file must begin with:
    Set-StrictMode -Version Latest
    
  2. Native Process Invocation: Every external command (python.exe, uv.exe, git.exe) must verify exit codes:
    # 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.
  3. Additive Record Schema:
    • Changes to 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 specification:

<type>(<scope>): <short description in imperative mood>

[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:

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/<feature-name>
  • Bugfixes: fix/<bug-name>
  • Documentation: docs/<doc-name>