feat: add vLLM as alternative inference backend (#1281)

Adds vLLM (high-throughput OpenAI-compatible inference server) as a
selectable backend alongside the existing Ollama and vllm-mlx backends.
vLLM's continuous batching gives 3-10x throughput for agentic workloads.

Changes:
- config.py: add `vllm` to timmy_model_backend Literal; add vllm_url /
  vllm_model settings (VLLM_URL / VLLM_MODEL env vars)
- cascade.py: add vllm provider type with _check_provider_available
  (hits /health) and _call_vllm (OpenAI-compatible completions)
- providers.yaml: add disabled-by-default vllm-local provider (priority 3,
  port 8001); bump OpenAI/Anthropic backup priorities to 4/5
- health.py: add _check_vllm/_check_vllm_sync with 30-second TTL cache;
  /health and /health/sovereignty reflect vLLM status when it is the
  active backend
- docker-compose.yml: add vllm service behind 'vllm' profile (GPU
  passthrough commented-out template included); add vllm-cache volume
- CLAUDE.md: add vLLM row to Service Fallback Matrix
- tests: 26 new unit tests covering availability checks, _call_vllm,
  providers.yaml validation, config options, and health helpers

Graceful fallback: if vLLM is unavailable the cascade router automatically
falls back to Ollama. The app never crashes.

Fixes #1281

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

docker-compose.yml

@@ -42,6 +42,10 @@ services:
       GROK_ENABLED: "${GROK_ENABLED:-false}"
       XAI_API_KEY: "${XAI_API_KEY:-}"
       GROK_DEFAULT_MODEL: "${GROK_DEFAULT_MODEL:-grok-3-fast}"
+      # vLLM backend — set TIMMY_LLM_BACKEND=vllm to activate
+      TIMMY_LLM_BACKEND: "${TIMMY_LLM_BACKEND:-ollama}"
+      VLLM_URL: "${VLLM_URL:-http://localhost:8001}"
+      VLLM_MODEL: "${VLLM_MODEL:-Qwen/Qwen2.5-14B-Instruct}"
     extra_hosts:
       - "host.docker.internal:host-gateway"  # Linux: maps to host IP
     networks:
@@ -74,6 +78,49 @@ services:
     profiles:
       - celery
 
+  # ── vLLM — high-throughput inference server (GPU optional) ──────────────
+  # Requires the 'vllm' profile: docker compose --profile vllm up
+  #
+  # GPU (NVIDIA):  set VLLM_MODEL and ensure nvidia-container-toolkit is installed.
+  # CPU-only:      add --device cpu to VLLM_EXTRA_ARGS (slower, but works anywhere).
+  #
+  # The dashboard reaches vLLM at http://vllm:8001 (inside timmy-net).
+  # Set VLLM_URL=http://vllm:8001 in the dashboard environment when using this service.
+  vllm:
+    image: vllm/vllm-openai:latest
+    container_name: timmy-vllm
+    profiles:
+      - vllm
+    ports:
+      - "8001:8001"
+    environment:
+      # Model to load — override with VLLM_MODEL env var
+      VLLM_MODEL: "${VLLM_MODEL:-Qwen/Qwen2.5-7B-Instruct}"
+    command: >
+      --model ${VLLM_MODEL:-Qwen/Qwen2.5-7B-Instruct}
+      --port 8001
+      --host 0.0.0.0
+      ${VLLM_EXTRA_ARGS:-}
+    volumes:
+      - vllm-cache:/root/.cache/huggingface
+    networks:
+      - timmy-net
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8001/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 5
+      start_period: 120s
+    # GPU support — uncomment to enable NVIDIA GPU passthrough
+    # deploy:
+    #   resources:
+    #     reservations:
+    #       devices:
+    #         - driver: nvidia
+    #           count: all
+    #           capabilities: [gpu]
+
   # ── OpenFang — vendored agent runtime sidecar ────────────────────────────
   openfang:
     build:
@@ -110,6 +157,8 @@ volumes:
       device: "${PWD}/data"
   openfang-data:
     driver: local
+  vllm-cache:
+    driver: local
 
 # ── Internal network ────────────────────────────────────────────────────────
 networks: