T

WildAi 4c44a8e275 plan(P2): address review findings

Five review findings of the P2 phase, each fixed at its root:

1. (medium) The P2.6 guard could not see an undeclared third-party import:
   the closure's imports were filtered through a hard-coded 10-name map, so
   every module outside it was dropped silently (a module-level `import av`
   in a copy of the repo still gave "1 passed"). The map is now a *rename*
   map (cv2 -> opencv-python, PIL -> Pillow, yaml -> pyyaml); every other
   module is mapped to its own name, so an unknown module shows up as an
   undeclared dependency. The guard is split by import time: every
   third-party module imported at import time must be a declared
   distribution, every lazy (function-level) one must be allowlisted with a
   reason (dlib, gdown, mc, wandb - all unreachable from the node).
2. (low) The P2.1 (c) progression test was vacuous: it returned before its
   assertions and probed a second, top-level copy of the vendored tree
   (`sys.path.insert(modules/deps)`). It now imports the packaged
   architecture, asserts that FeedForward / AdaLayerNorm come from the
   vendored _diffusers_compat and that no top-level `basicsr` shadows an
   installed one.
3. (low) Two swallow-and-stub fallbacks remained in the vendored tree
   (facelib/detection, facelib/parsing - their stubs called an unimported
   `urlparse` and would have raised NameError). Both now import the vendored
   symbol directly; a guard forbids a fallback stub in the vendored tree.
4. (low) `basicsr/utils/file_client.py` still appended to `sys.path` (the
   optional `sys_path` of MemcachedBackend), which the plan's §3 rule
   forbids anywhere in the package. The mutation and the parameter are gone
   and guard (d) now covers the whole package (the vendored tree included).
5. (low) The unreachable body of `KEEPFaceProcessor.process_video` still
   called the deleted VideoReader / VideoWriter. The 141 dead lines are
   removed; an AST guard keeps the references out.

Found while fixing the findings: the CI job did not install `requests`,
which the vendored `basicsr/utils/download_util.py` imports at module level
(P2.6 added it to requirements.txt but not to the workflow) - a clean CI
runner died with "No module named 'requests'". The install list is now
completed and a test derives it from requirements.txt.

Gate: pytest -m "unit or mock_integration" -> 109 passed, 1 skipped,
4 xfailed; plan's local gate (+ headless) -> 109 passed, 3 skipped,
4 xfailed; tools/scan_compat.py -> finding_count 0 (exit 0); ruff check . ->
All checks passed. A mutation check re-introduces six defects into a copy of
the repository: the matching guard fails in 6/6 cases.

2026-10-23 18:29:04 +03:00

.github/workflows

plan(P2): address review findings

2026-10-23 18:29:04 +03:00

assets

update README.md

2025-07-03 12:55:38 +03:00

example_workflows

plan(P0.5): canonicalize the examples directory (example_workflows/)

2026-10-23 14:00:48 +03:00

modules

plan(P2): address review findings

2026-10-23 18:29:04 +03:00

tests

plan(P2): address review findings

2026-10-23 18:29:04 +03:00

tools

plan(P2.5): package-ize the vendored deps and drop the sys.path mutation

2026-10-23 17:33:50 +03:00

__init__.py

update v1.1. Fixes, Upscale Model, final_upscale_factor

2025-07-03 13:30:04 +03:00

.gitignore

chore: keep docs/audit artifacts trackable

2026-10-23 13:02:22 +03:00

conftest.py

plan(P1): address review findings

2026-10-23 16:34:37 +03:00

LICENSE

init

2025-05-21 23:40:55 +03:00

nodes.py

update v1.1. Fixes, Upscale Model, final_upscale_factor

2025-07-03 13:30:04 +03:00

pyproject.toml

plan(P1.5): add the CI workflow with real install steps

2026-10-23 15:55:10 +03:00

README.md

update README.md

2025-07-03 12:55:38 +03:00

requirements.txt

plan(P2.6): trim requirements.txt to the true runtime set

2026-10-23 17:37:30 +03:00

README.md

ComfyUI-KEEP

