Skip to content

Production AI Systems·Lesson 66 of 67·expert

Packaging, dependency pinning and reproducibility

Declare dependencies in pyproject.toml, lock them so a build resolves identically in a year, and record the seeds, versions and data hashes that let somebody reproduce a number you reported.


In this lesson · 20 min

  • →Lay a project out so it is importable and installable
  • →Declare dependencies in pyproject.toml with honest constraints
  • →Explain the difference between a constraint and a lock
  • →Containerise a service so the image is reproducible
  • →Record what an experiment needs to be repeated

Everything in this module assumes the code you evaluated is the code that runs. That assumption holds only if you pin what it depends on.

Layout

PythonPython not started

pyproject.toml

PythonPython not started

The constraints say what the code is compatible with. >=2.7,<3 for Pydantic means “any 2.x from 2.7”, which lets a security fix in without letting a breaking 3.0 in.

Constraints are not a lock

PythonPython not started

A lock file records the resolution: every package, its exact version, and a hash of the artefact. It is generated, committed, and refreshed deliberately:

uv lock                     # resolve and write uv.lock
uv sync                     # install exactly what the lock says
uv lock --upgrade-package numpy   # move one dependency on purpose
# The pip equivalent, if you are not using uv:
pip-compile pyproject.toml -o requirements.lock
pip-sync requirements.lock

A reproducible image

FROM python:3.12-slim AS build
WORKDIR /app

# Copy only what the dependency layer needs, so it caches.
COPY pyproject.toml uv.lock ./
RUN pip install --no-cache-dir uv && uv sync --frozen --no-dev

COPY src/ ./src/
RUN uv pip install --no-deps .

FROM python:3.12-slim
WORKDIR /app
COPY --from=build /app/.venv /app/.venv
COPY --from=build /app/src /app/src
ENV PATH="/app/.venv/bin:$PATH" PYTHONUNBUFFERED=1

RUN useradd --create-home app && chown -R app /app
USER app

EXPOSE 8000
CMD ["uvicorn", "rag_service.api:app", "--host", "0.0.0.0", "--port", "8000"]

--frozen is the important flag: it fails the build if the lock file disagrees with pyproject.toml, rather than quietly re-resolving. And the key is not in the image — it arrives as an environment variable at run time, exactly as in module 2.

Versioning your own package

PythonPython not started

That last point is easy to miss. Prompts are not configuration you can edit silently — a downstream service parsing your refusal string breaks when you reword it.

Reproducing a result

PythonPython not started

Try it yourself

Exercise 1

Write satisfies(version, specifier) for specifiers like >=2.7,<3, and resolve(versions, specifier) returning the newest version that satisfies it.

Your turnPython not started
Exercise 2

Write manifest(result, **parts): build the record for a result, hashing the eval set from disk, and raise ValueError when any required part is missing.

Your turnPython not started

Check yourself

Your pyproject.toml pins nothing exactly, and an evaluation that scored 0.93 in January scores 0.88 in June with no code change. What is the likely cause?

Check yourself

Why does the src/ layout catch packaging mistakes that a flat layout hides?

Recap

  • src/ layout so tests import the installed package; commit the lock file, never the virtual environment.
  • pyproject.toml declares constraints — what you are compatible with. A lock file records a resolution, with exact versions and hashes.
  • uv lock / uv sync --frozen (or pip-tools) make a build reproduce; pip install -r with loose constraints does not.
  • Build images from the lock with --frozen, run as a non-root user, and pass secrets in at run time.
  • A prompt change is a behaviour change and belongs in the version and the changelog.
  • Record git sha, package version, model, prompt hash, eval-set hash, seeds and the lock hash beside every result you would quote.