DJ Set Planner

Optimization tool that reorders a playlist into a DJ set with smooth transitions and an intentional energy flow. A scoring function rates a candidate ordering (lower = better); optimization algorithms minimize that score.

University assessment project covering an AI module (SE_14) and a Testing module (SE_10).

Components

• Scoring — pure-function penalties for harmonic flow (Camelot wheel), tempo flow (BPM difference), and energy-shape deviation, combined into a weighted composite score.
• Algorithms — simulated annealing (primary optimizer), random shuffle and greedy nearest-neighbor as baselines.
• Data — Track dataclass plus loaders; the dataset/ folder holds CSV input.

The full specification lives in docs/dj-set-planner.md.

Requirements

• Python 3.10+

Install

python -m venv venv
source venv/bin/activate
pip install -e ".[dev]"

Run tests

pytest                                              # full suite
pytest --cov=scoring --cov=algorithms --cov=data    # with coverage
pytest tests/test_camelot.py -v                     # one module

Target coverage on scoring and algorithm modules: >85%.

Lint and type-check

ruff check .
mypy scoring algorithms data

Project layout

scoring/      Camelot, tempo, energy and composite scorer
algorithms/   simulated annealing and baseline optimizers
data/         Track model and dataset loaders
dataset/      Input CSVs
tests/        pytest suite
docs/         Specification and roadmap
notebooks/    Jupyter experiments (import from modules; no logic in notebooks)