Kalman-Inspired Feature Propagation for Video Face Super-Resolution in ComfyUI

Update

2025-07-03:
- Standard ComfyUI Upscale Model inputs instead of a hardcoded Real-ESRGAN
- Added final_upscale_factor for precise output scaling.
2025-05-20: Initial commit

About ComfyUI-KEEP

This repository provides custom nodes for ComfyUI that implement the KEEP algorithm for face super-resolution. KEEP is designed for robust video face super-resolution, and these nodes adapt its capabilities for use within the ComfyUI framework.

You can enhance faces in:

Single images
Sequences of images (video frames)

The nodes leverage the core architecture and pre-trained models from the original KEEP project.

Features

High-Quality Face Restoration: Utilizes the core KEEP model for detailed face enhancement.
Flexible Upscaling Integration:
- Connect any ComfyUI-compatible upscale model (from Upscale Model Loader) for both background and face upscaling.
- Use different models for background and face enhancement within the same workflow.
- Full control over the final output size with a final_upscale_factor.
Single Image & Sequence Processing: Enhance faces in individual images or entire video frame sequences.
Choice of Detection Models: Supports various face detection backbones (RetinaFace, YOLOv5).

Nodes

This package includes the following custom nodes:

1. Load KEEP Models

Loads the core KEEP model and face detection models. It now accepts UPSCALE_MODEL inputs, allowing you to connect any upscaler loaded via a standard Upscale Model Loader.

model: Choose between "KEEP" (general) or "Asian".
detection_model: Face detection model to use (e.g., retinaface_resnet50).
bg_upscale_model (optional): Connect an UPSCALE_MODEL here to enhance the background.
face_upscale_model (optional): Connect an UPSCALE_MODEL here to further enhance the quality of the restored face patch.

2. KEEP Single Image

Restores and enhances faces in a single input image.

image: The input image.
keep_model: The model pack from the Load KEEP Models node.
final_upscale_factor: The final scaling factor for the output image. For example, if your BG upscale model is 4x but you only want a 2x final output, set this to 2.0. If you want the original size, set this to 1.0.
has_aligned_face: Set to True if the input is an already aligned 512x512 face.
only_center_face: If multiple faces are detected, process only the one closest to the center.
draw_bounding_box: Draws a box around the detected face.

3. KEEP Image Sequence

Restores and enhances faces in a sequence of input images (e.g., frames from a video).

images: A batch of images representing video frames.
keep_model: The model pack from the Load KEEP Models node.
final_upscale_factor: The final scaling factor for the output frames.
max_clip_length: Maximum number of frames to process in one go by the KEEP network (for VRAM management).

Installation

Clone this repository:
```
git clone https://github.com/wildminder/ComfyUI-KEEP.git
```
Place it into your ComfyUI/custom_nodes/ directory.

Install Dependencies: The core KEEP model has several dependencies

cd ComfyUI/custom_nodes/ComfyUI-KEEP
pip install -r requirements.txt

Download Pre-trained Models: The nodes will attempt to download the required models automatically during the first run. Models will be saved into standard ComfyUI model directories:
- KEEP models (KEEP-b76feb75.pth): ComfyUI/models/keep_models/KEEP/
- Face detection/parsing models (e.g., detection_Resnet50_Final.pth): ComfyUI/models/facedetection/
- Upscale Models: Place any upscaler models (like Real-ESRGAN, SwinIR, etc.) in ComfyUI/models/upscale_models/.
If automatic download fails for the KEEP or face models, you can manually download them from the original KEEP Releases V1.0.0 and place them in the corresponding ComfyUI subdirectories mentioned above.
Restart ComfyUI.

Citation for Original KEEP

If you use the core KEEP algorithm or models in your research, please cite the original paper:

@InProceedings{feng2024keep,
      title     = {Kalman-Inspired FEaturE Propagation for Video Face Super-Resolution},
      author    = {Feng, Ruicheng and Li, Chongyi and Loy, Chen Change},
      booktitle = {European Conference on Computer Vision (ECCV)},
      year      = {2024}
}