Clarify Cookbook diffusion dependencies

README.md

@@ -77,6 +77,13 @@ chat model picker automatically. For NVIDIA GPUs in Docker, install the NVIDIA
 Container Toolkit and add `gpus: all` to the `odysseus` service if `nvidia-smi`
 is not visible inside the container.
 
+The default Docker image is intentionally slim. For Python-based serve engines,
+use **Cookbook -> Dependencies** to install vLLM, SGLang, llama-cpp-python, or
+diffusers into the persisted `./data/local` mount. Native CUDA builds inside the
+container also require CUDA toolkit binaries such as `nvcc`; if those are not
+installed in the container, use prebuilt Python wheels or serve from a remote
+GPU host that already has the toolkit.
+
 Useful checks:
 ```bash
 docker compose ps

routes/cookbook_routes.py

@@ -151,6 +151,11 @@ def setup_cookbook_routes() -> APIRouter:
                 "llama.cpp / llama-cpp-python dependencies are missing.",
                 [{"label": "install llama.cpp dependencies or llama-cpp-python[server]", "op": "dependency", "package": "llama-cpp-python[server]"}],
             ),
+            (
+                r"No module named 'torch'|No module named torch|No module named 'diffusers'|No module named diffusers",
+                "Diffusion serving requires PyTorch and diffusers.",
+                [{"label": "install diffusers[torch] in Cookbook Dependencies", "op": "dependency", "package": "diffusers[torch]"}],
+            ),
             (
                 r"403 Forbidden|401 Unauthorized|Access to model.*is restricted|gated repo|not in the authorized list|awaiting a review",
                 "Model access is gated or unauthorized.",
@@ -896,6 +901,12 @@ def setup_cookbook_routes() -> APIRouter:
                 runner_lines.append('  echo "ERROR: SGLang is not installed. Open Cookbook -> Dependencies and install sglang on this server, then launch again."')
                 runner_lines.append('  exit 127')
                 runner_lines.append('fi')
+            elif "scripts/diffusion_server.py" in req.cmd or ".diffusion_server.py" in req.cmd:
+                runner_lines.append('export PATH="$HOME/.local/bin:$PATH"')
+                runner_lines.append('if ! python3 -c "import torch, diffusers" 2>/dev/null; then')
+                runner_lines.append('  echo "ERROR: Diffusion serving requires PyTorch + diffusers. Open Cookbook -> Dependencies and install diffusers on this server, then launch again."')
+                runner_lines.append('  exit 127')
+                runner_lines.append('fi')
 
             runner_lines.append(req.cmd)
             # Keep shell open after exit so user can see errors

routes/shell_routes.py

@@ -501,7 +501,7 @@ def setup_shell_routes() -> APIRouter:
             {"name": "sglang", "pip": "sglang[all]", "desc": "Serve HF safetensors models via SGLang", "category": "LLM", "target": "remote"},
             {"name": "vllm", "pip": "vllm", "desc": "High-throughput LLM serving engine", "category": "LLM", "target": "remote"},
             # ── Image ── editor + diffusion model serving
-            {"name": "diffusers", "pip": "diffusers", "desc": "Image generation pipelines (SD, Flux)", "category": "Image", "target": "remote"},
+            {"name": "diffusers", "pip": "diffusers[torch]", "desc": "Image generation pipelines (SD, Flux) with PyTorch", "category": "Image", "target": "remote"},
             {"name": "rembg", "pip": "rembg[gpu]", "desc": "AI background removal for image editor", "category": "Image", "target": "local"},
             {"name": "realesrgan", "pip": "realesrgan", "desc": "AI denoise + upscale (Real-ESRGAN). Used by editor's Denoise and Upscale tools.", "category": "Image", "target": "local"},
             # ── Tools ──
@@ -600,7 +600,7 @@ def setup_shell_routes() -> APIRouter:
             return {"ok": False, "error": "No package specified"}
         # Validate against known packages to prevent arbitrary pip install
         known = {
-            "rembg[gpu]", "hf_transfer", "llama-cpp-python[server]", "sglang[all]", "diffusers",
+            "rembg[gpu]", "hf_transfer", "llama-cpp-python[server]", "sglang[all]", "diffusers", "diffusers[torch]",
             "TTS", "bark", "faster-whisper", "playwright", "realesrgan", "gfpgan",
             "insightface", "onnxruntime-gpu", "onnxruntime", "hdbscan",
         }

static/js/cookbook-diagnosis.js

@@ -323,10 +323,10 @@ export const ERROR_PATTERNS = [
     ],
   },
   {
-    pattern: /diffusers.*No module named|diffusers.*command not found/i,
+    pattern: /No module named ['"]?torch|No module named ['"]?diffusers|diffusers.*command not found/i,
-    message: 'Diffusers is not installed. Run: pip install diffusers transformers accelerate',
+    message: 'Diffusion serving needs PyTorch and diffusers. Install diffusers from Cookbook → Dependencies.',
     fixes: [
-      { label: 'Copy install command', action: () => _copyText('pip install diffusers transformers accelerate') },
+      { label: 'Copy install command', action: () => _copyText('python3 -m pip install "diffusers[torch]"') },
     ],
   },
   {