azureml-scaffolding

AzureML Project Scaffolding

A battle-tested structure for AI projects that require reproducible experimentation, leveraging AzureML for cloud execution. It ensures reproducibility from day one without sacrificing the path to production — and without breaking the ability to keep experimenting once you're there. Code, environments, specs, and dependencies are wired so that what runs locally runs on [AzureML][aml], with no surprises.

Principles

These principles are foundational. Every decision about project structure, tooling, or workflow must be evaluated against them.

• Three layers — Each layer depends only on inner layers:

  1. Code — the what. Pure Python, no platform deps.
  2. Specification — the how. job YAML. Declares how code executes on a target platform. Lives next to the code it describes.
  3. Orchestration — the when. Makefile, CI. Triggers execution. Knows about specs, knows nothing about code internals.

  Litmus test — If Python code imports or shells out to anything platform-specific (az, mlflow.register_model, endpoint APIs), it has escaped the Code layer. If a job YAML knows about scheduling, version registration, or what happens after the job finishes, it has escaped the Specification layer. Push the concern up to the next layer. Every generated or modified file must respect this layering — never merge concerns across layers even when it seems expedient.

• One mental model — Everything is a package: a [uv workspace][uv-workspace] member with its own [pyproject.toml][pyproject-toml], [[build-system]][build-system], [src layout][src-layout], source, tests, and dependencies. Same structure, same commands, everywhere.

  src/my_package/
  ├── pyproject.toml       # deps, metadata, [build-system]
  ├── aml-job.yaml         # aml spec (if executable, optional)
  ├── src/my_package/       # package source (src layout)
  │   ├── __init__.py
  │   └── __main__.py       # entry point (if executable, optional)
  └── tests/