Merge pull request #4 from calcorum/phase-3-uv-migration

Phase 3 uv migration

QUICKSTART.md

@@ -1,6 +1,6 @@
 # Paper Dynasty - Quick Start Guide
 
-**Last Updated**: 2025-10-21
+**Last Updated**: 2025-11-04
 
 ## Prerequisites
 
@@ -22,12 +22,11 @@ cd /mnt/NV2/Development/strat-gameplay-webapp
 ```bash
 cd backend
 
-# Create virtual environment
+# Install UV (modern Python package manager)
-python3 -m venv venv
+curl -LsSf https://astral.sh/uv/install.sh | sh
-source venv/bin/activate
 
 # Install dependencies
-pip install -r requirements-dev.txt
+uv sync
 
 # Configure environment
 cp .env.example .env
@@ -37,7 +36,7 @@ cp .env.example .env
 docker compose up -d
 
 # Verify setup
-python -m app.main
+uv run python -m app.main
 # Server should start at http://localhost:8000
 ```
 
@@ -69,8 +68,8 @@ docker compose up -d
 
 # Terminal 2: Run Backend
 cd backend
-source venv/bin/activate
+uv run python -m app.main
-python -m app.main
+# Or: source .venv/bin/activate && python -m app.main
 ```
 
 Backend will be available at:
@@ -99,14 +98,13 @@ npm run dev
 ```bash
 # Run tests
 cd backend
-source venv/bin/activate
+uv run pytest tests/ -v
-pytest tests/ -v
 
 # Format code
-black app/ tests/
+uv run black app/ tests/
 
 # Type checking
-mypy app/
+uv run mypy app/
 
 # Check logs
 tail -f backend/logs/app_*.log
@@ -142,15 +140,18 @@ psql postgresql://paperdynasty:PASSWORD@10.10.0.42:5432/paperdynasty_dev
 Use `docker compose` (with space) not `docker-compose`
 
 ### "greenlet library required"
+This should not happen with UV. If it does, run:
 ```bash
-pip install greenlet
+uv sync  # Reinstall all dependencies
 ```
 
 ### Import errors / Module not found
-Ensure virtual environment is activated:
+Ensure dependencies are installed:
 ```bash
-source venv/bin/activate
+uv sync  # Install/sync dependencies
-which python  # Should show path to venv/bin/python
+# Or check virtual environment
+source .venv/bin/activate
+which python  # Should show path to .venv/bin/python
 ```
 
 ### Database connection errors

README.md

@@ -44,8 +44,8 @@ strat-gameplay-webapp/
 3. **Start Backend** (in another terminal)
    ```bash
    cd backend
-   source venv/bin/activate  # or 'venv\Scripts\activate' on Windows
+   uv run python -m app.main
-   python -m app.main
+   # Or manually activate: source .venv/bin/activate && python -m app.main
    ```
    Backend will be available at http://localhost:8000
 
@@ -130,26 +130,26 @@ strat-gameplay-webapp/
 ```bash
 cd backend
 
-# Activate virtual environment
+# Install UV (one-time setup)
-source venv/bin/activate
+curl -LsSf https://astral.sh/uv/install.sh | sh
 
 # Install dependencies
-pip install -r requirements-dev.txt
+uv sync
 
 # Run server
-python -m app.main
+uv run python -m app.main
 
 # Run tests
-pytest tests/ -v
+uv run pytest tests/ -v
 
 # Code formatting
-black app/ tests/
+uv run black app/ tests/
 
 # Linting
-flake8 app/ tests/
+uv run flake8 app/ tests/
 
 # Type checking
-mypy app/
+uv run mypy app/
 ```
 
 ### Frontend
@@ -265,7 +265,8 @@ open http://localhost:8000/api/health
 ## Tech Stack
 
 ### Backend
-- **Framework**: FastAPI (Python 3.11+)
+- **Framework**: FastAPI (Python 3.13+)
+- **Package Manager**: UV (modern Python package management)
 - **WebSocket**: Socket.io
 - **Database**: PostgreSQL 14+ with SQLAlchemy
 - **Cache**: Redis 7

backend/.dockerignore

@@ -44,6 +44,7 @@ docker-compose.yml
 
 # Documentation
 *.md
+!README.md
 docs/
 
 # OS

backend/.python-version

@@ -0,0 +1 @@
+3.13

backend/CLAUDE.md

@@ -123,19 +123,35 @@ Lineup.from_api_data(config, data)
 
 ## Development Workflow
 
