tigerflow-ml

ML tasks for TigerFlow — private cloud ML APIs on HPC infrastructure.

Installation

pip install tigerflow-ml

If using a task that relies on vllm (chat, OCR, or translation), install with:

pip install tigerflow-ml[vllm]

Tasks

Each task provides both a Slurm variant (for HPC) and a Local variant (for development).

Usage

After installation, tasks are automatically discoverable via:

tigerflow tasks list

Run a task directly:

python -m tigerflow_ml.image.ocr.slurm --help
python -m tigerflow_ml.text.translate.slurm --help
python -m tigerflow_ml.multimodal.chat.slurm --help
python -m tigerflow_ml.audio.transcribe.slurm --help
python -m tigerflow_ml.image.detect.slurm --help
python -m tigerflow_ml.multimodal.embed.slurm --help

Container

A GPU image with all tasks (including the vllm extra) is published to GHCR on each release:

docker pull ghcr.io/princeton-ddss/tigerflow-ml:latest

The image bundles its own CUDA libraries, so only the host NVIDIA driver is needed at runtime — pass --gpus all (Docker) or --nv (Apptainer). Models are fetched on first use; mount a cache at /cache to persist them.

The entrypoint is tigerflow, so arguments are passed straight to the CLI:

# Run a pipeline (config file + input/output directories)
docker run --gpus all -v "$PWD/cache:/cache" -v "$PWD:/data" \
  ghcr.io/princeton-ddss/tigerflow-ml:latest \
  run /data/pipeline.yaml /data/input /data/output

# List available tasks
docker run ghcr.io/princeton-ddss/tigerflow-ml:latest tasks list

# Run a single task module directly (override the entrypoint)
docker run --gpus all -v "$PWD/cache:/cache" -v "$PWD:/data" \
  --entrypoint python ghcr.io/princeton-ddss/tigerflow-ml:latest \
  -m tigerflow_ml.audio.transcribe.local --help

On HPC, convert to a Singularity/Apptainer image:

apptainer build tigerflow-ml.sif docker://ghcr.io/princeton-ddss/tigerflow-ml:latest
apptainer run --nv -B ./cache:/cache tigerflow-ml.sif run pipeline.yaml input output
apptainer exec --nv tigerflow-ml.sif python -m tigerflow_ml.audio.transcribe.local --help

Development

uv sync --group dev
uv run pre-commit run --all-files
uv run pytest tests