add: uv

.dockerignore

@@ -3,7 +3,6 @@
 *.md
 *.log
 Makefile
-pyproject.toml
 
 __pycache__/
 .DS_Store/

.github/workflows/test.yml

@@ -11,24 +11,19 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
-
   lint-and-test:
     runs-on: ubuntu-latest
     steps:
       - name: Check out repository code
         uses: actions/checkout@v6
-      - name: Set up Python
-        uses: actions/setup-python@v6
+      - name: Install uv and set up Python
+        uses: astral-sh/setup-uv@v7
         with:
-          python-version: '3.12'
-          cache: 'pip'
+          python-version: "3.12"
+          enable-cache: true
       - name: Install dependencies
-        run: |
-          pip install -r requirements.txt
+        run: uv sync --frozen --extra dev
       - name: Lint (Ruff)
-        run: |
-          ruff format --check .
-          ruff check .
+        run: uv run ruff format --check . && uv run ruff check .
       - name: Unit tests
-        run: |
-          python -m unittest discover tests
+        run: uv run python -m unittest discover tests

Dockerfile

@@ -1,21 +1,15 @@
 # FROM baseimage: baseimage is a starting point
 FROM python:3.12-slim
-# python:3.12-slim as baseimage
 
-# change directory to app directory
 WORKDIR /app
 
-# copy requirements.txt file
-COPY requirements.txt ./
-
-# install app dependencies
-RUN pip install -r requirements.txt
-#  RUN is used while building the container
-
-# copy code into the image
+RUN pip install uv
+COPY pyproject.toml uv.lock ./
+RUN uv sync --frozen --no-dev --no-install-project
 COPY . .
+RUN uv sync --frozen --no-dev
 
-# run the app
+ENV PATH="/app/.venv/bin:$PATH"
 CMD ["uvicorn", "chatbot:app", "--host", "0.0.0.0", "--port", "8000"]
 # CMD is used to START the container AFTER building
 # there can be only 1 CMD command in a dockerfile

Makefile

@@ -1,14 +1,14 @@
 init:
-	pip install -r requirements.txt
+	uv sync --extra dev
 
 run:
-	python chatbot.py
+	uv run python chatbot.py
 
 check:
-	ruff format .
-	ruff check --fix .
+	uv run ruff format .
+	uv run ruff check --fix .
 
 test:
-	python -m unittest discover tests
+	uv run python -m unittest discover tests
 
 .PHONY: check init run test

README.md

@@ -10,20 +10,50 @@ Lets you ask questions over your own documents and get answers grounded in them.
 
 ## Requirements
 