+### Package Management
+
+This project uses **UV** for fast, reliable package management.
+
+**Installing UV** (one-time setup):
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+**Setting up the project**:
+```bash
+cd backend
+uv sync  # Creates .venv and installs all dependencies
+```
+
 ### Daily Development
 ```bash
-# Activate virtual environment
-source venv/bin/activate
-
 # Start Redis (in separate terminal or use -d for detached)
 docker compose up -d
 
-# Run backend with hot-reload
+# Run backend with hot-reload (UV auto-activates .venv)
-python -m app.main
+uv run python -m app.main
 
 # Backend available at http://localhost:8000
 # API docs at http://localhost:8000/docs
+
+# Alternative: Activate .venv manually
+source .venv/bin/activate
+python -m app.main
 ```
 
 ### Testing
@@ -146,7 +162,7 @@ Test the game engine directly without needing a frontend:
 
 ```bash
 # Start interactive REPL (recommended for rapid testing)
-python -m terminal_client
+uv run python -m terminal_client
 
 # Then interact:
 ⚾ > new_game
@@ -171,22 +187,22 @@ See `terminal_client/CLAUDE.md` for full documentation.
 
 ```bash
 # Run all tests
-pytest tests/ -v
+uv run pytest tests/ -v
 
 # Run with coverage
-pytest tests/ --cov=app --cov-report=html
+uv run pytest tests/ --cov=app --cov-report=html
 
 # Run specific test file
-pytest tests/unit/test_game_engine.py -v
+uv run pytest tests/unit/test_game_engine.py -v
 
 # Type checking
-mypy app/
+uv run mypy app/
 
 # Code formatting
-black app/ tests/
+uv run black app/ tests/
 
 # Linting
