Package Management with `uv`¶

This project uses uv as its Python package manager. It replaces pip + requirements.txt with pyproject.toml + uv.lock for reproducible, fast builds.

Prerequisites¶

Install uv on your machine:

curl -LsSf https://astral.sh/uv/install.sh | sh

Verify:

uv --version

Project Structure¶

KubeIntellect/
├── pyproject.toml      # dependency declarations (edit this, not requirements.txt)
├── uv.lock             # auto-generated lock file — commit this, never edit manually
├── .python-version     # pins Python version (3.12)
└── .venv/              # local virtual environment — gitignored

First-Time Setup (new machine / fresh clone)¶

# Install all deps (prod + dev) and create .venv automatically
uv sync

That's it. uv reads pyproject.toml and uv.lock, creates .venv/, and installs everything.

Daily Commands¶

Activate the virtual environment (optional)¶

source .venv/bin/activate   # Linux/macOS
.venv\Scripts\activate      # Windows

Or skip activation entirely and prefix commands with uv run:

uv run pytest
uv run uvicorn app.main:app --reload

Add a production dependency¶

uv add fastapi
uv add "langchain>=0.3"

Add a development-only dependency¶

uv add --dev pytest
uv add --dev ruff

Remove a dependency¶

uv remove requests

Upgrade a specific package¶

uv lock --upgrade-package langchain
uv sync

Upgrade all packages (within declared version bounds)¶

uv lock --upgrade
uv sync

Dependency Groups¶

Dependencies are split into groups in pyproject.toml:

Group	Purpose	Installed in Docker prod?
`dependencies`	Production runtime	Yes
`dev`	Testing, linting, local tools	No

Install only production deps:

uv sync --no-dev

Install everything including dev:

uv sync

Docker¶

The Dockerfile uses uv with these important flags:

RUN uv sync --frozen --no-dev --no-install-project

Flag	Meaning
`--frozen`	Fail if `uv.lock` is out of sync with `pyproject.toml` — catches drift in CI
`--no-dev`	Skip dev dependencies (`pytest` etc.) — keeps the image lean
`--no-install-project`	Don't install the project itself, only its dependencies (faster layer cache)

To rebuild after changing dependencies:

docker build -t kubeintellect .

CI / Production Rules¶

Always commit uv.lock to git. It is the single source of truth for exact resolved versions.
Never edit uv.lock by hand. Let uv lock regenerate it.
Never pin with == in pyproject.toml — use >= floors and let the lock file handle exact pinning.
The Docker build uses --frozen, so if you change pyproject.toml without running uv lock, the build will fail intentionally.

Troubleshooting¶

Lock file is out of date¶

uv lock
uv sync

Dependency conflict¶

uv lock --upgrade   # try re-resolving everything

Clean reinstall¶

rm -rf .venv
uv sync

Check what is installed¶

uv pip list

Show dependency tree¶

uv tree

Package Management with uv¶