Usage

Run the training pipeline

Run all stages end-to-end via DVC (respects the dependency graph and caches unchanged stages) and push the generated artifacts to DagsHub:

dvc repro
dvc push -r origin

Or run an individual stage directly:

python -m churn_prediction.pipelines.training_pipeline <stage>

Available stages: ingest-data, validate-raw, preprocess-raw, validate-train, validate-val, train-model, all.

Serve the prediction API

just serve

This starts the FastAPI app (default http://localhost:8000, docs at /docs).

Key endpoints:

Method	Endpoint	Description
GET	/health	Reports encoder/model load status and memory usage
POST	/api/v1/predict/batch	Upload a CSV file to generate batch predictions
GET	/api/v1/predictions/download/{batch_id}	Download predictions for a batch
POST	/explain/{batch_id}	Generate SHAP explainability artifacts for a batch

See the API Reference for full route and dependency documentation.

Launch the dashboard

churn-prediction

This starts the Streamlit application (talks to the FastAPI service configured via API_BASE_URL) for uploading data, reviewing predictions, and exploring SHAP-based risk drivers.

Maintenance & Dependency Management

just lock           # Upgrade all project lockfile dependencies via uv
just hooks-update   # Autoupdate pre-commit hook repositories
just hooks-run      # Run pre-commit checks across all staged/unstaged files

Testing & Quality

just test          # Run the pytest suite with coverage reporting

# Or use command without just
uv run pytest -v

Linting is handled by ruff, type checking by ty, and Containerfiles are validated with hadolint. A pytest suite (unit, integration, e2e) with an 85% coverage gate is configured in pyproject.toml.

Documentation

just docs-serve    # Serve locally with live reload at http://127.0.0.1:5050
just docs-deploy   # Publish the documentation to GitHub Pages

# Without just command
uv run mkdocs serve -a 127.0.0.1:5050 --strict
uv run mkdocs gh-deploy

Cleanup

just clean-cache      # Remove Python, pytest, ruff, mypy, pyright, and build caches, and the generated docs site
just clean-logs       # Remove log files in logs directory
just clean-generated  # Remove generated models, datasets, and SHAP/training reports
just clean-all        # Execute clean-cache, clean-generated, and clean-logs

just clean-container  # Prune Podman containers, volumes, and images