Installation Guide

Artifex supports CPU-first installation by default, with explicit extras for accelerator backends.

The PyPI distribution is named avitai-artifex; installed code is still imported as artifex.

Package users

CPU

pip install avitai-artifex

NVIDIA CUDA 12 on Linux

pip install "avitai-artifex[cuda12]"

This uses JAX's official pip-managed CUDA runtime. Artifex does not require /usr/local/cuda or manual LD_LIBRARY_PATH edits for this install path.

Apple Silicon Metal

pip install "avitai-artifex[metal]"

Optional extras

The base install carries the generative-model library only. Subsystems with their own dependencies ship behind extras:

Extra	Installs	Needed for
cli	typer	the artifex command and python -m artifex.cli
geometric	trimesh	the mesh datasets under artifex.benchmarks.datasets
benchmarks	cli, geometric, datasets, huggingface-hub	artifex.benchmarks
analysis	graphviz	artifex.generative_models.utils.code_analysis
logging	mlflow, wandb, tensorboard	the experiment trackers

Importing a subsystem without its extra raises an ImportError that names the extra:

pip install "avitai-artifex[cli,benchmarks]"

Repository developers

Artifex uses uv for all repo-maintained setup, sync, and test workflows.

Recommended setup

git clone https://github.com/avitai/artifex.git
cd artifex

# Auto-detect CPU, CUDA 12, or Metal policy
./setup.sh
source ./activate.sh

setup.sh writes a generated .artifex.env file. Optional .env and .env.local files are treated as user-owned override layers and are loaded after .artifex.env. Re-sourcing activate.sh refreshes the managed backend variables from .artifex.env before applying .env and .env.local. When the resolved backend is cuda12, activate.sh also removes inherited CUDA toolkit library directories from LD_LIBRARY_PATH so JAX uses its pip-managed runtime instead of stale system CUDA libraries.

Explicit backend selection

./setup.sh --backend cpu
./setup.sh --backend cuda12
./setup.sh --backend metal
source ./activate.sh

Recreate vs force-clean

# Rebuild the virtual environment and regenerate the managed backend file
./setup.sh --recreate

# Also remove repo-local test/coverage artifacts, but keep user-owned .env files
./setup.sh --force-clean

Direct uv sync

# CPU development
uv sync --extra dev --extra test

# Linux CUDA development
uv sync --extra cuda-dev

# Apple Silicon development
uv sync --extra dev --extra test --extra metal

Backend verification

uv run python scripts/verify_gpu_setup.py

# Require a working GPU backend
uv run python scripts/verify_gpu_setup.py --require-gpu

The verification script checks what JAX can actually use, not just what hardware exists.

Backend behavior

• CPU installs work everywhere JAX CPU wheels work.
• Linux CUDA installs rely on the NVIDIA driver plus the JAX-managed CUDA runtime from jax[cuda12].
• Metal installs are for Apple Silicon development.
• Artifex leaves JAX_PLATFORMS unset by default on GPU-capable environments so JAX can select GPU when available and CPU otherwise.
• If you want a CPU-only run on a machine with accelerators, set JAX_PLATFORMS=cpu for that command.

Troubleshooting

JAX falls back to CPU on Linux

Run:

uv run python scripts/verify_gpu_setup.py --json

If the default backend is still CPU, the usual problem is the NVIDIA driver or a driver/runtime mismatch. It is not fixed by editing LD_LIBRARY_PATH or installing a system CUDA toolkit.

You want to rebuild the repo environment

./setup.sh --recreate
source ./activate.sh