@quybt93/pcgf 0.0.1

package/plugins/phaser-casual-game-factory/skills/game-art/client/test_restyle_tools.py

@@ -0,0 +1,256 @@
+#!/usr/bin/env python3
+"""Test offline cho 4 tool restyle của gemini_image_mcp — KHÔNG cần cookie/Gemini/mạng.
+
+Bao phủ các rào AN TOÀN của apply_asset (nơi có thể phá hỏng asset gốc của người dùng) và
+đường happy của plan_asset/make_contact_sheet/restyle_asset (phần không gọi mạng).
+
+Chạy: `python test_restyle_tools.py`  (in PASS/FAIL từng dòng + tổng kết, KHÔNG phải JSON)
+"""
+import asyncio
+import shutil
+import sys
+import tempfile
+from pathlib import Path
+
+if hasattr(sys.stdout, "reconfigure"):
+    sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+
+sys.path.insert(0, str(Path(__file__).parent))
+import gemini_image_mcp as G
+from PIL import Image
+
+_fails = 0
+
+
+def check(name: str, cond: bool, detail: str = "") -> None:
+    global _fails
+    if cond:
+        print(f"  PASS  {name}")
+    else:
+        _fails += 1
+        print(f"  FAIL  {name}  {detail}")
+
+
+def _fn(tool):
+    return getattr(tool, "fn", tool)
+
+
+def _png(path: Path, size=(32, 32), color=(200, 30, 40, 255)) -> None:
+    Image.new("RGBA", size, color).save(path)
+
+
+async def run() -> int:
+    tmp = Path(tempfile.mkdtemp(prefix="restyle_tools_"))
+    try:
+        # --- plan_asset ---
+        asset = tmp / "asset.png"
+        # asset đỏ đặc -> key an toàn phải là xanh lá
+        _png(asset, size=(48, 48), color=(200, 30, 40, 255))
+        r = await _fn(G.plan_asset)(str(asset), avoid=["#F5DA55", "#4FB48D"])
+        check("plan_asset no error", "error" not in r, str(r))
+        check("plan_asset size", r.get("width") == 48 and r.get("height") == 48, str(r))
+        check("plan_asset key hex", str(r.get("key", "")).startswith("#"), str(r))
+        check("plan_asset key_safe present", "key_safe" in r, str(r))
+        check("plan_asset palette list", isinstance(r.get("palette"), list), str(r))
+
+        # plan_asset trên file không tồn tại -> error, không raise
+        r = await _fn(G.plan_asset)(str(tmp / "nope.png"))
+        check("plan_asset missing -> error", "error" in r, str(r))
+
+        # --- make_contact_sheet ---
+        a, b = tmp / "a.png", tmp / "b.png"
+        _png(a, color=(200, 30, 40, 255))
+        _png(b, color=(30, 200, 40, 255))
+        sheet = tmp / "sheet.png"
+        r = await _fn(G.make_contact_sheet)(["orig", "v1"], [str(a), str(b)], str(sheet))
+        check("make_contact_sheet ok", "error" not in r and sheet.is_file(), str(r))
+        r = await _fn(G.make_contact_sheet)(["x"], [str(a), str(b)], str(tmp / "s2.png"))
+        check("make_contact_sheet mismatch -> error", "error" in r, str(r))
+
+        # --- restyle_asset arg-validation (không chạm mạng) ---
+        r = await _fn(G.restyle_asset)(prompt="p", image_paths=[str(a)], n=0)
+        check("restyle_asset n<1 -> error", "error" in r, str(r))
+        r = await _fn(G.restyle_asset)(prompt="p", image_paths=[str(a)])  # thiếu src và size
+        check("restyle_asset no src/size -> error", "error" in r, str(r))
+
+        # --- process_raws (postprocess ảnh thô sinh từ CLI ngoài — thuần offline) ---
+        # Ép đường chroma-key để test không kéo BEN2/torch (máy có model vẫn chạy nhanh).
+        _avail = G.bgremove.available
+        G.bgremove.available = lambda: False
+        try:
+            r = await _fn(G.process_raws)([], src=str(asset))
+            check("process_raws empty -> error", "error" in r, str(r))
+            r = await _fn(G.process_raws)([str(a)])  # thiếu src và size
+            check("process_raws no src/size -> error", "error" in r, str(r))
+            r = await _fn(G.process_raws)([str(a)], src=str(asset), prefix="../evil")
+            check("process_raws bad prefix -> error", "error" in r, str(r))
+
+            # happy path: raw = chủ thể đỏ trên nền key xanh lá; raw thứ hai không tồn tại
+            raw = tmp / "raw_agy.png"
+            raw_img = Image.new("RGBA", (64, 64), (0, 255, 0, 255))
+            raw_img.paste(Image.new("RGBA", (32, 32), (200, 30, 40, 255)), (16, 16))
+            raw_img.save(raw)
+            outd = tmp / "proc_out"
+            r = await _fn(G.process_raws)(
+                [str(raw), str(tmp / "ghost.png")], src=str(asset),
+                key="#00FF00", out_dir=str(outd), prefix="agy",
+            )
+            check("process_raws no error", "error" not in r, str(r))
+            # `remover` ở cấp NGOÀI = danh sách ứng viên khả dụng ("multi" = không có BEN2,
+            # "multi+ben2" = có). Cách THẬT SỰ dùng cho từng ảnh nằm ở variants[i]
+            # ["cutout_method"] — vì tách nền chạy nhiều cách rồi chấm điểm chọn, nên một
+            # giá trị duy nhất ở cấp ngoài không thể nói đúng cho mọi ảnh.
+            check("process_raws remover = danh sach ung vien",
+                  r.get("remover") in ("multi", "multi+ben2"), str(r))
+            check("process_raws bao cach da thang cho tung anh",
+                  all(x.get("cutout_method") for x in r.get("variants") or []), str(r))
+            check("process_raws 1 produced + 1 error",
+                  r.get("n_produced") == 1 and len(r.get("errors", [])) == 1, str(r))
+            v = (r.get("variants") or [{}])[0]
+            check("process_raws out named agy1.png",
+                  str(v.get("out") or "").endswith("agy1.png") and (outd / "agy1.png").is_file(), str(r))
+            check("process_raws out size = src",
+                  (outd / "agy1.png").is_file() and Image.open(outd / "agy1.png").size == (48, 48), str(r))
+            check("process_raws key_auto False khi key đúng", v.get("key_auto") is False, str(v))
+
+            # auto-key: model vẽ nền "xanh studio" #2ED246 thay vì key #00FF00 được yêu cầu
+            # (ca thật, đo trên agy/Nano Banana) -> chroma-key theo key yêu cầu trượt cả khung;
+            # tool phải tự dò màu nền từ vành và key lại, KHÔNG báo bad_background.
+            raw_studio = tmp / "raw_studio.png"
+            studio = Image.new("RGBA", (64, 64), (46, 210, 70, 255))
+            studio.paste(Image.new("RGBA", (32, 32), (200, 30, 40, 255)), (16, 16))
+            studio.save(raw_studio)
+            r = await _fn(G.process_raws)(
+                [str(raw_studio)], src=str(asset), key="#00FF00",
+                out_dir=str(tmp / "proc_auto"), prefix="agy",
+            )
+            v = (r.get("variants") or [{}])[0]
+            check("autokey rescued (key_auto True)", v.get("key_auto") is True, str(v))
+            check("autokey no bad_background", "bad_background" not in (v.get("flags") or []), str(v))
+            check("autokey key = màu dò được", v.get("key") != "#00FF00", str(v))
+            check("autokey key_requested giữ màu gốc", v.get("key_requested") == "#00FF00", str(v))
+            check("autokey out file exists",
+                  v.get("out") is not None and Path(v["out"]).is_file(), str(v))
+
+            # nền ĐÚNG key mà vẫn bẩn một phần (bóng đổ lớn) -> auto-key KHÔNG được kích hoạt
+            # (coverage không vượt BAD_HIGH; ca này phải sinh lại, không cứu bằng đổi key)
+            raw_shadow = tmp / "raw_shadow.png"
+            shadow = Image.new("RGBA", (64, 64), (0, 255, 0, 255))
+            shadow.paste(Image.new("RGBA", (32, 32), (200, 30, 40, 255)), (16, 16))
+            shadow.paste(Image.new("RGBA", (64, 10), (90, 120, 90, 255)), (0, 54))  # dải bóng
+            shadow.save(raw_shadow)
+            r = await _fn(G.process_raws)(
+                [str(raw_shadow)], src=str(asset), key="#00FF00",
+                out_dir=str(tmp / "proc_shadow"), prefix="agy",
+            )
+            v = (r.get("variants") or [{}])[0]
+            check("partial-dirty bg: key_auto stays False", v.get("key_auto") is False, str(v))
+        finally:
+            G.bgremove.available = _avail
+
+        # --- slice_sheet (chế độ screen sheet — thuần offline, ép chroma-key) ---
+        _avail2 = G.bgremove.available
+        G.bgremove.available = lambda: False
+        try:
+            # Sheet 200x200: nửa trên = mockup xanh dương; nửa dưới = nền key + 3 chi tiết
+            # (hàng 1: đỏ rồi vàng; hàng 2: teal) + 1 speck 5x5 phải bị bỏ.
+            sheet = tmp / "sheet.png"
+            sh = Image.new("RGBA", (200, 200), (0, 255, 0, 255))
+            sh.paste(Image.new("RGBA", (200, 100), (40, 60, 200, 255)), (0, 0))      # mockup
+            sh.paste(Image.new("RGBA", (30, 20), (200, 30, 40, 255)), (10, 115))     # cell 1
+            sh.paste(Image.new("RGBA", (24, 24), (230, 200, 40, 255)), (70, 112))    # cell 2
+            sh.paste(Image.new("RGBA", (40, 16), (30, 180, 170, 255)), (20, 165))    # cell 3
+            sh.paste(Image.new("RGBA", (5, 5), (10, 10, 10, 255)), (150, 130))       # speck
+            sh.save(sheet)
+            outd2 = tmp / "sliced"
+            r = await _fn(G.slice_sheet)(str(sheet), key="#00FF00", out_dir=str(outd2),
+                                         prefix="agy", mockup_frac=0.5, min_cell=12)
+            check("slice_sheet no error", "error" not in r, str(r))
+            check("slice_sheet mockup saved",
+                  r.get("mockup") and Path(r["mockup"]).name == "agy_mockup.png"
+                  and Path(r["mockup"]).is_file(), str(r))
+            check("slice_sheet mockup size", Image.open(outd2 / "agy_mockup.png").size == (200, 100), "")
+            check("slice_sheet 3 cells (speck bị bỏ)", r.get("n_cells") == 3, str(r))
+            cells = r.get("cells") or []
+            check("slice_sheet thứ tự đọc: đỏ, vàng, teal",
+                  len(cells) == 3 and cells[0]["box"][0] < cells[1]["box"][0]
+                  and cells[2]["box"][1] > cells[0]["box"][1], str(cells))
+            check("slice_sheet cell files exist",
+                  all(c.get("out") and Path(c["out"]).is_file() for c in cells), str(cells))
+            check("slice_sheet key_auto False khi nền đúng key", r.get("key_auto") is False, str(r))
+
+            # nền dải lệch key (xanh studio) -> tự dò key, vẫn cắt được cells
+            sheet2 = tmp / "sheet_studio.png"
+            sh2 = Image.new("RGBA", (120, 120), (46, 210, 70, 255))
+            sh2.paste(Image.new("RGBA", (120, 60), (40, 60, 200, 255)), (0, 0))
+            sh2.paste(Image.new("RGBA", (30, 30), (200, 30, 40, 255)), (20, 75))
+            sh2.save(sheet2)
+            r = await _fn(G.slice_sheet)(str(sheet2), key="#00FF00", out_dir=str(tmp / "sliced2"),
+                                         prefix="agy", mockup_frac=0.5, min_cell=12)
+            check("slice_sheet studio bg -> key_auto True", r.get("key_auto") is True, str(r))
+            check("slice_sheet studio bg vẫn ra 1 cell", r.get("n_cells") == 1, str(r))
+
+            # guard: prefix bẩn / mockup_frac ngoài khoảng
+            r = await _fn(G.slice_sheet)(str(sheet), key="#00FF00", out_dir=str(outd2), prefix="../x")
+            check("slice_sheet bad prefix -> error", "error" in r, str(r))
+            r = await _fn(G.slice_sheet)(str(sheet), key="#00FF00", out_dir=str(outd2), mockup_frac=0.95)
+            check("slice_sheet bad mockup_frac -> error", "error" in r, str(r))
+        finally:
+            G.bgremove.available = _avail2
+
+        # --- apply_asset happy path ---
+        proj = tmp / "proj"
+        (proj / "assets").mkdir(parents=True)
+        dst = proj / "assets" / "icon.png"
+        _png(dst, color=(10, 10, 10, 255))            # bản gốc
+        variant = tmp / "variant.png"
+        _png(variant, color=(240, 240, 240, 255))     # bản mới
+        bdir = proj / "backup"
+        r = await _fn(G.apply_asset)(str(variant), str(dst), str(bdir), project_root=str(proj))
+        check("apply_asset happy applied", "applied" in r, str(r))
+        bak = Path(r["backup"]) if "applied" in r else None
+        check("apply_asset backup exists", bak is not None and bak.is_file(), str(r))
+        check("apply_asset dst=variant color",
+              Image.open(dst).convert("RGBA").getpixel((0, 0)) == (240, 240, 240, 255))
+        check("apply_asset backup=orig color",
+              bak is not None and Image.open(bak).convert("RGBA").getpixel((0, 0)) == (10, 10, 10, 255))
+
+        # apply lần 2: backup KHÔNG bị ghi đè (vẫn giữ bản gốc thật)
+        variant2 = tmp / "variant2.png"
+        _png(variant2, color=(1, 2, 3, 255))
+        r2 = await _fn(G.apply_asset)(str(variant2), str(dst), str(bdir), project_root=str(proj))
+        check("apply_asset 2nd applied", "applied" in r2, str(r2))
+        check("apply_asset backup NOT clobbered",
+              bak is not None and Image.open(bak).convert("RGBA").getpixel((0, 0)) == (10, 10, 10, 255))
+
+        # guard: backup trùng dst (backup_dir == project_root, mirror rel path == dst)
+        dst2 = proj / "x.png"
+        _png(dst2, color=(200, 30, 40, 255))
+        r3 = await _fn(G.apply_asset)(str(variant), str(dst2), str(proj), project_root=str(proj))
+        check("apply_asset guard backup==dst -> error", "error" in r3 and "trùng" in r3.get("error", ""), str(r3))
+        check("apply_asset dst2 untouched after refusal",
+              Image.open(dst2).convert("RGBA").getpixel((0, 0)) == (200, 30, 40, 255))
+
+        # guard: dst không .png -> từ chối, file gốc nguyên vẹn
+        notpng = proj / "main.js"
+        notpng.write_text("x", encoding="utf-8")
+        r4 = await _fn(G.apply_asset)(str(variant), str(notpng), str(bdir), project_root=str(proj))
+        check("apply_asset guard dst non-png -> error", "error" in r4 and ".png" in r4.get("error", ""), str(r4))
+        check("apply_asset non-png untouched", notpng.read_text(encoding="utf-8") == "x")
+
+        # guard: variant không tồn tại -> error
+        r5 = await _fn(G.apply_asset)(str(tmp / "ghost.png"), str(dst), str(bdir), project_root=str(proj))
+        check("apply_asset missing variant -> error", "error" in r5, str(r5))
+    finally:
+        shutil.rmtree(tmp, ignore_errors=True)
+
+    print(f"\n{'0 failed' if _fails == 0 else f'{_fails} failed'} — restyle tool guards")
+    return _fails
+
+
+def main() -> int:
+    return asyncio.run(run())
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/plugins/phaser-casual-game-factory/skills/game-art/client/upscale.py

