Add Ideogram support and improve BF16 dequantization handling

.github/skills/add-model-architecture/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: add-model-architecture
+description: Add safe, tested support for a new ComfyUI model architecture and its GGUF conversion path.
+---
+
+# Add a Model Architecture
+
+Use this skill when adding or investigating a new diffusion, text, or vision
+model architecture for ComfyUI-GGUF.
+
+## Goal
+
+Deliver end-to-end support: a source checkpoint is recognized, converted with
+correct precision choices, accepted by this node's loader, and recognized by
+the target ComfyUI installation. Do not label a converter-only match as
+supported.
+
+## Discovery
+
+1. Identify the model role: diffusion model, text encoder, vision encoder, or
+   multimodal projector.
+2. Obtain an authoritative checkpoint key listing with shapes and dtypes. Use
+   a safetensors header when possible; do not download model weights merely to
+   infer names.
+3. Verify the current ComfyUI source can detect the model and instantiate its
+   runtime class. Record the minimum compatible ComfyUI revision if it is new.
+4. Compare the key layout against every existing `Model*` class in
+   `tools/convert.py`. Reuse an existing architecture only when its detection,
+   precision rules, and runtime behavior all apply.
+
+## Conversion Support
+
+1. Add a focused `Model<Architecture>` subclass in `tools/convert.py`.
+2. Set `arch` to the ComfyUI/GGUF architecture identifier expected at load
+   time.
+3. Define `keys_detect` with multiple stable, distinctive keys. Use alternate
+   key sets only for known checkpoint export variants.
+4. Add `keys_banned` when a similarly named incompatible checkpoint format
+   exists, such as a Diffusers export with incompatible fused projections.
+5. Classify tensors before quantization:
+   - `keys_hiprec`: must remain FP32 due to numerical sensitivity, buffers, or
+     ComfyUI runtime requirements.
+   - `keys_noquant`: retain source FP16/BF16 because native low-bit execution
+     is unsafe or slower.
+   - `keys_ignore`: omit conversion-only state that is not model weight data.
+6. Add the class to `arch_list`. Confirm `handle_tensors` preserves original
+   shapes and that all quantized dimensions satisfy the selected GGML block
+   size.
+
+## Loading Support
+
+1. Add the architecture to `IMG_ARCH_LIST`, `TXT_ARCH_LIST`, or
+   `VIS_TYPE_LIST` in `loader.py`, as appropriate.
+2. Add a key mapper, tokenizer loader, or detection marker only when a real
+   naming or ComfyUI-detection mismatch requires it. Keep such transformations
+   deterministic and covered by a test.
+3. Check standard and Dynamic VRAM loading. Dynamic loading preserves GGML
+   storage through `quant_ops.py`; static loading uses `ops.py`.
+4. Do not enable `_K` diffusion quantization as a performance optimization:
+   this repository currently expands standard GGML quants before PyTorch
+   compute. Prefer `Q8_CR` for supported native INT8 Linear inference.
+
+## Tests and Documentation
+
+1. Add a synthetic test to `tests/test_targeted_quantization.py` that verifies
+   architecture detection from the distinctive keys.
+2. Convert a minimal state dict and assert `general.architecture`, selected
+   GGML tensor types, and required FP32/FP16 exceptions.
+3. Run `python -m unittest tests.test_targeted_quantization`.
+4. Validate one real checkpoint in ComfyUI with a fixed workflow and inspect
+   loader logs for tensor types and unexpected-key failures.
+5. Update `README.md` with supported model variants, minimum ComfyUI version,
+   conversion command, and quantization limitations.
+
+## Completion Checklist
+
+- [ ] ComfyUI support is present and its minimum version is documented.
+- [ ] Detection uses distinctive keys and rejects incompatible formats.
+- [ ] Sensitive tensors have explicit precision treatment.
+- [ ] Static and Dynamic VRAM loaders accept the generated GGUF.
+- [ ] Synthetic conversion tests pass.
+- [ ] A real model loads and produces output in ComfyUI.
+- [ ] User-facing documentation makes no unmeasured performance claim.

.github/workflows/publish.yml

@@ -0,0 +1,19 @@
+name: Publish to Comfy Registry
+
+on:
+  workflow_dispatch:
+  release:
+    types: [published]
+
+jobs:
+  publish-node:
+    name: Publish Custom Node
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v4
+
+      - name: Publish Custom Node
+        uses: Comfy-Org/publish-node-action@main
+        with:
+          personal_access_token: ${{ secrets.REGISTRY_ACCESS_TOKEN }}

.gitignore

@@ -165,3 +165,8 @@ cython_debug/
 #  and can be added to the global gitignore or merged into this file.  For a more nuclear
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
 #.idea/
+.idea/comfyui-gguf-reboot.iml
+.idea/inspectionProfiles/profiles_settings.xml
+.idea/modules.xml
+.idea/pyProjectModel.xml
+.idea/vcs.xml

AGENTS.md

@@ -0,0 +1,56 @@
+# Repository Guide for Agents
+
+## Purpose
+
+ComfyUI-GGUF loads GGUF-encoded diffusion, text, and vision models into
+ComfyUI. It also converts supported checkpoint layouts to GGUF. Preserve
+ComfyUI compatibility and model output quality over file-size reductions.
+
+## Repository Map
+
+| Area | Responsibility |
+| --- | --- |
+| `loader.py` | Reads GGUF metadata and tensors, maps text/vision checkpoints, and selects loader behavior. |
+| `ops.py` | Defines runtime tensor wrappers and on-the-fly dequantization or native INT8 execution. |
+| `dequant.py` | PyTorch implementations of GGML block dequantizers. |
+| `quant_ops.py` | Dynamic-VRAM `GGMLLayout` integration. |
+| `tools/convert.py` | Detects checkpoint architectures and writes GGUF files. |
+| `nodes.py` | ComfyUI node definitions and loading/conversion entry points. |
+| `tests/test_targeted_quantization.py` | Unit and integration coverage for conversion and loader detection. |
+
+## Working Rules
+
+- Treat `general.architecture`, tensor names, tensor shapes, dtypes, and GGML
+  quantization types as compatibility contracts. Reject unsupported inputs with
+  clear errors rather than guessing.
+- Add a model architecture in `tools/convert.py` only after confirming its
+  checkpoint key layout and that the installed ComfyUI can detect and run it.
+  A converter-only match is not usable model support.
+- Protect non-Linear, numerically sensitive, and architecture-specific tensors
+  with `keys_hiprec` or `keys_noquant`. Do not quantize Conv2d weights merely
+  because they are two-dimensional after reshaping.
+- Standard GGML quants are dequantized before PyTorch compute in this project.
+  Do not describe them as native low-bit inference. `Q8_CR` is the supported
+  native INT8 Linear path.
+- Keep static and Dynamic VRAM behavior aligned. A new quantization type must
+  be supported by both `dequant.py` and `quant_ops.py`, or be rejected.
+- Keep changes focused. Do not alter user-owned working-tree changes, generated
+  files, or model assets.
+
+## Validation
+
+Run the focused suite from the repository root when dependencies are available:
+
+```powershell
+python -m unittest tests.test_targeted_quantization
+```
+
+For a new architecture, add a minimal synthetic checkpoint test that verifies
+detection, intended protected-tensor precision, and GGUF metadata. Validate a
+real checkpoint in ComfyUI before advertising support.
+
+## Documentation
+
+Update `README.md` when user-visible model support, conversion options, or
+quantization behavior changes. Keep performance statements qualified by the
+actual runtime path and hardware; do not publish unmeasured speed claims.