-flake8 app/ tests/
+uv run flake8 app/ tests/
 ```
 
 ## Coding Standards
@@ -891,8 +907,43 @@ docker-compose up -d  # Old command not available
 
 ### Python Environment
 - **Version**: Python 3.13.3 (not 3.11 as originally planned)
-- **Virtual Environment**: Located at `backend/venv/`
+- **Package Manager**: UV (v0.9.7+) - Fast, reliable Python package management
-- **Activation**: `source venv/bin/activate` (from backend directory)
+- **Virtual Environment**: Located at `backend/.venv/` (UV default)
+- **Activation**: `source .venv/bin/activate` (from backend directory)
+  - Or use `uv run <command>` to auto-activate
+
+### Package Management with UV
+
+**Add a new dependency**:
+```bash
+# Production dependency
+uv add package-name==1.2.3
+
+# Development dependency
+uv add --dev package-name==1.2.3
+
+# With extras
+uv add "package[extra]==1.2.3"
+```
+
+**Update dependencies**:
+```bash
+# Update a specific package
+uv add package-name@latest
+
+# Sync dependencies (after pulling pyproject.toml changes)
+uv sync
+```
+
+**Remove a dependency**:
+```bash
+uv remove package-name
+```
+
+**Key Files**:
+- `pyproject.toml` - Project metadata and dependencies (commit to git)
+- `uv.lock` - Locked dependency versions (commit to git)
+- `.venv/` - Virtual environment (gitignored)
 
 ### Critical Dependencies
 - **greenlet**: Required for SQLAlchemy async support (must be explicitly installed)

backend/Dockerfile

@@ -1,31 +1,36 @@
 # Backend Dockerfile for Paper Dynasty Game Engine
 # Multi-stage build for optimized production image
 
-FROM python:3.11-slim as base
+FROM python:3.13-slim as base
 
 # Set environment variables
 ENV PYTHONUNBUFFERED=1 \
     PYTHONDONTWRITEBYTECODE=1 \
-    PIP_NO_CACHE_DIR=1 \
+    UV_LINK_MODE=copy \
-    PIP_DISABLE_PIP_VERSION_CHECK=1
+    UV_COMPILE_BYTECODE=1 \
+    UV_PYTHON_DOWNLOADS=never
 
-# Install system dependencies
+# Install system dependencies and UV
 RUN apt-get update && apt-get install -y \
     curl \
     postgresql-client \
+    build-essential \
     && rm -rf /var/lib/apt/lists/*
 
+# Install UV
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
+
 # Create app directory
 WORKDIR /app
 
 # Development stage
 FROM base as development
 
-# Copy requirements
+# Copy dependency files (including README.md referenced in pyproject.toml)
-COPY requirements.txt requirements-dev.txt ./
+COPY pyproject.toml uv.lock README.md ./
 
-# Install Python dependencies
+# Install all dependencies (including dev)
-RUN pip install -r requirements-dev.txt
+RUN uv sync --frozen
 
 # Copy application code
 COPY . .
@@ -34,16 +39,16 @@ COPY . .
 EXPOSE 8000
 
 # Run with uvicorn reload for development
-CMD ["python", "-m", "uvicorn", "app.main:socket_app", "--host", "0.0.0.0", "--port", "8000", "--reload"]
+CMD ["uv", "run", "python", "-m", "uvicorn", "app.main:socket_app", "--host", "0.0.0.0", "--port", "8000", "--reload"]
 
 # Production stage
 FROM base as production
 
-# Copy requirements (production only)
+# Copy dependency files (including README.md referenced in pyproject.toml)
-COPY requirements.txt ./
+COPY pyproject.toml uv.lock README.md ./
 
-# Install Python dependencies
+# Install production dependencies only
-RUN pip install -r requirements.txt
+RUN uv sync --frozen --no-dev
 
 # Create non-root user
 RUN useradd -m -u 1000 appuser && \
@@ -63,4 +68,4 @@ HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
     CMD curl -f http://localhost:8000/api/health || exit 1
 
 # Run with production server
-CMD ["python", "-m", "uvicorn", "app.main:socket_app", "--host", "0.0.0.0", "--port", "8000", "--workers", "4"]
+CMD ["uv", "run", "python", "-m", "uvicorn", "app.main:socket_app", "--host", "0.0.0.0", "--port", "8000", "--workers", "4"]

backend/README.md

@@ -0,0 +1,20 @@
+# Paper Dynasty Backend
+
+FastAPI-based real-time baseball game engine with WebSocket support.
+
+## Quick Start
+
+```bash
+# Install UV
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Install dependencies
+uv sync
+
+# Run server
+uv run python -m app.main
+```
+
+## Documentation
+
+See `CLAUDE.md` for full documentation.

backend/app/models/game_models.py

@@ -700,6 +700,18 @@ class GameState(BaseModel):
     )
 
 
+# ============================================================================
+# MODEL REBUILD (for forward references)
+# ============================================================================
+
+# Import PositionRating at runtime for model rebuild
+from app.models.player_models import PositionRating  # noqa: E402
+
+# Rebuild models that use forward references
+LineupPlayerState.model_rebuild()
+GameState.model_rebuild()
+
+
 # ============================================================================
 # EXPORTS
 # ============================================================================

backend/pyproject.toml

@@ -0,0 +1,48 @@
+[project]
+name = "paper-dynasty-backend"
+version = "0.1.0"
+description = "Paper Dynasty Real-Time Game Engine Backend - FastAPI with WebSocket support"
+readme = "README.md"
+requires-python = ">=3.13"
+authors = [
+    { name = "Paper Dynasty Team" }
+]
+dependencies = [
+    "aiofiles==24.1.0",
+    "alembic==1.14.0",
+    "asyncpg==0.30.0",
+    "click==8.1.8",
+    "fastapi==0.115.6",
+    "greenlet==3.2.4",
+    "httpx==0.28.1",
+    "passlib[bcrypt]==1.7.4",
+    "pendulum==3.0.0",
+    "psycopg2-binary==2.9.10",
+    "pydantic==2.10.6",
+    "pydantic-settings==2.7.1",
+    "python-dotenv==1.0.1",
+    "python-jose[cryptography]==3.3.0",
+    "python-multipart==0.0.20",
+    "python-socketio==5.11.4",
+    "redis==5.2.1",
+    "rich==13.9.4",
+    "sqlalchemy==2.0.36",
+    "uvicorn[standard]==0.34.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["app"]
+
+[dependency-groups]
+dev = [
+    "black==24.10.0",
+    "flake8==7.1.1",
+    "mypy==1.14.1",
+    "pytest==8.3.4",
+    "pytest-asyncio==0.25.2",
+    "pytest-cov==6.0.0",
+]

backend/terminal_client/CLAUDE.md

@@ -15,7 +15,8 @@ Interactive REPL (Read-Eval-Print Loop) terminal UI for testing the game engine
 Start the interactive shell for persistent in-memory state:
 
 ```bash
-python -m terminal_client
+uv run python -m terminal_client
+# Or: source .venv/bin/activate && python -m terminal_client
 
 # Then type commands interactively:
 ⚾ > new_game
@@ -38,10 +39,10 @@ python -m terminal_client
 Run individual commands with persistent config file:
 
 ```bash
-python -m terminal_client new-game
+uv run python -m terminal_client new-game
-python -m terminal_client defensive --alignment normal
+uv run python -m terminal_client defensive --alignment normal
-python -m terminal_client offensive --approach power
+uv run python -m terminal_client offensive --approach power
-python -m terminal_client resolve
+uv run python -m terminal_client resolve
 ```
 
 **Note**: Config file (`~/.terminal_client_config.json`) remembers current game between commands.