Fix build cache, DNS/model download, and AI Edit error handling

Build / pip layer fixes:
- Add BUILDID ARG to Dockerfile.gpu; pass from docker-compose.gpu.yml build args
  so pip layers can be force-busted without --no-cache:
    BUILDID=$(date +%s) docker compose -f docker-compose.gpu.yml up --build

Model download (DNS-blocked environments):
- Change HF model cache from named volume to ./data/hf_cache bind mount
  so models can be pre-downloaded on the host (no rebuild needed)
- Remove now-unused hf_model_cache named volume
- README: add iptables fix + huggingface-cli offline download instructions

Error handling improvements:
- ai_edit_region: catch ConnectError/Errno-3 → return 503 with exact fix commands
- _require_remote: give actionable message when local_gpu provider fails to load
- _build_provider: catch AttributeError (torch.xpu from wrong diffusers) not just ImportError
- local_diffusion.py: fix docstring to reflect <0.29.0 pin

https://claude.ai/code/session_01WVDg7amsy1TTtxvpku7bcM

backend/app/routers/ai_tools.py

@@ -80,8 +80,19 @@ def _encode(data: bytes) -> str:
 
 def _require_remote(operation: str = None):
     from app.services.remote_provider import get_remote_provider
+    from app.config import settings
     provider = get_remote_provider(operation)
     if provider is None:
+        if (settings.ai_provider or "").lower() == "local_gpu":
+            raise HTTPException(
+                status_code=503,
+                detail=(
+                    "local_gpu provider failed to load — diffusers may be incompatible with "
+                    "the installed PyTorch version. Check container logs for details. "
+                    "If you see 'torch has no attribute xpu', rebuild the container from the "
+                    "correct branch so the pinned diffusers<0.29.0 is installed."
+                )
+            )
         op_hint = f"AI_PROVIDER_{operation.upper()} or " if operation else ""
         raise HTTPException(
             status_code=503,
@@ -502,12 +513,28 @@ async def ai_edit_region(req: AiEditRegionRequest):
     Works with local_gpu, InvokeAI, ComfyUI, or OpenAI.
     """
     provider = _require_remote("inpaint")
-    result_bytes = await provider.inpaint(
-        _decode(req.image),
-        _decode(req.mask),
-        req.instruction,
-        {"negative_prompt": req.negative_prompt, "steps": req.steps, "cfg_scale": req.cfg_scale},
-    )
+    try:
+        result_bytes = await provider.inpaint(
+            _decode(req.image),
+            _decode(req.mask),
+            req.instruction,
+            {"negative_prompt": req.negative_prompt, "steps": req.steps, "cfg_scale": req.cfg_scale},
+        )
+    except Exception as exc:
+        import traceback; traceback.print_exc()
+        msg = str(exc)
+        if "Errno -3" in msg or "Name or service not known" in msg or "ConnectError" in msg:
+            raise HTTPException(
+                status_code=503,
+                detail=(
+                    "AI model files not yet downloaded — container DNS appears to be blocked. "
+                    "Fix: sudo iptables -I DOCKER-USER -p udp --dport 53 -j ACCEPT on the host, "
+                    "or pre-download the model: pip install huggingface-hub && "
+                    "huggingface-cli download diffusers/stable-diffusion-xl-1.0-inpainting-0.1 "
+                    "--cache-dir ./data/hf_cache"
+                )
+            )
+        raise HTTPException(status_code=500, detail=msg)
     return {"result": _encode(result_bytes)}
 
 

backend/app/services/local_diffusion.py

@@ -11,8 +11,8 @@ Supported model families:
   sd2x  → StableDiffusion2*Pipeline               (SD 2.x)
   sd15  → StableDiffusionPipeline                 (SD 1.5)
 
-Requires: diffusers>=0.29.0, transformers, accelerate, safetensors
-          (all in requirements.gpu.txt)
+Requires: diffusers>=0.28.0,<0.29.0, transformers, accelerate, safetensors
+          (all in requirements.gpu.txt — pinned <0.29.0 for PyTorch 2.1.x compatibility)
 """
 from __future__ import annotations
 

backend/app/services/remote_provider.py

@@ -432,7 +432,8 @@ def _build_provider(name: str) -> Optional[RemoteAIProvider]:
         try:
             from app.services.local_diffusion import get_local_diffusion_provider
             return get_local_diffusion_provider(max_pipelines=settings.local_gpu_max_pipelines)
-        except ImportError:
+        except (ImportError, AttributeError) as exc:
+            print(f"[local_gpu] Cannot load diffusion provider: {exc}")
             return None
 
     return None