Installation¶

This guide covers setting up AirSense ML for local development.

Prerequisites¶

git clone https://github.com/chitrank2050/airsense-ml.git
cd airsense-ml

make init

This creates .venv/ using Python 3.12. If you have a .python-version file it reads the version from there.

Full install (local development — includes training tools):

uv sync --all-groups

This installs:

Production deps — FastAPI, scikit-learn, XGBoost, LightGBM, Loguru, Pydantic
Training group — MLflow, Optuna, SHAP, Matplotlib, Seaborn
Dev group — Ruff, pre-commit, Jupyter, questionary

Production only (API serving, no training tools):

make install-prod

uv run pre-commit install
uv run pre-commit install --hook-type commit-msg

This installs: - Ruff linting and formatting on every commit - Conventional commit message enforcement

cp .env.example .env.dev

Open .env.dev — defaults work for local development. No changes required to get started.

Download the Delhi AQI dataset from Kaggle:

Place the CSV file in data/raw/:

data/raw/kaggle_delhi_ncr_aqi_dataset.csv

uv run dvc add data/raw
git add data/raw.dvc data/.gitignore
git commit -m "chore: track raw data with DVC"

make tree        # check project structure
make train       # run training pipeline
make api         # start API server

If all three run without errors — installation is complete.

zsh: command not found: dvc

DVC is installed in the virtual environment. Use uv run dvc or activate the venv:

source .venv/bin/activate

brew install libomp required on macOS

LightGBM requires OpenMP on macOS:

brew install libomp

ModuleNotFoundError: No module named src

Make sure you're running from the project root, not inside src/:

cd airsense-ml
uv run python -m src.models.train