@@ -0,0 +1,289 @@
+"""Phóng to ảnh bằng Real-ESRGAN x4plus_anime_6B (hlky/RealESRGAN_x4plus_anime_6B).
+
+Dùng khi ảnh AI sinh ra NHỎ HƠN kích thước đích: LANCZOS phóng to chỉ trải mép ra
+cho mềm đi, còn model này dựng lại nét. Bản `anime_6B` được huấn luyện riêng cho
+tranh vẽ/anime — đúng loại ảnh của skill này (game art vẽ tay, mảng màu phẳng,
+nét viền rõ) — và chỉ 6 khối RRDB nên nhẹ hơn hẳn bản x4plus 23 khối.
+
+Thiết kế:
+  - KHÔNG phụ thuộc `basicsr`/`realesrgan`. Trọng số trên HF là state-dict RRDBNet
+    chuẩn (conv_first / body.N.rdbM.convK / conv_body / conv_up1,2 / conv_hr /
+    conv_last), nên module này tự dựng lại RRDBNet bằng torch thuần (~70 dòng).
+    `basicsr` kéo theo `torchvision.transforms.functional_tensor` — đã bị gỡ khỏi
+    torchvision >= 0.17, tức là cài vào sẽ GÃY trên môi trường này (tv 0.19).
+  - Tự chứa: trọng số tải về `models/` (root skill) qua HF_HOME, giống bgremove.py.
+  - Nạp LƯỜI: import module này KHÔNG kéo theo torch, nhờ vậy test_imglib.py vẫn
+    chạy offline.
+  - Rớt mềm: thiếu torch / tải trọng số hỏng -> `available()` False, caller quay về
+    LANCZOS. KHÔNG ném lỗi lên pipeline.
+  - Chỉ nhận/trả numpy HxWx3 uint8. Chuyện RGBA (bleed màu ra vùng trong suốt, phóng
+    alpha riêng) nằm ở imglib.upscale_rgba — nhờ vậy test được với backend giả.
+
+ENV:
+  ESRGAN_MODEL    repo HF (mặc định "hlky/RealESRGAN_x4plus_anime_6B").
+  ESRGAN_DEVICE   "cuda" | "cpu" | "auto" (mặc định "auto").
+  ESRGAN_TILE     cạnh ô khi chia ảnh để tránh hết VRAM (mặc định 512, 0 = không chia).
+  ESRGAN_TILE_PAD lề chồng lấn giữa các ô (mặc định 32) — chống thấy đường ghép.
+  ESRGAN_FP16     "1" (mặc định) chạy nửa độ chính xác trên CUDA cho nhanh; "0" để tắt.
+  HF_HOME         nơi chứa/nạp trọng số (mặc định = models/ (root) cạnh file này).
+"""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+import numpy as np
+
+# Trỏ cache HuggingFace vào thư mục skill TRƯỚC khi huggingface_hub được import lần
+# đầu — cùng lý do như bgremove.py: trọng số nằm gọn trong skill, mang đi đâu cũng chạy.
+# Trọng số nằm ở models/ NGANG HÀNG client/ và server/ (dùng chung, không nằm trong
+# client/ để bản client mang đi không dính ~1GB). parent = client/, parent.parent = gốc skill.
+_DEFAULT_MODEL_DIR = Path(__file__).resolve().parent.parent / "models"
+os.environ.setdefault("HF_HOME", str(_DEFAULT_MODEL_DIR))
+os.environ.setdefault("HF_HUB_CACHE", str(_DEFAULT_MODEL_DIR / "hub"))
+
+_MODEL_NAME = os.environ.get("ESRGAN_MODEL", "hlky/RealESRGAN_x4plus_anime_6B")
+_WEIGHTS_FILE = "diffusion_pytorch_model.safetensors"
+
+SCALE = 4                      # model này phóng cố định 4x
+
+_TILE = int(os.environ.get("ESRGAN_TILE", "512"))
+_TILE_PAD = int(os.environ.get("ESRGAN_TILE_PAD", "32"))
+_FP16 = os.environ.get("ESRGAN_FP16", "1") not in ("0", "", "false", "False")
+
+_model = None                  # cache model (nạp lười, chỉ 1 lần)
+_device = None
+_import_ok: bool | None = None
+
+
+def _try_import() -> bool:
+    global _import_ok
+    if _import_ok is None:
+        try:
+            import torch
+            import safetensors.torch  # noqa: F401
+            import huggingface_hub  # noqa: F401
+            # Kiểm CẦU NỐI numpy<->torch chứ không chỉ import — xem chú thích cùng chỗ trong
+            # bgremove.py: numpy 2.x làm torch 2.4 import được nhưng chết ở from_numpy.
+            torch.from_numpy(np.zeros((1, 1), dtype=np.uint8))
+            _import_ok = True
+        except Exception:
+            _import_ok = False
+    return _import_ok
+
+
+def available() -> bool:
+    """torch + safetensors + huggingface_hub có import được không."""
+    return _try_import()
+
+
+def _pick_device():
+    import torch
+
+    want = os.environ.get("ESRGAN_DEVICE", "auto").lower()
+    if want == "cpu":
+        return torch.device("cpu")
+    if want == "cuda":
+        return torch.device("cuda")
+    return torch.device("cuda" if torch.cuda.is_available() else "cpu")
+
+
+# ---------------------------------------------------------------- kiến trúc RRDBNet
+# Chép đúng RRDBNet của BasicSR (ESRGAN) để state-dict trên HF khớp 1-1 tên tham số.
+# Hằng số 0.2 là residual scaling của bài báo ESRGAN, KHÔNG phải số tự chọn — đổi nó
+# là trọng số cho ra ảnh sai.
+
+def _build_net(num_feat: int, num_block: int, num_grow_ch: int, scale: int):
+    import torch
+    import torch.nn as nn
+    import torch.nn.functional as F
+
+    class ResidualDenseBlock(nn.Module):
+        def __init__(self, nf: int, gc: int):
+            super().__init__()
+            self.conv1 = nn.Conv2d(nf, gc, 3, 1, 1)
+            self.conv2 = nn.Conv2d(nf + gc, gc, 3, 1, 1)
+            self.conv3 = nn.Conv2d(nf + 2 * gc, gc, 3, 1, 1)
+            self.conv4 = nn.Conv2d(nf + 3 * gc, gc, 3, 1, 1)
+            self.conv5 = nn.Conv2d(nf + 4 * gc, nf, 3, 1, 1)
+            self.lrelu = nn.LeakyReLU(0.2, inplace=True)
+
+        def forward(self, x):
+            x1 = self.lrelu(self.conv1(x))
+            x2 = self.lrelu(self.conv2(torch.cat((x, x1), 1)))
+            x3 = self.lrelu(self.conv3(torch.cat((x, x1, x2), 1)))
+            x4 = self.lrelu(self.conv4(torch.cat((x, x1, x2, x3), 1)))
+            x5 = self.conv5(torch.cat((x, x1, x2, x3, x4), 1))
+            return x5 * 0.2 + x
+
+    class RRDB(nn.Module):
+        def __init__(self, nf: int, gc: int):
+            super().__init__()
+            self.rdb1 = ResidualDenseBlock(nf, gc)
+            self.rdb2 = ResidualDenseBlock(nf, gc)
+            self.rdb3 = ResidualDenseBlock(nf, gc)
+
+        def forward(self, x):
+            out = self.rdb3(self.rdb2(self.rdb1(x)))
+            return out * 0.2 + x
+
+    class RRDBNet(nn.Module):
+        def __init__(self):
+            super().__init__()
+            self.conv_first = nn.Conv2d(3, num_feat, 3, 1, 1)
+            self.body = nn.Sequential(*[RRDB(num_feat, num_grow_ch) for _ in range(num_block)])
+            self.conv_body = nn.Conv2d(num_feat, num_feat, 3, 1, 1)
+            self.conv_up1 = nn.Conv2d(num_feat, num_feat, 3, 1, 1)
+            self.conv_up2 = nn.Conv2d(num_feat, num_feat, 3, 1, 1)
+            self.conv_hr = nn.Conv2d(num_feat, num_feat, 3, 1, 1)
+            self.conv_last = nn.Conv2d(num_feat, 3, 3, 1, 1)
+            self.lrelu = nn.LeakyReLU(0.2, inplace=True)
+
+        def forward(self, x):
+            feat = self.conv_first(x)
+            feat = feat + self.conv_body(self.body(feat))
+            feat = self.lrelu(self.conv_up1(F.interpolate(feat, scale_factor=2, mode="nearest")))
+            feat = self.lrelu(self.conv_up2(F.interpolate(feat, scale_factor=2, mode="nearest")))
+            return self.conv_last(self.lrelu(self.conv_hr(feat)))
+
+    assert scale == 4, f"model này chỉ hỗ trợ scale 4, config báo {scale}"
+    return RRDBNet()
+
+
+def _get_model():
+    global _model, _device
+    if _model is None:
+        import json
+
+        import torch
+        from huggingface_hub import hf_hub_download
+        from safetensors.torch import load_file
+
+        Path(os.environ["HF_HOME"]).mkdir(parents=True, exist_ok=True)
+        cfg_path = hf_hub_download(_MODEL_NAME, "config.json")
+        cfg = json.loads(Path(cfg_path).read_text(encoding="utf-8"))
+        w_path = hf_hub_download(_MODEL_NAME, _WEIGHTS_FILE)
+
+        net = _build_net(
+            num_feat=int(cfg.get("num_feat", 64)),
+            num_block=int(cfg.get("num_block", 6)),
+            num_grow_ch=int(cfg.get("num_grow_ch", 32)),
+            scale=int(cfg.get("scale", 4)),
+        )
+        # strict=True là CÓ CHỦ ĐÍCH: thiếu/thừa key nghĩa là kiến trúc dựng sai so với
+        # trọng số, và một RRDBNet lệch tham số vẫn CHẠY ra ảnh — chỉ là ảnh rác. Thà nổ.
+        net.load_state_dict(load_file(w_path), strict=True)
+        dev = _pick_device()
+        net.eval().to(dev)
+        if _FP16 and dev.type == "cuda":
+            net.half()
+        for p in net.parameters():
+            p.requires_grad_(False)
+        _model, _device = net, dev
+    return _model, _device
+
+
+def _infer(net, t, tile: int, pad: int):
+    """Chạy model, chia ô nếu ảnh lớn. t: tensor 1x3xHxW đã chuẩn hoá 0..1."""
+    import torch
+
+    _, _, h, w = t.shape
+    if tile <= 0 or (h <= tile and w <= tile):
+        return net(t)
+
+    out = torch.zeros(1, 3, h * SCALE, w * SCALE, dtype=t.dtype, device=t.device)
+    for y0 in range(0, h, tile):
+        for x0 in range(0, w, tile):
+            y1, x1 = min(y0 + tile, h), min(x0 + tile, w)
+            # Vùng lấy vào có LỀ chồng lấn: conv 3x3 xếp chồng nhiều lớp nên pixel sát
+            # mép ô thiếu ngữ cảnh -> không có lề sẽ thấy rõ đường ghép giữa các ô.
+            py0, px0 = max(y0 - pad, 0), max(x0 - pad, 0)
+            py1, px1 = min(y1 + pad, h), min(x1 + pad, w)
+            o = net(t[:, :, py0:py1, px0:px1])
+            # Cắt bỏ lề, chỉ giữ đúng phần lõi của ô.
+            oy0, ox0 = (y0 - py0) * SCALE, (x0 - px0) * SCALE
+            out[:, :, y0 * SCALE:y1 * SCALE, x0 * SCALE:x1 * SCALE] = o[
+                :, :, oy0:oy0 + (y1 - y0) * SCALE, ox0:ox0 + (x1 - x0) * SCALE
+            ]
+    return out
+
+
+def upscale_rgb(arr: np.ndarray) -> np.ndarray:
+    """Phóng 4x một mảng HxWx3 uint8 bằng Real-ESRGAN. Trả (4H)x(4W)x3 uint8.
+
+    Ném lỗi nếu thiếu torch — gọi `available()` trước để rớt về LANCZOS.
+    Tự hạ cạnh ô rồi rớt về CPU khi hết VRAM, thay vì để pipeline chết giữa chừng.
+    """
+    import torch
+
+    if arr.ndim != 3 or arr.shape[2] != 3:
+        raise ValueError(f"cần mảng HxWx3, nhận {arr.shape}")
+    net, dev = _get_model()
+    dtype = torch.float16 if (_FP16 and dev.type == "cuda") else torch.float32
+
+    t = torch.from_numpy(np.ascontiguousarray(arr)).permute(2, 0, 1).unsqueeze(0)
+    t = t.to(device=dev, dtype=dtype).div_(255.0)
+
+    tile = _TILE
+    while True:
+        try:
+            with torch.inference_mode():
+                out = _infer(net, t, tile, _TILE_PAD)
+                # Chuẩn hoá NGAY TRONG inference_mode: tensor sinh ra ở đây là "inference
+                # tensor", sửa tại chỗ ở ngoài khối sẽ bị torch chặn.
+                out = (out.clamp(0.0, 1.0) * 255.0).round()
+                out = out[0].permute(1, 2, 0).to("cpu", torch.uint8).numpy().copy()
+            break
+        except torch.cuda.OutOfMemoryError:
+            torch.cuda.empty_cache()
+            if tile <= 0 or tile > 128:
+                # Hạ dần cạnh ô. Dãy này LUÔN kết thúc: mọi giá trị > 128 rơi về đúng 128
+                # sau tối đa 2 vòng, và 128 không còn thoả điều kiện nên rơi xuống nhánh CPU.
+                tile = 128 if tile <= 0 or tile > 256 else tile // 2
+                continue
+            # Ô đã nhỏ hết cỡ mà vẫn hết VRAM -> chuyển hẳn sang CPU (chậm nhưng xong việc).
+            net = net.float().to("cpu")
+            _model_to_cpu(net)           # nhớ lại, để lần gọi sau không lặp vòng OOM
+            t = t.float().to("cpu")
+            tile = _TILE
+
+    return out
+
+
+def _model_to_cpu(net) -> None:
+    """Ghi lại việc model đã bị đẩy sang CPU, để lần gọi sau không lặp lại vòng OOM."""
+    global _model, _device
+    import torch
+
+    _model, _device = net, torch.device("cpu")
+
+
+def warmup() -> bool:
+    """Tải trọng số + nạp model sẵn. True nếu sẵn sàng. Không ném lỗi."""
+    if not available():
+        return False
+    try:
+        _get_model()
+        return True
+    except Exception:
+        return False
+
+
+def backend():
+    """Trả callable `upscale_rgb` nếu dùng được, không thì None (caller rớt về LANCZOS)."""
+    return upscale_rgb if available() else None
+
+
+def info() -> dict:
+    """Mô tả backend để đưa vào report — không nạp model."""
+    d: dict = {"model": _MODEL_NAME, "scale": SCALE, "available": available(),
+               "tile": _TILE, "tile_pad": _TILE_PAD}
+    if _device is not None:
+        d["device"] = str(_device)
+        d["fp16"] = bool(_FP16 and _device.type == "cuda")
+    elif available():
+        try:
+            d["device"] = str(_pick_device())
+        except Exception:
+            pass
+    return d