# Environment Setup Specification

## ADDED Requirements

### Requirement: GPU Detection and CUDA Installation
The system SHALL automatically detect compatible GPU hardware during environment setup and install appropriate PaddlePaddle packages (GPU-enabled or CPU-only) based on hardware availability.

#### Scenario: GPU detected with CUDA support
- **WHEN** setup script runs on system with NVIDIA GPU and CUDA drivers
- **THEN** the script detects GPU using `nvidia-smi` command
- **AND** determines CUDA version from driver
- **AND** installs `paddlepaddle-gpu` with matching CUDA version
- **AND** verifies GPU availability through Python
- **AND** displays GPU information (device name, CUDA version, memory)

#### Scenario: No GPU detected
- **WHEN** setup script runs on system without compatible GPU
- **THEN** the script detects absence of GPU hardware
- **AND** installs CPU-only `paddlepaddle` package
- **AND** displays message that CPU mode will be used
- **AND** continues setup without errors

#### Scenario: GPU detected but no CUDA drivers
- **WHEN** setup script detects NVIDIA GPU but CUDA drivers are missing
- **THEN** the script displays warning about missing drivers
- **AND** provides installation instructions for CUDA drivers
- **AND** falls back to CPU-only installation
- **AND** suggests re-running setup after driver installation

#### Scenario: CUDA version mismatch
- **WHEN** detected CUDA version is not compatible with available PaddlePaddle packages
- **THEN** the script displays available CUDA versions
- **AND** installs closest compatible PaddlePaddle GPU package
- **AND** warns user about potential compatibility issues
- **AND** provides instructions to upgrade/downgrade CUDA if needed

#### Scenario: Manual CUDA version override
- **WHEN** user sets CUDA_VERSION environment variable before running setup
- **THEN** the script uses specified CUDA version instead of auto-detection
- **AND** installs corresponding PaddlePaddle GPU package
- **AND** skips automatic CUDA detection
- **AND** displays warning if specified version differs from detected version

### Requirement: GPU Verification
The system SHALL verify GPU functionality after installation and provide clear status reporting.

#### Scenario: Successful GPU setup verification
- **WHEN** PaddlePaddle GPU installation completes
- **THEN** the script runs GPU availability test using Python
- **AND** confirms CUDA devices are accessible
- **AND** displays GPU count, device names, and memory capacity
- **AND** marks GPU setup as successful

#### Scenario: GPU verification fails
- **WHEN** GPU verification test fails after installation
- **THEN** the script displays detailed error message
- **AND** provides troubleshooting steps
- **AND** suggests fallback to CPU mode
- **AND** does not fail entire setup process

### Requirement: Environment Configuration for GPU
The system SHALL create appropriate configuration settings for GPU usage in environment files.

#### Scenario: GPU-enabled configuration
- **WHEN** GPU is successfully detected and verified
- **THEN** the setup script adds GPU settings to `.env.local`
- **AND** sets `FORCE_CPU_MODE=false`
- **AND** sets detected `CUDA_VERSION`
- **AND** sets recommended `GPU_MEMORY_FRACTION` (e.g., 0.8)
- **AND** adds GPU-related comments and documentation

#### Scenario: CPU-only configuration
- **WHEN** no GPU is detected or verification fails
- **THEN** the setup script creates CPU-only configuration
- **AND** sets `FORCE_CPU_MODE=true`
- **AND** omits or comments out GPU-specific settings
- **AND** adds note about GPU requirements