preflight-scripts

Preflight script conventions

When creating or editing preflight_<slug>.py under any model's examples/ directory:

Required pattern

Use the standard check() helper with colored PASS/FAIL output:

PASS = "\033[32mPASS\033[0m"
FAIL = "\033[31mFAIL\033[0m"
errors = 0

def check(label, fn):
    global errors
    try:
        result = fn()
        print(f"[{PASS}] {label}" + (f": {result}" if result else ""))
    except Exception as exc:
        print(f"[{FAIL}] {label}: {exc}")
        errors += 1

Required checks (in order)

1. import torch — Report version
2. GPU accessible — torch.cuda.is_available() must be True; report device name
3. GPU tensor ops — Create a tensor on GPU, do a matmul, report result
4. Model-specific imports — Import the key packages the model needs
5. Optional deps — Use try/except and report "not installed (optional)" rather than failing

--dry-run (required)

CPU CI and make check invoke python preflight_<slug>.py --dry-run. That flag must exit 0 without importing torch or touching a GPU. Use it to confirm the script is present and parseable; full GPU checks remain the default (no flag).

if "--dry-run" in sys.argv:
    print("dry-run: skipping GPU and import checks")
    raise SystemExit(0)

Exit code

Exit with code 1 if any required check failed; 0 if all passed. Print a summary line at the end.

Naming

File: preflight_<slug>.py where <slug> matches the model folder name (lowercase, hyphens to underscores).