feat(docker): Use local vLLM by default, streamline Docker setup (#54)

- docker-compose.yml now uses local vLLM (host.docker.internal:11434)
  instead of containerized vLLM - faster startup, no 9GB image download
- Add docker-compose.full.yml for full containerized deployment
- Update Dockerfile to use nvidia/cuda base + pip install PyTorch
  (more reliable than pulling pytorch/pytorch image)
- Simplify docker-compose.cpu.yml
- Update google-generativeai>=0.5.0 (fix system_instruction error)
- Streamline CLAUDE.md (~40% reduction, focus on practical dev tasks)
- Update README.md with new Docker options

Docker usage:
- Local vLLM: ./start_qwen.sh && docker compose up -d
- Full containerized: docker compose -f ... -f docker-compose.full.yml up -d
- CPU mode: docker compose -f ... -f docker-compose.cpu.yml up -d

Co-authored-by: ShaerWare <shaerware@users.noreply.github.com>
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: ShaerWare

CLAUDE.md

@@ -19,14 +19,14 @@ COPY admin/ ./
 RUN npm run build
 
 # -----------------------------------------------------------------------------
-# Stage 2: Python Runtime with CUDA support
+# Stage 2: Python Runtime with CUDA
 # -----------------------------------------------------------------------------
+# Using nvidia/cuda base (smaller, likely cached) + install PyTorch via pip
 FROM nvidia/cuda:12.1.1-runtime-ubuntu22.04 AS runtime
 
-# Prevent interactive prompts during package installation
 ENV DEBIAN_FRONTEND=noninteractive
 
-# System dependencies
+# System dependencies + Python
 RUN apt-get update && apt-get install -y --no-install-recommends \
     python3.11 \
     python3.11-venv \
@@ -42,25 +42,24 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
 
 WORKDIR /app
 
-# Create virtual environment
+# Create venv
 RUN python -m venv /opt/venv
 ENV PATH="/opt/venv/bin:$PATH"
 
-# Upgrade pip
-RUN pip install --no-cache-dir --upgrade pip setuptools wheel
+# Install PyTorch + torchaudio (with pip cache for resume on network issues)
+RUN --mount=type=cache,target=/root/.cache/pip \
+    pip install --upgrade pip setuptools wheel \
+    && pip install torch==2.3.1 torchaudio==2.3.1 \
+       --index-url https://download.pytorch.org/whl/cu121
 
-# Install PyTorch with CUDA support first (large dependency)
-RUN pip install --no-cache-dir \
-    torch==2.1.2 \
-    torchaudio==2.1.2 \
-    --index-url https://download.pytorch.org/whl/cu121
-
-# Install remaining Python dependencies
+# Install remaining dependencies
 COPY requirements.txt .
-RUN pip install --no-cache-dir -r requirements.txt
+RUN --mount=type=cache,target=/root/.cache/pip \
+    pip install -r requirements.txt
 
 # Application code
 COPY *.py ./
+COPY app/ ./app/
 COPY db/ ./db/
 COPY alembic/ ./alembic/
 COPY alembic.ini ./
@@ -119,14 +118,16 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
 
 WORKDIR /app
 
-# Install Python dependencies (CPU versions)
+# Install Python dependencies (CPU versions, uses cache mount)
 COPY requirements.txt .
-RUN pip install --no-cache-dir --upgrade pip setuptools wheel \
-    && pip install --no-cache-dir torch torchaudio --index-url https://download.pytorch.org/whl/cpu \
-    && pip install --no-cache-dir -r requirements.txt
+RUN --mount=type=cache,target=/root/.cache/pip \
+    pip install --upgrade pip setuptools wheel \
+    && pip install torch torchaudio --index-url https://download.pytorch.org/whl/cpu \
+    && pip install -r requirements.txt
 
 # Application code
 COPY *.py ./
+COPY app/ ./app/
 COPY db/ ./db/
 COPY alembic/ ./alembic/
 COPY alembic.ini ./

Dockerfile

@@ -87,10 +87,14 @@ cd AI_Secretary_System
 cp .env.docker .env
 # Edit .env: set GEMINI_API_KEY for cloud fallback
 
-# GPU Mode (XTTS + vLLM) - requires NVIDIA GPU 12GB+
-docker compose up -d
+# Option 1: Use LOCAL vLLM (recommended - faster, no 9GB download)
+./start_qwen.sh                    # Start local vLLM first
+docker compose up -d               # Start orchestrator + redis
 
-# CPU Mode (Piper + Gemini) - no GPU required
+# Option 2: FULL containerized (downloads ~9GB vLLM image)
+docker compose -f docker-compose.yml -f docker-compose.full.yml up -d
+
+# Option 3: CPU Mode (Piper + Gemini) - no GPU required
 docker compose -f docker-compose.yml -f docker-compose.cpu.yml up -d
 
 # Check status

README.md

@@ -1,16 +1,12 @@
 # =============================================================================
-# AI Secretary System - Docker Compose Override (CPU Mode)
+# AI Secretary System - CPU Mode (no GPU required)
 # =============================================================================
 #
+# Uses Piper TTS (CPU) + Gemini API instead of XTTS + vLLM.
+#
 # Usage:
 #   docker compose -f docker-compose.yml -f docker-compose.cpu.yml up -d
 #
-# This override file:
-#   - Uses CPU-only image (smaller, no CUDA)
-#   - Disables vLLM service
-#   - Sets Gemini as default LLM backend
-#   - Uses Piper TTS instead of XTTS
-#
 # =============================================================================
 
 services:
@@ -19,25 +15,13 @@ services:
       target: cpu
     image: ai-secretary:cpu
     environment:
-      # Override to use cloud LLM
+      # Use cloud LLM instead of local vLLM
       - LLM_BACKEND=gemini
       - VLLM_API_URL=
+      - GEMINI_API_KEY=${GEMINI_API_KEY:?GEMINI_API_KEY required for CPU mode}
       # Disable CUDA
       - CUDA_VISIBLE_DEVICES=
-    depends_on:
-      redis:
-        condition: service_healthy
-      # Remove vLLM dependency
     deploy:
       resources:
         reservations:
-          devices: []
-
-  # Disable vLLM service in CPU mode
-  vllm:
-    profiles:
-      - gpu-only
-
-  # Redis still used for caching
-  redis:
-    # No changes needed
+          devices: []  # No GPU

docker-compose.cpu.yml

@@ -0,0 +1,79 @@
+# =============================================================================
+# AI Secretary System - Full Containerized Setup (with vLLM container)
+# =============================================================================
+#
+# Use this for production deployment or CI/CD where you need everything in Docker.
+# WARNING: vLLM image is ~9GB, first pull takes time.
+#
+# Usage:
+#   docker compose -f docker-compose.yml -f docker-compose.full.yml up -d
+#
+# =============================================================================
+
+services:
+  orchestrator:
+    environment:
+      # Override to use containerized vLLM
+      - VLLM_API_URL=http://vllm:8000/v1
+    extra_hosts: []  # Remove host.docker.internal
+    depends_on:
+      redis:
+        condition: service_healthy
+      vllm:
+        condition: service_healthy
+    volumes:
+      # Persistent data
+      - ./data:/app/data
+      - ./logs:/app/logs
+      - ./models:/app/models
+      # Voice samples
+      - ./Гуля:/app/Гуля:ro
+      - ./Лидия:/app/Лидия:ro
+      # Named volumes for caches (not host mounts)
+      - tts_cache:/root/.local/share/tts
+      - hf_cache:/root/.cache/huggingface
+
+  # ---------------------------------------------------------------------------
+  # vLLM - Local LLM Inference Server (containerized)
+  # ---------------------------------------------------------------------------
+  vllm:
+    image: vllm/vllm-openai:latest
+    container_name: ai-secretary-vllm
+    command: >
+      --model ${VLLM_MODEL:-Qwen/Qwen2.5-7B-Instruct-AWQ}
+      --gpu-memory-utilization 0.5
+      --max-model-len 4096
+      --dtype float16
+      --max-num-seqs 32
+      --enforce-eager
+      --trust-remote-code
+      --host 0.0.0.0
+      --port 8000
+    volumes:
+      - hf_cache:/root/.cache/huggingface
+      - ./finetune/adapters:/app/adapters:ro
+    environment:
+      - HUGGING_FACE_HUB_TOKEN=${HF_TOKEN:-}
+      - VLLM_LOGGING_LEVEL=WARNING
+    deploy:
+      resources:
+        reservations:
+          devices:
+            - driver: nvidia
+              count: 1
+              capabilities: [gpu]
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 20
+      start_period: 180s
+    restart: unless-stopped
+    networks:
+      - ai-secretary
+
+volumes:
+  tts_cache:
+    driver: local
+  hf_cache:
+    driver: local

docker-compose.full.yml

@@ -1,16 +1,16 @@
 # =============================================================================
-# AI Secretary System - Docker Compose (GPU Mode)
+# AI Secretary System - Docker Compose
 # =============================================================================
 #
+# Default: Uses LOCAL vLLM (start with ./start_qwen.sh before docker compose)
+#
 # Usage:
-#   docker compose up -d                    # Start all services
-#   docker compose logs -f orchestrator     # View logs
-#   docker compose down                     # Stop all services
+#   ./start_qwen.sh                    # Start local vLLM first
+#   docker compose up -d               # Start orchestrator + redis
+#   docker compose logs -f orchestrator
 #
-# Requirements:
-#   - NVIDIA GPU with 12GB+ VRAM
-#   - NVIDIA Container Toolkit installed
-#   - Docker Compose v2.x
+# For FULL containerized setup (downloads ~9GB vLLM image):
+#   docker compose -f docker-compose.yml -f docker-compose.full.yml up -d
 #
 # =============================================================================
 
@@ -32,19 +32,19 @@ services:
       - ./data:/app/data
       - ./logs:/app/logs
       - ./models:/app/models
-      # Voice samples (read-only, already in image but can override)
+      # Voice samples
       - ./Гуля:/app/Гуля:ro
       - ./Лидия:/app/Лидия:ro
-      # Model caches (named volumes for persistence)
-      - tts_cache:/root/.cache/tts_models
-      - hf_cache:/root/.cache/huggingface
+      # Mount LOCAL caches (no re-download)
+      - ${HOME}/.cache/huggingface:/root/.cache/huggingface
+      - ${HOME}/.local/share/tts:/root/.local/share/tts
     environment:
-      # LLM Configuration
+      # LLM - connect to LOCAL vLLM on host
       - LLM_BACKEND=${LLM_BACKEND:-vllm}
-      - VLLM_API_URL=http://vllm:8000/v1
+      - VLLM_API_URL=http://host.docker.internal:11434/v1
       - VLLM_MODEL_NAME=${VLLM_MODEL_NAME:-}
       - SECRETARY_PERSONA=${SECRETARY_PERSONA:-gulya}
-      # Cloud LLM (optional fallback)
+      # Cloud LLM fallback
       - GEMINI_API_KEY=${GEMINI_API_KEY:-}
       # Database
       - REDIS_URL=redis://redis:6379/0
@@ -53,12 +53,12 @@ services:
       - ADMIN_JWT_SECRET=${ADMIN_JWT_SECRET:-}
       # TTS
       - COQUI_TOS_AGREED=1
-      - TTS_CACHE_PATH=/root/.cache/tts_models
+      - TTS_CACHE_PATH=/root/.local/share/tts
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
     depends_on:
       redis:
         condition: service_healthy
-      vllm:
-        condition: service_healthy
     deploy:
       resources:
         reservations:
@@ -76,45 +76,6 @@ services:
       retries: 3
       start_period: 60s
 
-  # ---------------------------------------------------------------------------
-  # vLLM - Local LLM Inference Server
-  # ---------------------------------------------------------------------------
-  vllm:
-    image: vllm/vllm-openai:latest
-    container_name: ai-secretary-vllm
-    command: >
-      --model ${VLLM_MODEL:-Qwen/Qwen2.5-7B-Instruct-AWQ}
-      --gpu-memory-utilization 0.5
-      --max-model-len 4096
-      --dtype float16
-      --max-num-seqs 32
-      --enforce-eager
-      --trust-remote-code
-      --host 0.0.0.0
-      --port 8000
-    volumes:
-      - hf_cache:/root/.cache/huggingface
-      - ./finetune/adapters:/app/adapters:ro
-    environment:
-      - HUGGING_FACE_HUB_TOKEN=${HF_TOKEN:-}
-      - VLLM_LOGGING_LEVEL=WARNING
-    deploy:
-      resources:
-        reservations:
-          devices:
-            - driver: nvidia
-              count: 1
-              capabilities: [gpu]
-    healthcheck:
-      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
-      interval: 30s
-      timeout: 10s
-      retries: 20
-      start_period: 180s
-    restart: unless-stopped
-    networks:
-      - ai-secretary
-
   # ---------------------------------------------------------------------------
   # Redis - Caching and Rate Limiting
   # ---------------------------------------------------------------------------
@@ -139,10 +100,6 @@ services:
 volumes:
   redis_data:
     driver: local
-  tts_cache:
-    driver: local
-  hf_cache:
-    driver: local
 
 # =============================================================================
 # Networks

docker-compose.yml

@@ -23,16 +23,21 @@ pydub==0.25.1
 python-telegram-bot==21.0.1
 
 # AI Integration
-google-generativeai==0.3.2
+google-generativeai>=0.5.0
 requests==2.31.0
 aiohttp==3.9.1
 
 # Utils
 python-dotenv==1.0.0
 pydantic==2.5.3
 numpy==1.24.3
-torch==2.1.2
-torchaudio==2.1.2
+
+# PyTorch (installed separately in Dockerfile for CUDA support)
+# torch==2.3.1
+# torchaudio==2.3.1
+
+# Pin transformers for TTS compatibility
+transformers>=4.41.0,<5.0.0
 
 # System monitoring
 psutil==5.9.8