-- Python: Version 3.10 - 3.12
-- Dependencies: Check [requirements.txt](./requirements.txt)
+- Python: 3.10–3.12 (uv installs it automatically if needed). 3.14 is not supported: ChromaDB uses Pydantic v1, which is incompatible with 3.14+.
+- [uv](https://github.com/astral-sh/uv) – package and environment manager
 
 ## Installation
 
-Make sure you create a virtual environment, activate it, and then install all dependencies mentioned in `requirements.txt`
+1. Install [uv](https://github.com/astral-sh/uv) (e.g. via the official installer):
+
+   ```sh
+   curl -LsSf https://astral.sh/uv/install.sh | sh
+   ```
+
+   Then ensure `~/.local/bin` is on your `PATH`, or install with pip: `pip install uv`.
+
+2. From the repo root, create the venv and install dependencies:
+
+   ```sh
+   uv sync --extra dev    # creates .venv and installs deps + dev tools (ruff, pyright)
+   ```
+
+3. Activate the venv so you can use `python`, `pytest`, etc. without prefixing every command with `uv run`:
+
+   ```sh
+   source .venv/bin/activate   # macOS/Linux
+   # Windows:  .venv\Scripts\activate
+   ```
+
+## Adding a new package
+
+From the repo root (venv can be active or not):
 
 ```sh
-python -m venv .venv    # create venv
-source .venv/bin/activate   # activate venv
+uv add <package-name>
+```
+
+This updates `pyproject.toml` and `uv.lock`, and installs the package. Commit both files.
 
-pip install -r requirements.txt # install dependencies
+For a dev-only dependency (e.g. a test or lint tool):
+
+```sh
+uv add --dev <package-name>
 ```
 
+To add a version constraint: `uv add "package>=1.0"`. After editing `pyproject.toml` by hand, run `uv lock` to refresh the lockfile.
+
 ## Configuration
 
 - Create `.env` file with variables mentioned in [.env.example](./.env.example)
@@ -40,13 +70,21 @@ pip install -r requirements.txt # install dependencies
 
 ## Run
 
-To run programmatically:
-`python chatbot.py`
+With the venv activated (see Installation), from the repo root:
+
+Run with: `python chatbot.py`
+
+Without activating the venv, prefix with `uv run`: `uv run python chatbot.py`
+
+## Run with Docker (local)
+
+From the repo root. One command (build + run, with `.env` and local `source_docs` / `chroma_db` mounted):
+
+```sh
+docker compose up --build
+```
 
-To run via CLI (non-programmatically):
-`fastapi dev chatbot.py`
-or
-`uvicorn chatbot:app --reload`
+Then open http://localhost:8000/ (health) or http://localhost:8000/docs (API docs).
 
 ## Architecture
 
@@ -161,7 +199,7 @@ Send a message to the chatbot.
 
 ## Testing
 
-1. Start the server using `python chatbot.py`
+1. Start the server: `python chatbot.py` (or `uv run python chatbot.py` if the venv is not activated)
 
 2. In another terminal, test the health endpoint:
 ```bash
@@ -187,7 +225,7 @@ curl -X POST http://127.0.0.1:8000/chat \
 
 ## Formatting
 
-Format and lint code with [Ruff](https://docs.astral.sh/ruff/) (install via `pip install -r requirements.txt`):
+Format and lint code with [Ruff](https://docs.astral.sh/ruff/) (installed via `uv sync --extra dev`):
 
 ```bash
 make check
@@ -197,7 +235,8 @@ make check
 
 chatbot/
 ├── README.md
-├── requirements.txt
+├── pyproject.toml
+├── uv.lock
 ├── .env.example
 ├── chatbot.py
 │
@@ -233,13 +272,13 @@ chatbot/
 ## Files Reference
 
 - Main implementation: [chatbot.py](chatbot.py) – FastAPI app. RAG and vector DB in the [chroma/](chroma/) package
-- Configuration: [requirements.txt](requirements.txt), [.env.example](.env.example)
+- Configuration: [pyproject.toml](pyproject.toml), [uv.lock](uv.lock), [.env.example](.env.example)
 - Packages
   - [chroma/](chroma/) - ChromaDB client implementation with vector database operations
   - [github_downloader/](github_downloader/) - see [github_downloader/README.md](./github_downloader/README.md)
 - Scripts: [scripts/](scripts/)
-  - [reload_db.py](scripts/reload_db.py) - script to reload Chroma collection. Run using `python -m scripts.reload_db`
-  - [remove_db_files.py](scripts/remove_db_files.py) - script to remove file from Chroma collection. Run using `python -m scripts.remove_db_files`
+  - [reload_db.py](scripts/reload_db.py) - script to reload Chroma collection. Run: `python -m scripts.reload_db` (or `uv run python -m scripts.reload_db` without venv)
+  - [remove_db_files.py](scripts/remove_db_files.py) - script to remove file from Chroma collection. Run: `python -m scripts.remove_db_files` (or `uv run python -m scripts.remove_db_files` without venv)
 - Curl scripts: [curl_scripts/](curl_scripts/)
   - [test_health.sh](curl_scripts/test_health.sh) – Test GET / endpoint
   - [test_chatbot.sh](curl_scripts/test_chatbot.sh) - Test POST /chat endpoint

github_downloader/README.md

@@ -17,7 +17,7 @@ git sparse-checkout set <path_in_repo>
 ## Requirements
 
 - Python 3.10+
-- Dependencies: `requests`. Check [requirements.txt](../requirements.txt)
+- Dependencies: managed by [uv](https://github.com/astral-sh/uv). From repo root run `uv sync --extra dev`, then activate the venv (`source .venv/bin/activate`) so you can use `python` without `uv run`. See the main [README](../README.md#installation).
 
 ## Input: JSON file
 
@@ -44,12 +44,14 @@ If the file is missing or invalid, the program logs an error and exits.
 
 ## Run
 
-Make sure you create a virtual environment, activate it, then from repo root:
+From repo root with the venv activated:
 
 ```sh
 python -m github_downloader
 ```
 
+If the venv is not activated, use `uv run python -m github_downloader`.
+
 ## Configuration
 
 - **Env:** `GITHUB_TOKEN` (recommended for rate limits), `COLLECTION_PATH` (default `source_docs`).

pyproject.toml

@@ -1,6 +1,24 @@
 [project]
 name = "chatbot-mvp"
-requires-python = ">=3.10,<3.13" # Python 3.10 - 3.12
+version = "0.1.0"
+requires-python = ">=3.10,<3.14"
+dependencies = [
+    "chromadb",
+    "fastapi",
+    "google-genai",
+    "langchain-text-splitters",
+    "pymupdf4llm",
+    "pydantic",
+    "python-dotenv",
+    "uvicorn",
+    "requests",
+]
+
+[project.optional-dependencies]
+dev = [
+    "ruff",
+    "pyright",
+]
 
 [tool.ruff]
 target-version = "py312" # Python 3.12