feat: add devcontainer for local setup

scripts/setup_fork.ps1

@@ -102,18 +102,33 @@ Write-Host '[3/4] Python virtual environment' -ForegroundColor Blue
 $VenvPath = Join-Path $BaseDir 'venv'
 $VenvActivate = Join-Path $VenvPath 'Scripts/Activate.ps1'
 
-if (Test-Path $VenvActivate) {
-    Write-Host "OK venv already exists at $VenvPath" -ForegroundColor Green
-} else {
-    $py = $null
-    foreach ($candidate in @('python3.13', 'python', 'python3')) {
-        if (Get-Command $candidate -ErrorAction SilentlyContinue) {
-            $py = $candidate
-            break
+function Get-Python313Command {
+    foreach ($candidate in @('python3.13', 'python3', 'python')) {
+        if (-not (Get-Command $candidate -ErrorAction SilentlyContinue)) {
+            continue
+        }
+
+        $version = & $candidate -c "import sys; print(f'{sys.version_info.major}.{sys.version_info.minor}')" 2>$null
+        if ($LASTEXITCODE -eq 0 -and $version -eq '3.13') {
+            return $candidate
         }
     }
+
+    return $null
+}
+
+if (Test-Path $VenvActivate) {
+    $venvPython = Join-Path $VenvPath 'Scripts/python.exe'
+    $venvVersion = & $venvPython -c "import sys; print(f'{sys.version_info.major}.{sys.version_info.minor}')" 2>$null
+    if ($LASTEXITCODE -ne 0 -or $venvVersion -ne '3.13') {
+        Write-Host "Error: existing venv uses Python $venvVersion. Remove $VenvPath and re-run with Python 3.13." -ForegroundColor Red
+        exit 1
+    }
+    Write-Host "OK venv already exists at $VenvPath (Python $venvVersion)" -ForegroundColor Green
+} else {
+    $py = Get-Python313Command
     if (-not $py) {
-        Write-Host 'Error: no python interpreter found on PATH. Install Python 3.13.' -ForegroundColor Red
+        Write-Host 'Error: no Python 3.13 interpreter found on PATH. Install Python 3.13.' -ForegroundColor Red
         exit 1
     }
     & $py -m venv $VenvPath
@@ -128,8 +143,9 @@ Write-Host ''
 
 Write-Host '[4/4] Environment files' -ForegroundColor Blue
 $pairs = @(
-    @{ Src = 'api/.env.example'; Dst = 'api/.env' },
-    @{ Src = 'ui/.env.example';  Dst = 'ui/.env'  }
+    @{ Src = 'api/.env.example';      Dst = 'api/.env'      },
+    @{ Src = 'api/.env.test.example'; Dst = 'api/.env.test' },
+    @{ Src = 'ui/.env.example';       Dst = 'ui/.env'       }
 )
 foreach ($p in $pairs) {
     if (Test-Path $p.Dst) {

scripts/setup_fork.sh

@@ -102,18 +102,36 @@ echo ""
 echo -e "${BLUE}[3/4] Python virtual environment${NC}"
 VENV_PATH="$BASE_DIR/venv"
 
-if [[ -d "$VENV_PATH" && -f "$VENV_PATH/bin/activate" ]]; then
-    echo -e "${GREEN}✓ venv already exists at $VENV_PATH${NC}"
-else
-    PY=""
+find_python_313() {
+    local candidate=""
+    local version=""
+
     for candidate in python3.13 python3 python; do
-        if command -v "$candidate" >/dev/null 2>&1; then
-            PY="$candidate"
-            break
+        if ! command -v "$candidate" >/dev/null 2>&1; then
+            continue
+        fi
+
+        version=$("$candidate" -c "import sys; print(f'{sys.version_info.major}.{sys.version_info.minor}')" 2>/dev/null || true)
+        if [[ "$version" == "3.13" ]]; then
+            echo "$candidate"
+            return 0
         fi
     done
+
+    return 1
+}
+
+if [[ -d "$VENV_PATH" && -f "$VENV_PATH/bin/activate" ]]; then
+    VENV_VERSION=$("$VENV_PATH/bin/python" -c "import sys; print(f'{sys.version_info.major}.{sys.version_info.minor}')" 2>/dev/null || true)
+    if [[ "$VENV_VERSION" != "3.13" ]]; then
+        echo -e "${RED}Error: existing venv uses Python ${VENV_VERSION:-unknown}. Remove $VENV_PATH and re-run with Python 3.13.${NC}"
+        exit 1
+    fi
+    echo -e "${GREEN}✓ venv already exists at $VENV_PATH (Python $VENV_VERSION)${NC}"
+else
+    PY="$(find_python_313 || true)"
     if [[ -z "$PY" ]]; then
-        echo -e "${RED}Error: no python interpreter found on PATH. Install Python 3.13.${NC}"
+        echo -e "${RED}Error: no Python 3.13 interpreter found on PATH. Install Python 3.13.${NC}"
         exit 1
     fi
     "$PY" -m venv "$VENV_PATH"
@@ -126,7 +144,7 @@ echo ""
 ###############################################################################
 
 echo -e "${BLUE}[4/4] Environment files${NC}"
-for pair in "api/.env.example|api/.env" "ui/.env.example|ui/.env"; do
+for pair in "api/.env.example|api/.env" "api/.env.test.example|api/.env.test" "ui/.env.example|ui/.env"; do
     src="${pair%|*}"
     dst="${pair#*|}"
     if [[ -f "$dst" ]]; then

scripts/setup_local.devcontainer.md

@@ -0,0 +1,13 @@
+# Devcontainer contributor setup
+
+`setup_local.sh` and `setup_local.ps1` provision the OSS Docker stack for local
+deployments. They are not the recommended contributor workflow for this
+repository.
+
+For day-to-day development, use the checked-in devcontainer under
+`.devcontainer/`. The full contributor instructions live in
+`../docs/contribution/setup.mdx`.
+
+The devcontainer flow pins Python 3.13, installs backend and frontend
+dependencies in-container, creates a container-specific API env file, and
+starts Postgres, Redis, and MinIO automatically.

scripts/setup_requirements.ps1

@@ -25,24 +25,30 @@ if (-not $Dev) {
     git submodule update --init --recursive
 }
 
+# Use uv (https://github.com/astral-sh/uv) for ~5-10x faster installs.
+if (-not (Get-Command uv -ErrorAction SilentlyContinue)) {
+    Write-Host "Installing uv..."
+    Invoke-RestMethod https://astral.sh/uv/install.ps1 | Invoke-Expression
+    $env:Path = "$env:USERPROFILE\.local\bin;$env:Path"
+}
+
 # Install dograh API requirements first so pipecat's extras win on any
 # shared transitive dependencies (matches api/Dockerfile and CI workflow).
 Write-Host "Installing dograh API requirements..."
-pip install -r api/requirements.txt
+uv pip install -r api/requirements.txt
 
 if ($Dev) {
     Write-Host "Installing dograh API dev requirements..."
-    pip install -r api/requirements.dev.txt
+    uv pip install -r api/requirements.dev.txt
 }
 
 # Install pipecat in editable mode with all extras
 Write-Host "Installing pipecat dependencies..."
-pip install -e './pipecat[cartesia,deepgram,openai,elevenlabs,groq,google,azure,sarvam,soundfile,silero,webrtc,speechmatics,openrouter,camb]'
+uv pip install -e './pipecat[cartesia,deepgram,openai,elevenlabs,groq,google,azure,sarvam,soundfile,silero,webrtc,speechmatics,openrouter,camb]'
 
 if ($Dev) {
     Write-Host "Installing pipecat dev dependencies..."
-    pip install --upgrade pip
-    pip install --group pipecat/pyproject.toml:dev
+    uv pip install --group pipecat/pyproject.toml:dev
 }
 
 Write-Host "Setup complete! Requirements are installed."

scripts/setup_requirements.sh

@@ -39,24 +39,32 @@ if [ "$DEV_MODE" -eq 0 ]; then
     git submodule update --init --recursive
 fi
 
+# Use uv (https://github.com/astral-sh/uv) for ~5-10x faster installs.
+# The devcontainer Dockerfile pre-installs uv; this fallback handles CI runners
+# and contributor laptops that don't have it yet.
+if ! command -v uv >/dev/null 2>&1; then
+    echo "Installing uv..."
+    curl -LsSf https://astral.sh/uv/install.sh | sh
+    export PATH="$HOME/.local/bin:$PATH"
+fi
+
 # Install dograh API requirements first so pipecat's extras win on any
 # shared transitive dependencies (matches api/Dockerfile and CI workflow).
 echo "Installing dograh API requirements..."
-pip install -r api/requirements.txt
+uv pip install -r api/requirements.txt
 
 if [ "$DEV_MODE" -eq 1 ]; then
     echo "Installing dograh API dev requirements..."
-    pip install -r api/requirements.dev.txt
+    uv pip install -r api/requirements.dev.txt
 fi
 
 # Install pipecat in editable mode with all extras
 echo "Installing pipecat dependencies..."
-pip install -e ./pipecat[cartesia,deepgram,openai,elevenlabs,groq,google,azure,sarvam,soundfile,silero,webrtc,speechmatics,openrouter,camb,mcp]
+uv pip install -e ./pipecat[cartesia,deepgram,openai,elevenlabs,groq,google,azure,sarvam,soundfile,silero,webrtc,speechmatics,openrouter,camb,mcp]
 
 if [ "$DEV_MODE" -eq 1 ]; then
     echo "Installing pipecat dev dependencies..."
-    pip install --upgrade pip
-    pip install --group pipecat/pyproject.toml:dev
+    uv pip install --group pipecat/pyproject.toml:dev
 fi
 
 echo "Setup complete! Requirements are installed."

scripts/start_services_dev.ps1

@@ -21,7 +21,7 @@ $ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
 $BaseDir   = Split-Path -Parent $ScriptDir
 Set-Location $BaseDir
 
-$EnvFile    = Join-Path $BaseDir 'api/.env'
+$EnvFile    = if ($env:DOGRAH_ENV_FILE) { $env:DOGRAH_ENV_FILE } else { Join-Path $BaseDir 'api/.env' }
 $RunDir     = Join-Path $BaseDir 'run'
 $LogsRoot   = Join-Path $BaseDir 'logs'
 $LatestDir  = Join-Path $LogsRoot 'latest'
@@ -29,6 +29,7 @@ $VenvPath   = Join-Path $BaseDir 'venv'
 
 Write-Host "Starting Dograh Services (DEV MODE) in BASE_DIR: $BaseDir"
 Write-Host "Auto-reload enabled for api/ directory changes"
+Write-Host "Environment file: $EnvFile"
 
 ###############################################################################
 ### 1) Load environment variables

scripts/start_services_dev.sh

@@ -8,7 +8,7 @@ set -e  # Exit on error
 # Determine BASE_DIR as parent of the scripts directory
 BASE_DIR="$(cd "$(dirname "$(dirname "${BASH_SOURCE[0]}")")" && pwd)"
 
-ENV_FILE="$BASE_DIR/api/.env"
+ENV_FILE="${DOGRAH_ENV_FILE:-$BASE_DIR/api/.env}"
 RUN_DIR="$BASE_DIR/run"                 # Where we keep *.pid
 BASE_LOG_DIR="$BASE_DIR/logs"           # Base logs directory
 
@@ -26,6 +26,7 @@ HEALTH_INTERVAL=${HEALTH_INTERVAL:-2}
 cd "$BASE_DIR"
 echo "Starting Dograh Services (DEV MODE) at $(date) in BASE_DIR: ${BASE_DIR}"
 echo "Auto-reload enabled for api/ directory changes"
+echo "Environment file: $ENV_FILE"
 
 ###############################################################################
 ### 1) Load environment variables