Installation¶

Prerequisites¶

Python 3.12 or later
An NVIDIA GPU with drivers installed (required for local SGLang-backed LLM inference; not needed for the batch_api processor)
NVIDIA Container Toolkit (required only for GPU Docker usage)

From Source (recommended)¶

Clone the repository, create a virtual environment with uv, and install the base package:

git clone git@github.com:EPFLiGHT/MMIRAGE.git
cd MMIRAGE
uv venv
source .venv/bin/activate
uv pip install -e .

The base install provides all core functionality except local GPU inference.

GPU / Local Inference¶

To run pipelines locally using the SGLang-backed llm processor, install the gpu extra. It is strongly recommended to install PyTorch matching your CUDA version before running this step:

pip install -e ".[gpu]"

This installs sglang, sgl_kernel, xgrammar, and compressed_tensors.

Docker¶

Prebuilt images are published to GHCR for every push to main.

GPU image¶

docker pull ghcr.io/epflight/mmirage:latest-gpu
docker run --rm -it --gpus all ghcr.io/epflight/mmirage:latest-gpu

The host must have NVIDIA GPU drivers, the NVIDIA Container Toolkit, and a recent Docker Engine with GPU support.

To build locally:

docker compose build mmirage
docker compose run --rm -it mmirage

CPU image¶

Suitable for workflows that do not require a local GPU (e.g. the batch_api processor):

docker pull ghcr.io/epflight/mmirage:latest-cpu
docker run --rm -it ghcr.io/epflight/mmirage:latest-cpu

To build locally:

docker compose build mmirage-cpu
docker compose run --rm -it mmirage-cpu

Environment Variables¶

Several features rely on environment variables (e.g. HF_TOKEN for private HuggingFace models, SLURM_* variables injected by the scheduler). A helper script generates a .env starter file:

./scripts/generate_env.sh

Key variables:

Variable	Description
`HF_TOKEN`	HuggingFace API token for gated/private models
`HF_HOME`	HuggingFace cache directory (default: `~/hf`)
`SLURM_ARRAY_TASK_ID`	Shard ID injected automatically in SLURM array jobs
`SLURM_GPUS_ON_NODE`	Used to auto-detect `tp_size` for SGLang
`MMIRAGE_COLLECT_STATS`	Set to `1` to enable GPU/throughput benchmarking

Development Setup¶

Install linters, type checkers, and test dependencies:

pip install -e ".[dev]"

Run the test suite:

pytest tests/

Lint and format the codebase with Ruff (via pre-commit, same as CI):

pre-commit run --all-files

Or invoke Ruff directly:

ruff check --fix .
ruff format .

Verifying the Installation¶

mmirage --help