Merge pull request #86 from anfredette/refactor

refactor: Standardize on uv and clean up top-level directory

Author: anfredette

CLAUDE.md

@@ -173,6 +173,19 @@ The recommendation engine uses **multi-criteria scoring** to rank configurations
 - `backend/src/recommendation/analyzer.py` - Generates 5 ranked lists
 - `backend/src/recommendation/config_finder.py` - Orchestrates scoring during capacity planning
 
+## Development Environment
+
+This project uses **uv** (by Astral) for Python package management. **Do not use `pip` or `pip install`.**
+
+- **Install dependencies**: `uv sync` (reads from `pyproject.toml` + `uv.lock`)
+- **Run Python commands**: `uv run python ...` (not bare `python`)
+- **Run tools**: `uv run pytest`, `uv run ruff`, `uv run uvicorn`, etc.
+- **Add a dependency**: `uv add <package>` (updates `pyproject.toml` and `uv.lock`)
+- **Source of truth**: `pyproject.toml` defines all dependencies; there is no top-level `requirements.txt`
+- **Makefile targets** already use `uv` — see `make setup-backend`, `make start-backend`, etc.
+
+Note: `ui/requirements.txt` and `simulator/requirements.txt` exist separately for their Docker builds.
+
 ## Working with This Repository
 
 ### When Modifying Architecture Documents

backend/Dockerfile

@@ -11,11 +11,14 @@ RUN apt-get update && apt-get install -y \
     postgresql-client \
     && rm -rf /var/lib/apt/lists/*
 
-# Copy requirements file
-COPY requirements.txt .
+# Install uv
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
 
-# Install Python dependencies
-RUN pip install --no-cache-dir -r requirements.txt
+# Copy dependency files
+COPY pyproject.toml uv.lock ./
+
+# Install Python dependencies (frozen = use lockfile exactly, no-dev = skip dev deps)
+RUN uv sync --frozen --no-dev
 
 # Copy backend source code
 COPY backend/src ./backend/src
@@ -35,7 +38,7 @@ EXPOSE 8000
 
 # Health check
 HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
-  CMD python -c "import requests; requests.get('http://localhost:8000/health')" || exit 1
+  CMD uv run python -c "import requests; requests.get('http://localhost:8000/health')" || exit 1
 
 # Run the backend API server
-CMD ["python", "-m", "uvicorn", "backend.src.api.routes:app", "--host", "0.0.0.0", "--port", "8000"]
+CMD ["uv", "run", "uvicorn", "backend.src.api.routes:app", "--host", "0.0.0.0", "--port", "8000"]

docs/DEVELOPER_GUIDE.md

@@ -721,32 +721,15 @@ make open-backend
 
 ### Manual Backend Installation
 
-**Terminal 1:**
 ```bash
-python -m venv venv
-source venv/bin/activate  # On Windows: venv\Scripts\activate
-
-# Verify correct venv
-which python  # Should show: .../venv/bin/python
-
-pip install -r requirements.txt
+uv sync
 ```
 
 ### Manual Frontend Installation
 
-**Terminal 2 (or deactivate first):**
+The UI shares the same virtual environment as the backend (managed by uv):
 ```bash
-# If in same terminal: deactivate first
-deactivate
-
-cd frontend
-python -m venv venv
-source venv/bin/activate  # On Windows: venv\Scripts\activate
-
-# Verify correct venv
-which python  # Should show: .../frontend/venv/bin/python
-
-pip install -r requirements.txt
+uv sync  # Same command — all deps are in pyproject.toml
 ```
 
 ### Manual Ollama Model Pull
@@ -863,11 +846,8 @@ ollama pull llama3.2:3b
 ### Import Errors
 
 ```bash
-# Make sure you're in the right venv
-which python  # Should show path to venv
-
 # Reinstall dependencies
-pip install -r requirements.txt
+uv sync
 ```
 
 ## Manual Kubernetes Cluster Setup

DOCKER.md docs/DOCKER.mdDOCKER.md renamed to docs/DOCKER.md

@@ -1,31 +1,24 @@
 #!/bin/bash
 
 # Start the NeuralNav FastAPI backend
-# This script activates the virtual environment and starts the API server
+# This script installs dependencies with uv and starts the API server
 
 set -e
 
 echo "🚀 Starting NeuralNav API..."
 echo ""
 
-# Check if virtual environment exists
-if [ ! -d "venv" ]; then
-    echo "❌ Virtual environment not found!"
-    echo "Creating virtual environment..."
-    python -m venv venv
+# Check if uv is installed
+if ! command -v uv &> /dev/null; then
+    echo "❌ uv not found! Install it: curl -LsSf https://astral.sh/uv/install.sh | sh"
+    exit 1
 fi
 
-# Activate virtual environment
-source venv/bin/activate
-
-# Check if requirements are installed
-echo "Checking dependencies..."
-if ! python -c "import fastapi" &> /dev/null; then
-    echo "⚠️  Dependencies not found. Installing from requirements.txt..."
-    pip install -r requirements.txt
-    echo "✅ Dependencies installed"
-    echo ""
-fi
+# Install/sync dependencies
+echo "Syncing dependencies..."
+uv sync
+echo "✅ Dependencies ready"
+echo ""
 
 # Check if Ollama is running
 echo "Checking if Ollama is running..."
@@ -39,4 +32,4 @@ fi
 echo "Starting FastAPI backend on http://localhost:8000..."
 echo ""
 cd backend
-uvicorn src.api.routes:app --host 0.0.0.0 --port 8000 --reload
+uv run uvicorn src.api.routes:app --host 0.0.0.0 --port 8000 --reload

requirements.txt

@@ -1,31 +1,24 @@
 #!/bin/bash
 
 # Start the NeuralNav UI
-# This script activates the virtual environment and starts the Streamlit UI
+# This script installs dependencies with uv and starts the Streamlit UI
 
 set -e
 
 echo "🤖 Starting NeuralNav UI..."
 echo ""
 
-# Check if virtual environment exists
-if [ ! -d "venv" ]; then
-    echo "❌ Virtual environment not found!"
-    echo "Creating virtual environment..."
-    python -m venv venv
+# Check if uv is installed
+if ! command -v uv &> /dev/null; then
+    echo "❌ uv not found! Install it: curl -LsSf https://astral.sh/uv/install.sh | sh"
+    exit 1
 fi
 
-# Activate virtual environment
-source venv/bin/activate
-
-# Check if requirements are installed
-echo "Checking dependencies..."
-if ! python -c "import streamlit" &> /dev/null; then
-    echo "⚠️  Dependencies not found. Installing from requirements.txt..."
-    pip install -r requirements.txt
-    echo "✅ Dependencies installed"
-    echo ""
-fi
+# Install/sync dependencies
+echo "Syncing dependencies..."
+uv sync
+echo "✅ Dependencies ready"
+echo ""
 
 # Check if FastAPI backend is running
 echo "Checking if FastAPI backend is running..."
@@ -42,4 +35,4 @@ echo ""
 # Disable Streamlit's email collection prompt on first run
 export STREAMLIT_BROWSER_GATHER_USAGE_STATS=false
 
-streamlit run ui/app.py --server.headless true
+uv run streamlit run ui/app.py --server.headless true