3.85 GB
70,867 files
Updated 17 days ago
Name
Size
uvbin.py2.48 kB
xet
util.py7.77 kB
xet
spec.py19.8 kB
xet
sparkdeps.py7.62 kB
xet
nodejs.py8.09 kB
xet
migrations.py943 Bytes
xet
launch.py3.32 kB
xet
gitwin.py2.86 kB
xet
gitops.py2.51 kB
xet
ffmpeg.py6.36 kB
xet
env.py25.6 kB
xet
doctor.py5.6 kB
xet
detect.py3.71 kB
xet
__main__.py8.66 kB
xet
__init__.py279 Bytes
xet
README.md6.27 kB
xet
README.md

AI Toolkit Manager

Self-contained install/update manager for this checkout of AI Toolkit. Runs with any Python >= 3.8 and no dependencies, so it works before the training environment exists.

python3 -m manager install     # first-time setup: venv + torch + requirements
python3 -m manager check       # is an update available / are deps out of sync?
python3 -m manager update      # git pull, then sync deps + run migrations
python3 -m manager launch      # start the web UI (http://localhost:8675)
python3 -m manager doctor      # diagnose problems

Design

  • The install logic lives in the repo it installs. Every commit knows how to install itself; external frontends (the desktop launcher, install.sh, install.ps1) just shell out to this CLI and stay dumb. Machine-readable output via check --json / detect --json.
  • Hardware → spec mapping is in spec.py. One universal torch pin (2.13.0 / torchvision 0.28.0 / torchaudio 2.11.0) on every platform: cu130 wheels when the driver supports CUDA 13 (cu126 fallback for older drivers, refused outright on Blackwell GPUs which need cu130), same stack + Python 3.11 + dgx_requirements.txt on DGX/Grace, PyPI wheels on Mac, rocm7.1 (experimental) for AMD, --cpu to force a CPU install. Torch pins there must be updated together with the README install instructions, run_mac.zsh, and dgx_instructions.md.
  • Accelerators everywhere wheels exist, via per-spec extra_packages (installed after requirements with --upgrade so they override pins) and optional_packages (installed one-by-one, warn-only on failure): torchcodec==0.15.0 on all platforms; flash-attn 2.8.3 prebuilt wheels (mjun0812) on Linux x86_64/aarch64 + Windows; NATTEN 0.21.7 wheels (whl.natten.org) on Linux both arches; triton bundled with torch on Linux and triton-windows 3.7.x on Windows. No flash-attn/NATTEN/triton on Mac, no NATTEN on Windows (no wheels exist).
  • The torch stack is pinned against the resolver. torch is an unpinned transitive dep of timm/peft/accelerate/torchvision, so anything in requirements*.txt that conflicts with what the pinned torch needs makes the resolver silently backtrack to an older torch rather than fail — and prebuilt accelerator wheels then reinstall a plain PyPI torch over the GPU one, leaving torchvision/torchaudio's C++ extensions linked against a libtorch that is gone. Every install pass after torch therefore carries a generated constraints file (torch==X+cu130, ...) plus per-package --find-links to the pytorch index, and _verify_torch re-checks (and repairs) the trio before the optional accelerators are import-tested and again at the end. Requirements files must never pin a torch dependency below what torch needs (torch 2.13 wants setuptools>=77.0.3).
  • ui/package-lock.json is never modified by installing. A plain npm install re-derives the lockfile for whichever machine runs it — on Windows it strips the libc fields off the Linux-only optional binaries (@next/swc-linux-*, rollup, lightningcss), on Linux it adds them back — so with the install baked into npm run build_and_start every user got a dirty tree on every launch, which then blocks manager update (a dirty tree aborts the pull). nodejs.ensure_ui_deps owns the install instead: npm install --no-save, gated on a hash of ui/package.json + ui/package-lock.json (stored in the venv state), with the lockfile bytes snapshotted and restored either way. manager launch therefore runs npm run db_build_start, not build_and_start; the latter still exists for the manual cd ui && npm run build_and_start flow in the README and calls the same non-writing install via npm run install_deps.
  • Nothing global is ever installed. FFmpeg (shared builds — the libs torchcodec dlopens) goes to .ffmpeg/ (ffmpeg.py), Node (when the system lacks >= 20) to .node/ (nodejs.py), the uv binary (when absent) to .uv/ (uvbin.py) with uv-managed Pythons kept in .uv/python/ via UV_PYTHON_INSTALL_DIR, and on Windows without git, portable MinGit to .mingit/ (gitwin.py) — all inside the repo and gitignored. The first clone on a git-less Windows box is handled by the bootstrap layer (install.ps1 / desktop launcher), which downloads MinGit itself and moves it into the checkout afterwards. manager launch puts them on PATH (and LD_LIBRARY_PATH on Linux) for the whole UI/training process tree, and a generated sitecustomize.py in the venv exposes ffmpeg to any direct use of the venv python (plus os.add_dll_directory on Windows).
  • Hostile-environment hardening (learned from the community Windows installer): every python/pip subprocess runs with PYTHONPATH/PYTHONHOME/ CONDA/PYENV/PIP_* scrubbed from the env; git runs with GIT_LFS_SKIP_SMUDGE=1; git-pinned requirements (diffusers) are force-reinstalled when requirements change since pip skips unchanged version numbers; launch polls the UI port and opens the browser when ready (--no-browser to disable, auto-skipped on headless boxes).
  • uv is used when present (fast installs, auto-downloads the right Python); plain venv + pip otherwise. The venv is created at .venv/ (an existing venv/ is also respected, matching ui/cron/pythonPath.ts).
  • State (requirements hash, applied migrations) lives inside the venv (aitk_manager_state.json) — deleting the venv resets everything.
  • Update flow: update pulls fast-forward only, then re-execs python -m manager sync so the freshly pulled manager code — not the stale in-memory copy — performs its own dependency sync and migrations. Local work is never overwritten: a dirty tree aborts the update by default (untracked files don't count), --auto (used by the run_* scripts) warns and skips the pull instead so launching still works, and there is no reset/clean anywhere — even --force relies on git itself refusing to clobber modified files.
  • Migrations (migrations.py): one-time post-update steps, each applied at most once per environment.
Total size
3.85 GB
Files
70,867
Last updated
Nov 3
Pre-warmed CDN
US EU US EU

Contributors