managed-portal/managed/people_flow_project/docs/plans/2026-04-08-offline-wheelhouse-design.md

Offline Wheelhouse Design

Date: 2026-04-08

Goal: Add an offline Python dependency bundle for Ubuntu 24.04 x86_64 with Python 3.12 and NVIDIA GPU support so the project can be installed on similar machines without re-downloading PyTorch, TensorFlow, and application wheels.

Scope

• Target platform: Ubuntu 24.04 x86_64
• Python version: 3.12
• GPU runtime: NVIDIA, using CUDA-enabled PyTorch wheels
• Bundle type: project code + weights + wheelhouse/
• Setup behavior: prefer offline wheels when present, fall back to network otherwise

Approach

Add a dedicated wheelhouse build script that downloads:

• pip, setuptools, wheel
• numpy<2
• CUDA-enabled torch and torchvision
• tensorflow[and-cuda]==2.16.1
• tf-keras==2.16.0
• project requirements and their transitive dependencies

Store the wheels inside wheelhouse/ under the project root.

Update the native setup script so it:

1. creates .venv
2. upgrades installer tooling from wheelhouse/ when available
3. installs PyTorch and TensorFlow from local wheels when available
4. installs project requirements from local wheels when available
5. falls back to online indexes only if the wheelhouse is missing

Bundle Layout

• weights/
• wheelhouse/
• setup_native_venv.sh
• build_wheelhouse.sh
• run_rtsp.sh

Tradeoff

This increases the lightweight bundle size, but it removes repeat dependency downloads on future hosts. The user explicitly asked for an offline dependency pack, so this is the right tradeoff now.