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
pyproject.toml
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
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
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
Try it yourself
Write satisfies(version, specifier) for specifiers like >=2.7,<3, and resolve(versions, specifier) returning the newest version that satisfies it.
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.
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.tomldeclares 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 -rwith 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.