# Setup and first run

## What you need

A browser reads the guide. To execute the labs, use a local Python 3.12 installation, a terminal and this extracted folder. CPython 3.12.14 on Linux x86_64 was used for verification. Python 3.12 is available from https://www.python.org/downloads/; installation details depend on your operating system. Use an official source. The course does not change your system Python, use a GPU or contact a paid service.

Open a terminal in the extracted `applied-ml-course` folder. Commands below are terminal commands, not code to paste into the Python REPL. A virtual environment isolates course packages. Initial installation needs internet; afterward the packaged data and scripts can run offline.

## macOS or Linux

```sh
python3 --version
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python tools/check_environment.py
.venv/bin/python examples/01_contract.py
```

If `python3 --version` does not report a Python 3.12 release, select the Python 3.12 executable you installed before creating the environment. Do not overwrite or remove an operating-system Python.

## Windows PowerShell

If the Python Launcher can find Python 3.12:

```powershell
py -3.12 --version
py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe tools\check_environment.py
.\.venv\Scripts\python.exe examples\01_contract.py
```

Use the explicit interpreter path; activation and execution-policy changes are unnecessary. These Windows/macOS commands were reviewed but not executed on those operating systems. Record your actual versions and any differences rather than assuming identical numerical bytes across platforms.

## The study loop

In later commands, `python` means the course environment's executable (`.venv/bin/python` or `.\.venv\Scripts\python.exe`). Replace it accordingly. Each example can run in a fresh process from this folder. No notebook kernel state is required.

```sh
python examples/02_provenance.py
python examples/03_splits.py
python examples/04_preprocessing.py
python examples/05_regression.py
python examples/06_classification.py
python examples/07_validation.py
python examples/08_calibration.py
python examples/09_errors.py
python examples/10_handoff.py
```

Read each matching lesson before running its example. `courseml/` contains the shared implementation; trace the named function when a short example imports it. The examples are small enough for an ordinary CPU. No runtime or memory promise has been established for every learner device. Every estimator and search runs with one job; numerical libraries may use their own threads. For tighter resource control on macOS/Linux, prefix a run with `OPENBLAS_NUM_THREADS=1 OMP_NUM_THREADS=1`.

## Independent practice

Finish `exercises/learner_functions.py`, then run `python check_learner.py`. Finish `exercises/capstone.py`, then run `python check_learner.py --capstone`. These load your file and will intentionally fail until you implement it. Passing the public checks is a smoke test, not a complete capstone grade. The written report, leakage reasoning and operational decision need the rubric and a human review.

After your pipeline/policy code and training-only selection are ready, run `python learner_run.py develop`. This runs your code and saves a separate `learner_outputs/frozen_plan.json`. Complete your decision record. Then run `python learner_run.py final` for your own frozen final evaluation. Set explicit seeds on stochastic learner estimators. Before opening the test, final reconstruction must reproduce the frozen policy-window classification probabilities and regression predictions within absolute/relative tolerance 1e-10. This guards accidental nondeterministic refits. Neither command automatically grades your report or protects against intentionally leaky learner code. The runner preplans sigmoid calibration and never calls your threshold selector on test rows.

## Reference development and the test boundary

After attempting the worked case, reproduce development with `python -m courseml.run_all`. It reads only train and validation CSVs, writes fold metrics and a frozen plan, and does not open the test CSV. Review the reference choices and write your own decision record before the final reveal.

Only then run `python -m courseml.final_evaluation`. It validates the frozen code/development-data hashes, reconstructs the exact frozen models without a search, and evaluates the future test. It does not refit on validation, because the calibration and threshold were selected for the train-fitted predictor. A different final training strategy would need its own evaluation design.

The final script's guard prevents accidental code/data drift; it is not an access-control system. Running development again can rewrite the freeze. Do not interpret this as permission to repeatedly tune against the visible test. Preserve your first results and label any later test-informed changes exploratory. The bundled reference outputs are already filled in for checking, including final-test spoilers; you can postpone opening those files until your first evaluation.

## Regeneration and verification

`python -m courseml.data` regenerates the four supplied CSVs from the documented seed. It overwrites only those course data files. Do not run it on your own imported data. `python -m unittest discover -s tests -v` validates the reference implementation. It reads the reference test partition to check invariants; wait until the final reveal if you are preserving a strict learner test boundary. Run the tests after reproducing the reference evaluation.

## Troubleshooting

A missing package usually means the command used a different interpreter from the one you installed into. Use the full environment path. A file-not-found error usually means the course folder was only partly extracted; modules resolve data relative to their own location. `No module named courseml` when using `-m` means the terminal is not in the course root. A freeze mismatch means source or development data changed; document a new experiment rather than suppressing the check. A convergence warning needs investigation, not automatic acceptance; none should occur in the tested reference runs.

The public Aabha browser lab has not been verified for scikit-learn 1.8, these module imports or the CPU workload. This package therefore does not claim a browser-only execution route. The guide itself has no network scripts or embedded trackers.