Install Python and Create a Reproducible Project

A reproducible Python project records its required Python version, dependencies, and lockfile instead of relying on whatever happens to be installed globally. We will use uv to manage those pieces, isolate packages in .venv, and verify the toolchain before adding FastAPI or application code.

What will you be able to do?

verify Python and uv rather than guessing whether installation worked;
initialize a package with recorded dependencies;
explain the purpose of pyproject.toml, .venv, and the lockfile;
reproduce the environment on another machine.

What is the mental model?

pyproject.toml declares intent. The lockfile records exact resolution. .venv contains installed packages for this project. Source files contain your code. Only the declaration, lockfile, and source belong in Git; the environment is recreated.

Use the official uv installation guide for your operating system, then verify:

bash

uv --version
uv python install 3.12
uv init --package supportdesk-ai
cd supportdesk-ai
uv python pin 3.12
uv add fastapi 'uvicorn[standard]'
uv add --dev pytest httpx ruff mypy
uv run python --version
uv run python -c 'import fastapi; print(fastapi.__version__)'

Version numbers change; the successful imports and lockfile are the evidence. Do not copy a global pip install command into an unknown interpreter.

What should the project contain?

text

supportdesk-ai/
├── .python-version
├── pyproject.toml
├── uv.lock
├── src/supportdesk_ai/__init__.py
└── tests/

Inspect pyproject.toml. The dependency declaration should name FastAPI and Uvicorn; development dependencies should include test and quality tools.

Reproduce from the lockfile:

bash

uv sync --frozen
uv run pytest

--frozen refuses to silently change dependency resolution. That behavior is valuable in CI.

Why does this matter in AI-native systems?

Model SDKs and orchestration libraries change quickly. Unbounded dependencies create surprise behavior and security risk. Keep the integration surface small, wrap providers behind your own interfaces, review lockfile changes, and automate vulnerability updates without merging them blindly.

Common mistakes

Symptom	Likely cause	Fix
Import works in one terminal only	Different interpreter or environment	Prefix commands with uv run
CI resolves newer packages	Lockfile ignored or not frozen	Commit uv.lock; use uv sync --frozen
Huge repository	.venv committed	Remove it from tracking and ignore it
Tutorial command differs	Tool version changed	Check official docs and --help; preserve the intent

AI Pair-Programmer Prompt

text

Audit this pyproject.toml and lockfile diff. Classify runtime versus development
dependencies, identify unnecessary AI framework coupling, flag risky version jumps,
and give exact import/test commands. Do not propose global installation.

Exercise

Clone or copy only the declarations and source into a new temporary directory, run uv sync --frozen, and execute the import verification.

Acceptance criteria: the second environment succeeds without copying .venv; its locked package versions match the first.

Knowledge check

Which file declares direct dependencies?
Why is .venv not committed?
What guarantee does a frozen sync seek?

Answers

pyproject.toml.
It is machine-specific generated state that can be recreated.
Installation must use the existing lock resolution without silently modifying it.

Completion checklist

uv run python --version reports Python 3.12 or later.
FastAPI imports inside the project environment.
The lockfile exists and frozen sync succeeds.

Primary references

What is the mental model?

Use the official uv installation guide for your operating system, then verify:

bash

uv --version
uv python install 3.12
uv init --package supportdesk-ai
cd supportdesk-ai
uv python pin 3.12
uv add fastapi 'uvicorn[standard]'
uv add --dev pytest httpx ruff mypy
uv run python --version
uv run python -c 'import fastapi; print(fastapi.__version__)'

Version numbers change; the successful imports and lockfile are the evidence. Do not copy a global pip install command into an unknown interpreter.

What should the project contain?

text

supportdesk-ai/
├── .python-version
├── pyproject.toml
├── uv.lock
├── src/supportdesk_ai/__init__.py
└── tests/

Inspect pyproject.toml. The dependency declaration should name FastAPI and Uvicorn; development dependencies should include test and quality tools.

Reproduce from the lockfile:

bash

uv sync --frozen
uv run pytest

--frozen refuses to silently change dependency resolution. That behavior is valuable in CI.

Common mistakes

Symptom	Likely cause	Fix
Import works in one terminal only	Different interpreter or environment	Prefix commands with uv run
CI resolves newer packages	Lockfile ignored or not frozen	Commit uv.lock; use uv sync --frozen
Huge repository	.venv committed	Remove it from tracking and ignore it
Tutorial command differs	Tool version changed	Check official docs and --help; preserve the intent

AI Pair-Programmer Prompt

text

Audit this pyproject.toml and lockfile diff. Classify runtime versus development
dependencies, identify unnecessary AI framework coupling, flag risky version jumps,
and give exact import/test commands. Do not propose global installation.