convert: add test_convert.py

* ci : allow make-release to target a specific commit

The make-release workflow now accepts an optional 'commit' input. When
set, that commit is checked out and the release checks verify that it
belongs to the branch selected in the "Run workflow" dialog and is not
older than 3 days from the branch tip. The check is part of
make-release-checks.sh (driven by the RELEASE_BRANCH env), so it follows
the same dry-run semantics as the other checks.

Assisted-by: pi:llama.cpp/Qwen3.8-27B

* cont : scan latest 100 relase workflow runs

* cont : do not check manually for release.yml success

.github/workflows/docker.yml

@@ -44,6 +44,7 @@ jobs:
         uses: actions/checkout@v6
         with:
           fetch-depth: 0
+          ssh-key: ${{ secrets.DEPLOY_KEY_RELEASE }}
 
       - name: Determine source tag name
         id: srctag

.github/workflows/make-release.yml

@@ -3,6 +3,11 @@ name: Make Release
 on:
   workflow_dispatch:
     inputs:
+      commit:
+        description: 'Commit SHA to release (empty = branch HEAD)'
+        required: false
+        default: ''
+        type: string
       dry_run:
         description: 'Dry run - validate without creating the tag'
         required: true
@@ -22,12 +27,17 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v6
+        with:
+          ssh-key: ${{ secrets.DEPLOY_KEY_RELEASE }}
+          ref: ${{ inputs.commit != '' && inputs.commit || github.ref_name }}
+          fetch-depth: 0
 
       - name: Run release checks
         id: checks
         run: bash scripts/make-release-checks.sh ${{ github.event.inputs.dry_run == 'true' && '--dry-run' || '' }}
         env:
           GITHUB_REPOSITORY: ${{ github.repository }}
+          RELEASE_BRANCH: ${{ github.ref_name }}
 
       - name: Create release tag
         if: ${{ github.event.inputs.dry_run == 'false' }}

.github/workflows/release.yml

@@ -1598,6 +1598,7 @@ jobs:
         uses: actions/checkout@v6
         with:
           fetch-depth: 0
+          ssh-key: ${{ secrets.DEPLOY_KEY_RELEASE }}
 
       - name: Determine tag name
         id: tag

common/chat-diff-analyzer.cpp

@@ -193,6 +193,14 @@ static std::vector<std::function<void(const common_chat_template & tmpl, autopar
               LOG_DBG(ANSI_ORANGE "[Patch: Laguna]\n" ANSI_RESET);
           }
       },
+      // Bailing V3
+      [](const common_chat_template & tmpl, autoparser & analysis) -> void {
+          if (tmpl.src.find("Bailing V3 chat template") != std::string::npos) {
+              analysis.tools.arguments.value_suffix = trim_whitespace(analysis.tools.arguments.value_suffix);
+              analysis.tools.arguments.tolerate_intertag_whitespace = true;
+              LOG_DBG(ANSI_ORANGE "[Patch: Bailing V3]\n" ANSI_RESET);
+          }
+      },
 
     });
 

conversion/__init__.py

@@ -27,6 +27,7 @@ TEXT_MODEL_MAP: dict[str, str] = {
     "BaichuanForCausalLM": "baichuan",
     "BailingMoeForCausalLM": "bailingmoe",
     "BailingMoeV2ForCausalLM": "bailingmoe",
+    "BailingMoeV3ForCausalLM": "bailingmoe3",
     "BambaForCausalLM": "granite",
     "BertForMaskedLM": "bert",
     "BertForSequenceClassification": "bert",

conversion/afmoe.py

@@ -13,6 +13,7 @@ from .llama import LlamaModel
 
 
 @ModelBase.register("AfmoeForCausalLM")
+@ModelBase.example("arcee-ai/Trinity-Large-Thinking")
 class AfmoeModel(LlamaModel):
     model_arch = gguf.MODEL_ARCH.AFMOE
 

conversion/arctic.py

@@ -16,6 +16,7 @@ from .llama import LlamaModel
 
 
 @ModelBase.register("ArcticForCausalLM")
+@ModelBase.example("Snowflake/snowflake-arctic-instruct")
 class ArcticModel(TextModel):
     model_arch = gguf.MODEL_ARCH.ARCTIC
 

conversion/baichuan.py

@@ -9,6 +9,7 @@ from .base import ModelBase, TextModel, gguf, logger
 
 
 @ModelBase.register("BaichuanForCausalLM", "BaiChuanForCausalLM")
+@ModelBase.example("baichuan-inc/Baichuan2-7B-Chat", "baichuan-inc/Baichuan-7B")
 class BaichuanModel(TextModel):
     model_arch = gguf.MODEL_ARCH.BAICHUAN
 

conversion/bailingmoe.py

@@ -11,6 +11,7 @@ from .base import ModelBase, TextModel, gguf
 
 
 @ModelBase.register("BailingMoeForCausalLM")
+@ModelBase.example("inclusionAI/Ling-lite")
 class BailingMoeModel(TextModel):
     model_arch = gguf.MODEL_ARCH.BAILINGMOE
 
@@ -108,6 +109,7 @@ class BailingMoeModel(TextModel):
 
 
 @ModelBase.register("BailingMoeV2ForCausalLM")
+@ModelBase.example("inclusionAI/Ling-mini-2.0")
 class BailingMoeV2Model(TextModel):
     model_arch = gguf.MODEL_ARCH.BAILINGMOE2
 
@@ -189,6 +191,7 @@ class BailingMoeV2Model(TextModel):
 
 
 @ModelBase.register("SarvamMoEForCausalLM", "modeling_sarvam_moe.SarvamMoEForCausalLM")
+@ModelBase.example("sarvamai/sarvam-30b")
 class SarvamMoEModel(BailingMoeV2Model):
     model_arch = gguf.MODEL_ARCH.BAILINGMOE2
     # Sarvam-MoE shares the BailingMoeV2 architecture; only differences:

conversion/bailingmoe3.py

@@ -0,0 +1,193 @@
+from __future__ import annotations
+
+import re
+
+from typing import Callable, Iterable, TYPE_CHECKING
+
+import torch
+
+if TYPE_CHECKING:
+    from torch import Tensor
+
+from .base import ModelBase, TextModel, gguf
+
+
+@ModelBase.register("BailingMoeV3ForCausalLM")
+@ModelBase.example("inclusionAI/Ling-3.0-tiny", "inclusionAI/Ling-3.0-flash")
+class BailingMoeV3Model(TextModel):
+    model_arch = gguf.MODEL_ARCH.BAILINGMOE3
+    supports_mtp_export = True
+
+    _experts: list[dict[str, Tensor]] | None = None
+    _main_layers: int | None = None
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        nextn_layers = self.hparams.get("num_nextn_predict_layers", 0) or 0
+        if self.no_mtp:
+            nextn_layers = 0
+        self.block_count = self.hparams["num_hidden_layers"] + nextn_layers
+        self.tensor_map = gguf.get_tensor_name_map(self.model_arch, self.block_count)
+
+    def index_tensors(self, remote_hf_model_id: str | None = None):
+        type(self)._main_layers = self.hparams["num_hidden_layers"]
+        return super().index_tensors(remote_hf_model_id=remote_hf_model_id)
+
+    def set_vocab(self):
+        self._set_vocab_gpt2()
+
+    def is_full_attention(self, bid: int) -> bool:
+        n_layer = self.hparams["num_hidden_layers"]
+        layer_group_size = self.hparams["layer_group_size"]
+        return bid >= n_layer or (bid + 1) % layer_group_size == 0 or bid >= n_layer // layer_group_size * layer_group_size
+
+    def set_gguf_parameters(self):
+        if not self.hparams.get("no_kda_lora", False):
+            raise ValueError("BailingMoeV3 KDA LoRA projections are not supported")
+        if not self.hparams.get("kda_safe_gate", False):
+            raise ValueError("BailingMoeV3 non-safe KDA gates are not supported")
+        if self.hparams.get("gated_attention_proj_granularity_type") != "head_wise":
+            raise ValueError("BailingMoeV3 requires head-wise attention gates")
+
+        self.hparams["num_key_value_heads"] = 1
+        super().set_gguf_parameters()
+
+        n_head_kv = [1 if self.is_full_attention(il) else 0 for il in range(self.block_count)]
+        self.gguf_writer.add_head_count_kv(n_head_kv)
+
+        self.gguf_writer.add_vocab_size(self.hparams["vocab_size"])
+        self.gguf_writer.add_ssm_conv_kernel(self.hparams["short_conv_kernel_size"])
+        self.gguf_writer.add_kda_head_dim(self.hparams["head_dim"])
+        self.gguf_writer.add_kda_safe_gate(self.hparams["kda_safe_gate"])
+        self.gguf_writer.add_kda_gate_lower_bound(self.hparams["kda_lower_bound"])
+
+        kv_lora_rank = self.hparams["kv_lora_rank"]
+        qk_nope_head_dim = self.hparams["qk_nope_head_dim"]
+        qk_rope_head_dim = self.hparams["qk_rope_head_dim"]
+        if (q_lora_rank := self.hparams.get("q_lora_rank")) is not None:
+            self.gguf_writer.add_q_lora_rank(q_lora_rank)
+        self.gguf_writer.add_kv_lora_rank(kv_lora_rank)
+        self.gguf_writer.add_rope_dimension_count(qk_rope_head_dim)
+        self.gguf_writer.add_key_length(kv_lora_rank + qk_rope_head_dim)
+        self.gguf_writer.add_key_length_mla(qk_nope_head_dim + qk_rope_head_dim)
+        self.gguf_writer.add_value_length_mla(self.hparams["v_head_dim"])
+
+        self.gguf_writer.add_expert_feed_forward_length(self.hparams["moe_intermediate_size"])
+        self.gguf_writer.add_expert_shared_feed_forward_length(self.hparams["moe_shared_expert_intermediate_size"])
+        self.gguf_writer.add_expert_shared_count(self.hparams["num_shared_experts"])
+        self.gguf_writer.add_leading_dense_block_count(self.hparams["first_k_dense_replace"])
+        self.gguf_writer.add_expert_weights_scale(self.hparams["routed_scaling_factor"])
+        self.gguf_writer.add_expert_weights_norm(self.hparams["norm_topk_prob"])
+
+        def clamp_limits(key: str) -> list[float] | None:
+            values = self.hparams.get(key)
+            if values is None:
+                return None
+            values = [0.0 if value is None else float(value) for value in values[:self.block_count]]
+            return values + [0.0] * (self.block_count - len(values))
+
+        if (values := clamp_limits("expert_swiglu_limit_list")) is not None:
+            self.gguf_writer.add_swiglu_clamp_exp(values)
+        if (values := clamp_limits("share_expert_swiglu_limit_list")) is not None:
+            self.gguf_writer.add_swiglu_clamp_shexp(values)
+
+        if not self.no_mtp and (nextn_layers := self.hparams.get("num_nextn_predict_layers", 0)):
+            self.gguf_writer.add_nextn_predict_layers(nextn_layers)
+
+    def prepare_metadata(self, vocab_only: bool):
+        from_dir = self.fname_out.is_dir()
+        super().prepare_metadata(vocab_only=vocab_only)
+
+        if not self.mtp_only or not from_dir:
+            return
+
+        output_type: str = self.ftype.name.partition("_")[2]
+        fname_default: str = gguf.naming_convention(
+            self.metadata.name, self.metadata.basename, self.metadata.finetune,
+            self.metadata.version, size_label=None, output_type=output_type, model_type=None)
+        self.fname_out = self.fname_out.parent / f"mtp-{fname_default}.gguf"
+
+    @classmethod
+    def filter_tensors(cls, item: tuple[str, Callable[[], Tensor]]) -> tuple[str, Callable[[], Tensor]] | None:
+        name, gen = item
+        if name.endswith(".expert_bias"):
+            name += ".bias"
+
+        if cls._main_layers is None:
+            return super().filter_tensors((name, gen))
+
+        m = re.match(r"model\.layers\.(\d+)\.", name)
+        is_mtp = m is not None and int(m.group(1)) >= cls._main_layers
+
+        if is_mtp and cls.no_mtp:
+            return None
+        if cls.mtp_only and not is_mtp and name not in (
+            "model.word_embeddings.weight", "model.norm.weight", "lm_head.weight",
+        ):
+            return None
+
+        return super().filter_tensors((name, gen))
+
+    def modify_tensors(self, data_torch: Tensor, name: str, bid: int | None) -> Iterable[tuple[str, Tensor]]:
+        if name.endswith((".q_conv1d.weight", ".k_conv1d.weight", ".v_conv1d.weight")) and data_torch.ndim in (2, 3):
+            d_inner = data_torch.shape[0]
+            d_conv = data_torch.shape[-1]
+            data_torch = data_torch.reshape(1, d_inner, 1, d_conv)
+
+        if name.endswith(".A_log"):
+            data_torch = torch.exp(data_torch).reshape(-1, 1)
+
+        if name.endswith(".dt_bias"):
+            name = name.rpartition(".dt_bias")[0] + ".dt_proj.bias"
+
+        if name.endswith(".attention.f_proj.weight"):
+            assert bid is not None
+            if self.is_full_attention(bid):
+                raise ValueError(f"unexpected f_proj on full-attention layer {bid}")
+            name = self.format_tensor_name(gguf.MODEL_TENSOR.SSM_F_A, bid)
+
+        if name.endswith(".attention.g_proj.weight"):
+            assert bid is not None
+            tensor = gguf.MODEL_TENSOR.ATTN_GATE if self.is_full_attention(bid) else gguf.MODEL_TENSOR.SSM_G_A
+            name = self.format_tensor_name(tensor, bid)
+
+        if ".mlp.experts." in name:
+            n_experts = self.hparams["num_experts"]
+            assert bid is not None
+
+            if self._experts is None:
+                self._experts = [{} for _ in range(self.block_count)]
+
+            self._experts[bid][name] = data_torch
+            if len(self._experts[bid]) >= n_experts * 3:
+                for weight_name in ("down_proj", "gate_proj", "up_proj"):
+                    tensors = []
+                    for expert_id in range(n_experts):
+                        expert_name = f"model.layers.{bid}.mlp.experts.{expert_id}.{weight_name}.weight"
+                        tensors.append(self._experts[bid].pop(expert_name))
+                    merged_name = f"model.layers.{bid}.mlp.experts.{weight_name}.weight"
+                    yield from super().modify_tensors(torch.stack(tensors, dim=0), merged_name, bid)
+            return
+
+        if name.endswith(".attention.kv_b_proj.weight"):
+            assert bid is not None
+            n_head = self.hparams["num_attention_heads"]
+            v_head_dim = self.hparams["v_head_dim"]
+            qk_nope_head_dim = self.hparams["qk_nope_head_dim"]
+            assert data_torch.shape[0] == n_head * (v_head_dim + qk_nope_head_dim)
+            kv_b = data_torch.view(n_head, v_head_dim + qk_nope_head_dim, data_torch.shape[-1])
+            k_b, v_b = torch.split(kv_b, [qk_nope_head_dim, v_head_dim], dim=1)
+            name_k = self.format_tensor_name(gguf.MODEL_TENSOR.ATTN_K_B, bid)
+            name_v = self.format_tensor_name(gguf.MODEL_TENSOR.ATTN_V_B, bid)
+            yield from super().modify_tensors(k_b.transpose(1, 2), name_k, bid)
+            yield from super().modify_tensors(v_b, name_v, bid)
+            return
+
+        yield from super().modify_tensors(data_torch, name, bid)
+
+    def prepare_tensors(self):
+        super().prepare_tensors()
+        if self._experts is not None:
+            experts = [name for layer in self._experts for name in layer]
+            if experts:
+                raise ValueError(f"Unprocessed experts: {experts}")

conversion/base.py

@@ -84,6 +84,9 @@ class ModelBase:
     }
     _hparams_loaders: list[tuple[HparamsMatcher, HparamsLoader]] = []
 
+    # HF repos usable to test conversion of this model, set by @ModelBase.example()
+    model_hf_examples: tuple[str, ...] = ()
+
     dir_model: Path
     ftype: gguf.LlamaFileType
     fname_out: Path
@@ -1149,6 +1152,15 @@ class ModelBase:
             return modelcls
         return func
 
+    @classmethod
+    def example(cls, *hf_repos: str) -> Callable[[AnyModel], AnyModel]:
+        assert hf_repos
+
+        def func(modelcls: AnyModel) -> AnyModel:
+            modelcls.model_hf_examples = hf_repos
+            return modelcls
+        return func
+
     @classmethod
     def print_registered_models(cls):
         for model_type, model_classes in cls._model_classes.items():

conversion/bert.py

@@ -15,6 +15,7 @@ from .base import ModelBase, SentencePieceTokenTypes, TextModel, gguf, logger
 
 
 @ModelBase.register("BertModel", "BertForMaskedLM", "CamembertModel", "BertForSequenceClassification")
+@ModelBase.example("BAAI/bge-small-en-v1.5", "dangvantuan/sentence-camembert-base")
 class BertModel(TextModel):
     model_arch = gguf.MODEL_ARCH.BERT
 
@@ -240,6 +241,7 @@ class BertModel(TextModel):
 
 
 @ModelBase.register("DistilBertModel", "DistilBertForMaskedLM", "DistilBertForSequenceClassification")
+@ModelBase.example("distilbert/distilbert-base-uncased")
 class DistilBertModel(BertModel):
     model_arch = gguf.MODEL_ARCH.BERT
 
@@ -263,6 +265,7 @@ class DistilBertModel(BertModel):
 
 
 @ModelBase.register("RobertaModel", "RobertaForSequenceClassification")
+@ModelBase.example("sentence-transformers/stsb-roberta-base")
 class RobertaModel(BertModel):
     model_arch = gguf.MODEL_ARCH.BERT
 
@@ -312,6 +315,7 @@ class RobertaModel(BertModel):
 
 
 @ModelBase.register("NomicBertModel")
+@ModelBase.example("nomic-ai/nomic-embed-text-v1.5")
 class NomicBertModel(BertModel):
     model_arch = gguf.MODEL_ARCH.BERT
 
@@ -400,6 +404,7 @@ class NomicBertModel(BertModel):
 
 
 @ModelBase.register("NeoBERT", "NeoBERTLMHead", "NeoBERTForSequenceClassification")
+@ModelBase.example("chandar-lab/NeoBERT")
 class NeoBert(BertModel):
     model_arch = gguf.MODEL_ARCH.NEO_BERT
 
@@ -431,6 +436,7 @@ class NeoBert(BertModel):
 
 
 @ModelBase.register("EuroBertModel", "JinaEmbeddingsV5Model")
+@ModelBase.example("hf-tiny-v2/tiny-random-EuroBertModel", "jinaai/jina-embeddings-v5-text-nano")
 class EuroBertModel(TextModel):
     model_arch = gguf.MODEL_ARCH.EUROBERT
 
@@ -459,6 +465,7 @@ class EuroBertModel(TextModel):
 
 
 @ModelBase.register("XLMRobertaModel", "XLMRobertaForSequenceClassification")
+@ModelBase.example("BAAI/bge-m3")
 class XLMRobertaModel(BertModel):
     model_arch = gguf.MODEL_ARCH.BERT
     _lora_files = {}
@@ -561,6 +568,7 @@ class XLMRobertaModel(BertModel):
 
 
 @ModelBase.register("JinaBertModel", "JinaBertForMaskedLM")
+@ModelBase.example("jinaai/jina-embeddings-v2-base-en")
 class JinaBertV2Model(BertModel):
     model_arch = gguf.MODEL_ARCH.JINA_BERT_V2
 
@@ -588,6 +596,7 @@ class JinaBertV2Model(BertModel):
 
 
 @ModelBase.register("ModernBertModel", "ModernBertForMaskedLM", "ModernBertForSequenceClassification")
+@ModelBase.example("answerdotai/ModernBERT-base")
 class ModernBertModel(BertModel):
     model_arch = gguf.MODEL_ARCH.MODERN_BERT
 

conversion/bitnet.py

@@ -9,6 +9,7 @@ from .base import ModelBase, TextModel, gguf
 
 
 @ModelBase.register("BitnetForCausalLM", "BitNetForCausalLM")
+@ModelBase.example("microsoft/bitnet-b1.58-2B-4T")
 class BitnetModel(TextModel):
     model_arch = gguf.MODEL_ARCH.BITNET
 

conversion/bloom.py

@@ -13,6 +13,7 @@ from .base import ModelBase, TextModel, gguf, logger
 
 
 @ModelBase.register("BloomForCausalLM", "BloomModel")
+@ModelBase.example("bigscience/bloom-560m")
 class BloomModel(TextModel):
     model_arch = gguf.MODEL_ARCH.BLOOM
 

conversion/chameleon.py

@@ -12,6 +12,8 @@ from .llama import LlamaModel
 
 @ModelBase.register("ChameleonForConditionalGeneration")
 @ModelBase.register("ChameleonForCausalLM")  # obsolete
+# [TAG_HF_EXAMPLE_GATED] facebook/chameleon-7b is gated
+# [TAG_HF_EXAMPLE_MISSING]
 class ChameleonModel(TextModel):
     model_arch = gguf.MODEL_ARCH.CHAMELEON
 

conversion/chatglm.py

@@ -9,6 +9,7 @@ from .base import ModelBase, SentencePieceTokenTypes, TextModel, gguf
 
 
 @ModelBase.register("GlmForCausalLM", "ChatGLMModel", "ChatGLMForConditionalGeneration")
+@ModelBase.example("THUDM/chatglm3-6b", "zai-org/glm-4-9b-chat-hf")
 class ChatGLMModel(TextModel):
     model_arch = gguf.MODEL_ARCH.CHATGLM
 

conversion/codeshell.py

@@ -4,6 +4,7 @@ from .base import ModelBase, TextModel, gguf
 
 
 @ModelBase.register("CodeShellForCausalLM")
+@ModelBase.example("WisdomShell/CodeShell-7B")
 class CodeShellModel(TextModel):
     model_arch = gguf.MODEL_ARCH.CODESHELL
 

conversion/cogvlm.py

@@ -11,6 +11,7 @@ from .llama import LlamaModel
 
 
 @ModelBase.register("CogVLMForCausalLM")
+@ModelBase.example("THUDM/cogvlm2-llama3-chat-19B", "THUDM/cogvlm-chat-hf")
 class CogVLMVisionModel(MmprojModel):
 
     def set_gguf_parameters(self):
@@ -29,5 +30,6 @@ class CogVLMVisionModel(MmprojModel):
 
 
 @ModelBase.register("CogVLMForCausalLM")
+@ModelBase.example("THUDM/cogvlm2-llama3-chat-19B", "THUDM/cogvlm-chat-hf")
 class CogVLMModel(LlamaModel):
     model_arch = gguf.MODEL_ARCH.COGVLM

conversion/command_r.py

@@ -12,6 +12,8 @@ from .base import ModelBase, TextModel, gguf, logger
 
 
 @ModelBase.register("CohereForCausalLM")
+# [TAG_HF_EXAMPLE_GATED] CohereLabs/c4ai-command-r-v01 is gated
+# [TAG_HF_EXAMPLE_MISSING]
 class CommandR2Model(TextModel):
     model_arch = gguf.MODEL_ARCH.COMMAND_R
 
@@ -30,6 +32,8 @@ class CommandR2Model(TextModel):
 
 
 @ModelBase.register("Cohere2ForCausalLM")
+# [TAG_HF_EXAMPLE_GATED] CohereLabs/c4ai-command-r7b-12-2024 is gated
+@ModelBase.example("hf-tiny-v2/tiny-random-Cohere2ForCausalLM")
 class Cohere2Model(TextModel):
     model_arch = gguf.MODEL_ARCH.COHERE2
 
@@ -59,6 +63,7 @@ class Cohere2Model(TextModel):
 
 
 @ModelBase.register("Cohere2MoeForCausalLM")
+@ModelBase.example("CohereLabs/North-Mini-Code-1.0")
 class Cohere2MoeModel(TextModel):
     model_arch = gguf.MODEL_ARCH.COHERE2MOE
     _n_main_layers: int | None = None

conversion/dbrx.py

@@ -9,6 +9,7 @@ from .base import ModelBase, TextModel, gguf, logger
 
 
 @ModelBase.register("DbrxForCausalLM")
+@ModelBase.example("alpindale/dbrx-instruct")
 class DbrxModel(TextModel):
     model_arch = gguf.MODEL_ARCH.DBRX
 

conversion/deci.py

@@ -13,6 +13,7 @@ from .base import ModelBase, TextModel, gguf
 
 
 @ModelBase.register("DeciLMForCausalLM")
+@ModelBase.example("nvidia/Llama-3_1-Nemotron-51B-Instruct", "Deci/DeciLM-7B")
 class DeciModel(TextModel):
     model_arch = gguf.MODEL_ARCH.DECI
 

conversion/deepseek.py

@@ -18,6 +18,7 @@ from .qwen import QwenModel
 
 
 @ModelBase.register("DeepseekOCRForCausalLM")
+@ModelBase.example("deepseek-ai/DeepSeek-OCR")
 class DeepseekOCRVisionModel(MmprojModel):
     # HF dynamic_preprocess() max_num, which differs per model
     preproc_max_tiles = 9
@@ -100,11 +101,13 @@ class DeepseekOCRVisionModel(MmprojModel):
 
 
 @ModelBase.register("UnlimitedOCRForCausalLM")
+@ModelBase.example("baidu/Unlimited-OCR")
 class UnlimitedOCRVisionModel(DeepseekOCRVisionModel):
     preproc_max_tiles = 32
 
 
 @ModelBase.register("DeepseekOCR2ForCausalLM")
+@ModelBase.example("deepseek-ai/DeepSeek-OCR-2")
 class DeepseekOCR2VisionModel(DeepseekOCRVisionModel):
     preproc_max_tiles = 6
 
@@ -134,6 +137,7 @@ class DeepseekOCR2VisionModel(DeepseekOCRVisionModel):
 
 
 @ModelBase.register("DeepseekForCausalLM")
+@ModelBase.example("deepseek-ai/deepseek-moe-16b-chat")
 class DeepseekModel(TextModel):
     model_arch = gguf.MODEL_ARCH.DEEPSEEK
 
@@ -228,6 +232,7 @@ class DeepseekModel(TextModel):
     "YoutuForCausalLM",
     "YoutuVLForConditionalGeneration",
 )
+@ModelBase.example("deepseek-ai/DeepSeek-V2-Lite", "deepseek-ai/DeepSeek-V3")
 class DeepseekV2Model(TextModel):
     model_arch = gguf.MODEL_ARCH.DEEPSEEK2
 
@@ -457,6 +462,7 @@ class DeepseekV2Model(TextModel):
 
 
 @ModelBase.register("DeepseekV32ForCausalLM")
+@ModelBase.example("deepseek-ai/DeepSeek-V3.2-Exp")
 class DeepseekV32Model(DeepseekV2Model):
     model_arch = gguf.MODEL_ARCH.DEEPSEEK32
     skip_mtp = False
@@ -517,6 +523,7 @@ class DeepseekV32Model(DeepseekV2Model):
 
 
 @ModelBase.register("DeepseekV4ForCausalLM")
+@ModelBase.example("deepseek-ai/DeepSeek-V4-Flash-Base")
 class DeepseekV4Model(TextModel):
     model_arch = gguf.MODEL_ARCH.DEEPSEEK4
     supports_mtp_export = True
@@ -911,6 +918,7 @@ class DeepseekV4Model(TextModel):
 
 
 @ModelBase.register("DeepseekV4DSparkModel")
+@ModelBase.example("deepseek-ai/DeepSeek-V4-Flash-DSpark")
 class DeepseekV4DSparkModel(DeepseekV4Model):
     model_arch = gguf.MODEL_ARCH.DFLASH
 

conversion/dots1.py

@@ -11,6 +11,7 @@ from .qwen import Qwen2MoeModel
 
 
 @ModelBase.register("Dots1ForCausalLM")
+@ModelBase.example("rednote-hilab/dots.llm1.inst")
 class Dots1Model(Qwen2MoeModel):
     model_arch = gguf.MODEL_ARCH.DOTS1
 

conversion/dotsocr.py

@@ -9,6 +9,7 @@ from .base import MmprojModel, ModelBase, gguf
 
 
 @ModelBase.register("DotsOCRForCausalLM")
+@ModelBase.example("rednote-hilab/dots.ocr")
 class DotsOCRVisionModel(MmprojModel):
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)

conversion/dream.py

@@ -9,6 +9,7 @@ from .base import ModelBase, TextModel, gguf
 
 
 @ModelBase.register("DreamModel")
+@ModelBase.example("Dream-org/Dream-v0-Instruct-7B")
 class DreamModel(TextModel):
     model_arch = gguf.MODEL_ARCH.DREAM
 

conversion/ernie.py

@@ -15,6 +15,7 @@ from .base import MmprojModel, ModelBase, TextModel, gguf
 
 
 @ModelBase.register("Ernie4_5_ForCausalLM", "Ernie4_5ForCausalLM")
+@ModelBase.example("baidu/ERNIE-4.5-0.3B-PT")
 class Ernie4_5Model(TextModel):
     model_arch = gguf.MODEL_ARCH.ERNIE4_5
 
@@ -73,6 +74,7 @@ class Ernie4_5Model(TextModel):
 
 
 @ModelBase.register("Ernie4_5_MoeForCausalLM")
+@ModelBase.example("baidu/ERNIE-4.5-21B-A3B-PT")
 class Ernie4_5MoeModel(Ernie4_5Model):
     model_arch = gguf.MODEL_ARCH.ERNIE4_5_MOE
     _experts: list[dict[str, Tensor]] | None = None
@@ -156,11 +158,13 @@ class Ernie4_5MoeModel(Ernie4_5Model):
 
 
 @ModelBase.register("PaddleOCRVLForConditionalGeneration")
+@ModelBase.example("PaddlePaddle/PaddleOCR-VL")
 class PaddleOCRModel(Ernie4_5Model):
     model_arch = gguf.MODEL_ARCH.PADDLEOCR
 
 
 @ModelBase.register("PaddleOCRVisionModel")
+@ModelBase.example("PaddlePaddle/PaddleOCR-VL")
 class PaddleOCRVisionModel(MmprojModel):
     # PaddleOCR-VL uses a modified version of Siglip
     min_pixels: int = 0

conversion/exaone.py

@@ -15,6 +15,7 @@ from .qwenvl import Qwen2VLVisionModel
 
 
 @ModelBase.register("ExaoneForCausalLM")
+@ModelBase.example("LGAI-EXAONE/EXAONE-3.5-2.4B-Instruct")
 class ExaoneModel(TextModel):
     model_arch = gguf.MODEL_ARCH.EXAONE
 
@@ -60,6 +61,7 @@ class ExaoneModel(TextModel):
 
 
 @ModelBase.register("Exaone4ForCausalLM")
+@ModelBase.example("LGAI-EXAONE/EXAONE-4.0-32B")
 class Exaone4Model(TextModel):
     model_arch = gguf.MODEL_ARCH.EXAONE4
 
@@ -126,6 +128,7 @@ class Exaone4Model(TextModel):
 # note: transformers >= 5.1 renamed the class to "ExaoneMoeForCausalLM" (lowercase 'e'),
 #       so accept both spellings - LG AI have updated the configs of already-released models
 @ModelBase.register("ExaoneMoEForCausalLM", "ExaoneMoeForCausalLM")
+@ModelBase.example("LGAI-EXAONE/K-EXAONE-236B-A23B")
 class ExaoneMoEModel(Exaone4Model):
     model_arch = gguf.MODEL_ARCH.EXAONE_MOE
 
@@ -214,6 +217,7 @@ class ExaoneMoEModel(Exaone4Model):
 
 
 @ModelBase.register("Exaone4_5_ForConditionalGeneration")
+@ModelBase.example("LGAI-EXAONE/EXAONE-4.5-33B")
 class Exaone4_5_TextModel(Exaone4Model):
     """Text tower of EXAONE 4.5; Tensors match EXAONE4"""
 
@@ -267,6 +271,7 @@ class Exaone4_5_TextModel(Exaone4Model):
 
 
 @ModelBase.register("Exaone4_5_ForConditionalGeneration")
+@ModelBase.example("LGAI-EXAONE/EXAONE-4.5-33B")
 class Exaone4_5VisionModel(Qwen2VLVisionModel):
     """Vision tower for EXAONE 4.5; Qwen2-VL-style ViT (GQA) + patch merger"""
 

conversion/falcon.py

@@ -11,6 +11,7 @@ from .base import ModelBase, TextModel, gguf
 
 
 @ModelBase.register("FalconForCausalLM", "RWForCausalLM")
+@ModelBase.example("tiiuae/falcon-7b")
 class FalconModel(TextModel):
     model_arch = gguf.MODEL_ARCH.FALCON
 

conversion/falcon_h1.py

@@ -12,6 +12,7 @@ from .mamba import Mamba2Model
 
 
 @ModelBase.register("FalconH1ForCausalLM")
+@ModelBase.example("tiiuae/Falcon-H1-0.5B-Base")
 class FalconH1Model(Mamba2Model):
     model_arch = gguf.MODEL_ARCH.FALCON_H1
 

conversion/gemma.py

@@ -14,6 +14,8 @@ from .base import MmprojModel, ModelBase, TextModel, gguf, logger
 
 
 @ModelBase.register("GemmaForCausalLM")
+# [TAG_HF_EXAMPLE_GATED] google/gemma-2b is gated
+@ModelBase.example("trl-internal-testing/tiny-GemmaForCausalLM")
 class GemmaModel(TextModel):
     model_arch = gguf.MODEL_ARCH.GEMMA
 
@@ -68,6 +70,8 @@ class GemmaModel(TextModel):
 
 
 @ModelBase.register("Gemma2ForCausalLM")
+# [TAG_HF_EXAMPLE_GATED] google/gemma-2-9b-it is gated
+@ModelBase.example("trl-internal-testing/tiny-Gemma2ForCausalLM")
 class Gemma2Model(TextModel):
     model_arch = gguf.MODEL_ARCH.GEMMA2
 
@@ -118,6 +122,8 @@ class Gemma2Model(TextModel):
 
 
 @ModelBase.register("Gemma3ForCausalLM", "Gemma3ForConditionalGeneration")
+# [TAG_HF_EXAMPLE_GATED] google/gemma-3-4b-it is gated
+@ModelBase.example("trl-internal-testing/tiny-Gemma3ForConditionalGeneration", "hf-tiny-v2/tiny-random-Gemma3ForCausalLM")
 class Gemma3Model(TextModel):
     model_arch = gguf.MODEL_ARCH.GEMMA3
 
@@ -174,6 +180,8 @@ class Gemma3Model(TextModel):
 
 
 @ModelBase.register("Gemma3TextModel")
+# [TAG_HF_EXAMPLE_GATED] google/embeddinggemma-300m is gated
+@ModelBase.example("hf-tiny-v2/tiny-random-Gemma3TextModel")
 class EmbeddingGemma(Gemma3Model):
     model_arch = gguf.MODEL_ARCH.GEMMA_EMBEDDING
     module_paths = []
@@ -248,6 +256,8 @@ class EmbeddingGemma(Gemma3Model):
 
 
 @ModelBase.register("Gemma3ForConditionalGeneration")
+# [TAG_HF_EXAMPLE_GATED] google/gemma-3-4b-it is gated
+@ModelBase.example("trl-internal-testing/tiny-Gemma3ForConditionalGeneration")
 class Gemma3VisionModel(MmprojModel):
     def set_gguf_parameters(self):
         super().set_gguf_parameters()
@@ -352,6 +362,8 @@ class ConformerAudioModel(MmprojModel):
 
 
 @ModelBase.register("Gemma3nForConditionalGeneration")
+# [TAG_HF_EXAMPLE_GATED] google/gemma-3n-E2B-it is gated
+@ModelBase.example("hf-tiny-v2/tiny-random-Gemma3nForConditionalGeneration")
 class Gemma3nVisionAudioModel(ConformerAudioModel):
     has_audio_encoder = True
     has_vision_encoder = True
@@ -471,6 +483,8 @@ class Gemma3nVisionAudioModel(ConformerAudioModel):
 
 
 @ModelBase.register("Gemma3nForCausalLM", "Gemma3nForConditionalGeneration")
+# [TAG_HF_EXAMPLE_GATED] google/gemma-3n-E2B-it is gated
+@ModelBase.example("hf-tiny-v2/tiny-random-Gemma3nForConditionalGeneration")
 class Gemma3NModel(Gemma3Model):
     model_arch = gguf.MODEL_ARCH.GEMMA3N
 
@@ -615,6 +629,7 @@ class Gemma3NModel(Gemma3Model):
 
 
 @ModelBase.register("Gemma4ForConditionalGeneration", "Gemma4ForCausalLM")
+@ModelBase.example("google/gemma-4-31B-it", "google/gemma-4-26B-A4B-it", "google/gemma-4-E2B-it")
 class Gemma4Model(Gemma3Model):
     model_arch = gguf.MODEL_ARCH.GEMMA4
 
@@ -795,6 +810,7 @@ class Gemma4Model(Gemma3Model):
 
 
 @ModelBase.register("Gemma4UnifiedForConditionalGeneration")
+@ModelBase.example("hf-tiny-v2/tiny-random-Gemma4UnifiedForConditionalGeneration")
 class Gemma4UnifiedModel(Gemma4Model):
     model_arch = gguf.MODEL_ARCH.GEMMA4
 
@@ -815,6 +831,7 @@ class Gemma4UnifiedModel(Gemma4Model):
 
 
 @ModelBase.register("Gemma4AssistantForCausalLM", "Gemma4UnifiedAssistantForCausalLM")
+@ModelBase.example("google/gemma-4-31B-it-assistant", "google/gemma-4-26B-A4B-it-assistant", "google/gemma-4-E2B-it-assistant")
 class Gemma4AssistantModel(Gemma4Model):
     model_arch = gguf.MODEL_ARCH.GEMMA4_ASSISTANT
 
@@ -835,6 +852,7 @@ class Gemma4AssistantModel(Gemma4Model):
 
 
 @ModelBase.register("Gemma4ForConditionalGeneration")
+@ModelBase.example("google/gemma-4-31B-it", "google/gemma-4-26B-A4B-it", "google/gemma-4-E2B-it")
 class Gemma4VisionAudioModel(MmprojModel):
     has_audio_encoder = True
     has_vision_encoder = True
@@ -913,6 +931,7 @@ class Gemma4VisionAudioModel(MmprojModel):
 
 
 @ModelBase.register("Gemma4UnifiedForConditionalGeneration")
+@ModelBase.example("hf-tiny-v2/tiny-random-Gemma4UnifiedForConditionalGeneration")
 class Gemma4UnifiedVisionAudioModel(Gemma4VisionAudioModel):
     has_audio_encoder = True
     has_vision_encoder = True

conversion/glm.py

@@ -15,6 +15,7 @@ from .deepseek import DeepseekV2Model
 
 
 @ModelBase.register("Glm4ForCausalLM", "Glm4vForConditionalGeneration")
+@ModelBase.example("zai-org/GLM-4-9B-0414")
 class Glm4Model(TextModel):
     model_arch = gguf.MODEL_ARCH.GLM4
     use_mrope = False
@@ -86,6 +87,7 @@ class Glm4Model(TextModel):
 
 
 @ModelBase.register("GlmOcrForConditionalGeneration")
+@ModelBase.example("zai-org/GLM-OCR")
 class GlmOCRModel(Glm4Model):
     model_arch = gguf.MODEL_ARCH.GLM4
     use_mrope = False
@@ -107,6 +109,7 @@ class GlmOCRModel(Glm4Model):
 
 
 @ModelBase.register("Glm4MoeForCausalLM", "Glm4vMoeForConditionalGeneration")
+@ModelBase.example("zai-org/GLM-4.5-Air")
 class Glm4MoeModel(TextModel):
     model_arch = gguf.MODEL_ARCH.GLM4_MOE
 
@@ -204,6 +207,7 @@ class Glm4MoeModel(TextModel):
 
 
 @ModelBase.register("Glm4MoeLiteForCausalLM")
+@ModelBase.example("zai-org/GLM-4.7-Flash")
 class Glm4MoeLiteModel(DeepseekV2Model):
     model_arch = gguf.MODEL_ARCH.DEEPSEEK2
     skip_mtp = False
@@ -272,6 +276,7 @@ class Glm4MoeLiteModel(DeepseekV2Model):
 
 
 @ModelBase.register("GlmMoeDsaForCausalLM")
+@ModelBase.example("zai-org/GLM-5.2")
 class GlmMoeDsaModel(DeepseekV2Model):
     model_arch = gguf.MODEL_ARCH.GLM_DSA
     skip_mtp = False
@@ -340,6 +345,7 @@ class GlmMoeDsaModel(DeepseekV2Model):
 
 
 @ModelBase.register("SolarOpenForCausalLM")
+@ModelBase.example("upstage/Solar-Open-100B")
 class SolarOpenModel(Glm4MoeModel):
     model_arch = gguf.MODEL_ARCH.GLM4_MOE
 

conversion/gpt2.py

@@ -11,6 +11,7 @@ from .base import ModelBase, TextModel, gguf, logger
 
 
 @ModelBase.register("GPT2LMHeadModel")
+@ModelBase.example("openai-community/gpt2")
 class GPT2Model(TextModel):
     model_arch = gguf.MODEL_ARCH.GPT2
 
@@ -38,6 +39,7 @@ class GPT2Model(TextModel):
 
 
 @ModelBase.register("RuGPT3XLForCausalLM")
+@ModelBase.example("evilfreelancer/ruGPT3XL")
 class RuGPT3XLModel(TextModel):
     model_arch = gguf.MODEL_ARCH.GPT2
 

conversion/gpt_oss.py

@@ -11,6 +11,7 @@ from .base import ModelBase, TextModel, gguf, logger
 
 
 @ModelBase.register("GptOssForCausalLM")
+@ModelBase.example("openai/gpt-oss-20b")
 class GptOssModel(TextModel):
     model_arch = gguf.MODEL_ARCH.GPT_OSS
 

conversion/gptneox.py

@@ -13,6 +13,7 @@ from .base import ModelBase, TextModel, gguf, logger
 
 
 @ModelBase.register("GPTNeoXForCausalLM")
+@ModelBase.example("EleutherAI/pythia-70m")
 class GPTNeoXModel(TextModel):
     model_arch = gguf.MODEL_ARCH.GPTNEOX
 

conversion/granite.py

@@ -15,6 +15,7 @@ from .mamba import Mamba2Model
 
 
 @ModelBase.register("GraniteForCausalLM")
+@ModelBase.example("ibm-granite/granite-3.3-2b-instruct")
 class GraniteModel(LlamaModel):
     """Conversion for IBM's GraniteForCausalLM"""
     model_arch = gguf.MODEL_ARCH.GRANITE
@@ -74,6 +75,7 @@ class GraniteModel(LlamaModel):
 
 
 @ModelBase.register("GraniteMoeForCausalLM", "GraniteMoeSharedForCausalLM")
+@ModelBase.example("ibm-granite/granite-3.1-3b-a800m-instruct")
 class GraniteMoeModel(GraniteModel):
     """Conversion for IBM's GraniteMoeForCausalLM"""
     model_arch = gguf.MODEL_ARCH.GRANITE_MOE
@@ -124,6 +126,7 @@ class GraniteMoeModel(GraniteModel):
 
 
 @ModelBase.register("GraniteSwitchForCausalLM")
+@ModelBase.example("ibm-granite/granite-switch-4.1-3b-preview")
 class GraniteSwitchModel(GraniteMoeModel):
     """Dense, all-attention Granite with N per-token embedded LoRA adapters, stacked
     over the adapter dim with a zero adapter at slot 0 (N = num_adapters + 1)."""
@@ -284,6 +287,7 @@ class GraniteSwitchModel(GraniteMoeModel):
 
 
 @ModelBase.register("GraniteMoeHybridForCausalLM", "BambaForCausalLM")
+@ModelBase.example("ibm-granite/granite-4.0-h-tiny", "ibm-ai-platform/Bamba-9B-v2")
 class GraniteHybridModel(Mamba2Model, GraniteMoeModel):
     """GraniteHybrid is a hybrid SSM + Attention model that uses Mamba2 SSM
     layers and optionally uses MoE w/ a shared expert"""
@@ -426,6 +430,7 @@ class GraniteHybridModel(Mamba2Model, GraniteMoeModel):
 
 
 @ModelBase.register("GraniteSpeechForConditionalGeneration")
+@ModelBase.example("ibm-granite/granite-speech-3.3-2b", "ibm-granite/granite-4.0-1b-speech")
 class GraniteSpeechMmprojModel(MmprojModel):
     has_vision_encoder = False
     has_audio_encoder = True
@@ -509,6 +514,7 @@ class GraniteSpeechMmprojModel(MmprojModel):
 
 
 @ModelBase.register("GraniteSpeechPlusForConditionalGeneration")
+@ModelBase.example("ibm-granite/granite-speech-4.1-2b-plus")
 class GraniteSpeechPlusMmprojModel(GraniteSpeechMmprojModel):
     """Conversion for GraniteSpeechPlus - extends GraniteSpeech with feature layer concatenation"""
     has_vision_encoder = False
@@ -537,6 +543,7 @@ class GraniteSpeechPlusMmprojModel(GraniteSpeechMmprojModel):
 
 
 @ModelBase.register("Granite4VisionForConditionalGeneration")
+@ModelBase.example("ibm-granite/granite-4.0-3b-vision")
 class Granite4VisionMmprojModel(MmprojModel):
     has_vision_encoder = True
     has_audio_encoder = False

conversion/grok.py

@@ -13,6 +13,7 @@ from .base import ModelBase, TextModel, gguf, logger
 
 
 @ModelBase.register("GrokForCausalLM", "Grok1ForCausalLM")
+@ModelBase.example("keyfan/grok-1-hf")
 class GrokModel(TextModel):
     model_arch = gguf.MODEL_ARCH.GROK
 

conversion/grovemoe.py

@@ -11,6 +11,7 @@ from .base import ModelBase, TextModel, gguf, logger
 
 
 @ModelBase.register("GroveMoeForCausalLM", "modeling_grove_moe.GroveMoeForCausalLM")
+@ModelBase.example("inclusionAI/GroveMoE-Inst")
 class GroveMoeModel(TextModel):
     model_arch = gguf.MODEL_ARCH.GROVEMOE
 

conversion/hunyuan.py

@@ -17,6 +17,7 @@ from .qwen import QwenModel
 
 
 @ModelBase.register("HunYuanMoEV1ForCausalLM")
+@ModelBase.example("tencent/Hunyuan-A13B-Instruct")
 class HunYuanMoEModel(TextModel):
     model_arch = gguf.MODEL_ARCH.HUNYUAN_MOE
 
@@ -154,6 +155,7 @@ class HunYuanMoEModel(TextModel):
 
 
 @ModelBase.register("HunYuanDenseV1ForCausalLM")
+@ModelBase.example("tencent/Hunyuan-4B-Instruct")
 class HunYuanModel(TextModel):
     model_arch = gguf.MODEL_ARCH.HUNYUAN_DENSE
 
@@ -290,6 +292,7 @@ class HunYuanModel(TextModel):
 
 
 @ModelBase.register("HunYuanVLForConditionalGeneration")
+@ModelBase.example("tencent/HunyuanOCR")
 class HunyuanVLVisionModel(MmprojModel):
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
@@ -333,6 +336,7 @@ class HunyuanVLVisionModel(MmprojModel):
 
 
 @ModelBase.register("HunYuanVLForConditionalGeneration")
+@ModelBase.example("tencent/HunyuanOCR")
 class HunyuanVLTextModel(HunYuanModel):
     model_arch = gguf.MODEL_ARCH.HUNYUAN_VL
 
@@ -365,6 +369,7 @@ class HunyuanVLTextModel(HunYuanModel):
 
 
 @ModelBase.register("HYV3ForCausalLM")
+@ModelBase.example("tencent/Hy3")
 class HYV3Model(TextModel):
     model_arch = gguf.MODEL_ARCH.HY_V3
     supports_mtp_export = True

conversion/internlm.py

@@ -14,6 +14,7 @@ from .llama import LlamaModel
 
 
 @ModelBase.register("InternLM2ForCausalLM")
+@ModelBase.example("internlm/internlm2-chat-7b")
 class InternLM2Model(TextModel):
     model_arch = gguf.MODEL_ARCH.INTERNLM2
 
@@ -170,6 +171,7 @@ class InternLM2Model(TextModel):
 
 
 @ModelBase.register("InternLM3ForCausalLM")
+@ModelBase.example("internlm/internlm3-8b-instruct")
 class InternLM3Model(TextModel):
     model_arch = gguf.MODEL_ARCH.LLAMA
 

conversion/internvl.py

@@ -9,6 +9,7 @@ from .base import MmprojModel, ModelBase, gguf
 
 
 @ModelBase.register("InternVisionModel")
+@ModelBase.example("OpenGVLab/InternVL3-2B", "OpenGVLab/InternVL2_5-1B")
 class InternVisionModel(MmprojModel):
 
     min_dynamic_tiles: int = 0

conversion/jais.py

@@ -11,6 +11,8 @@ from .base import ModelBase, TextModel, gguf
 
 
 @ModelBase.register("Jais2ForCausalLM")
+# [TAG_HF_EXAMPLE_GATED] inceptionai/Jais-2-8B-Chat is gated
+# [TAG_HF_EXAMPLE_MISSING]
 class Jais2Model(TextModel):
     model_arch = gguf.MODEL_ARCH.JAIS2
 
@@ -22,6 +24,7 @@ class Jais2Model(TextModel):
 
 
 @ModelBase.register("JAISLMHeadModel")
+@ModelBase.example("inceptionai/jais-family-590m")
 class JaisModel(TextModel):
     model_arch = gguf.MODEL_ARCH.JAIS
 

conversion/jamba.py

@@ -11,6 +11,7 @@ from .base import ModelBase, TextModel, gguf, logger
 
 
 @ModelBase.register("JambaForCausalLM")
+@ModelBase.example("ai21labs/Jamba-v0.1")
 class JambaModel(TextModel):
     model_arch = gguf.MODEL_ARCH.JAMBA
 

conversion/januspro.py

@@ -11,6 +11,7 @@ from .llama import LlamaModel
 
 
 @ModelBase.register("JanusForConditionalGeneration")
+@ModelBase.example("deepseek-community/Janus-Pro-1B")
 class JanusProModel(LlamaModel):
     model_arch = gguf.MODEL_ARCH.LLAMA  # reuse Llama arch
 
@@ -34,6 +35,7 @@ class JanusProModel(LlamaModel):
 
 
 @ModelBase.register("JanusForConditionalGeneration")
+@ModelBase.example("deepseek-community/Janus-Pro-1B")
 class JanusProVisionModel(MmprojModel):
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)

conversion/kimi_k3.py

@@ -16,6 +16,7 @@ from .kimi_linear import KimiLinearModel
 
 
 @ModelBase.register("KimiK3ForConditionalGeneration")
+@ModelBase.example("moonshotai/Kimi-K3")
 class KimiK3Model(TextModel):
     """
     Kimi-K3 text model (KimiLinearForCausalLM under a `language_model.` prefix).

conversion/kimi_linear.py

@@ -13,6 +13,7 @@ from .qwen import QwenModel
 
 
 @ModelBase.register("KimiLinearModel", "KimiLinearForCausalLM")
+@ModelBase.example("moonshotai/Kimi-Linear-48B-A3B-Instruct")
 class KimiLinearModel(TextModel):
     """Kimi-Linear model with hybrid MLA+KDA architecture"""
     model_arch = gguf.MODEL_ARCH.KIMI_LINEAR

conversion/kimivl.py

@@ -11,6 +11,7 @@ from .base import MmprojModel, ModelBase, gguf
 
 
 @ModelBase.register("KimiVLForConditionalGeneration")
+@ModelBase.example("moonshotai/Kimi-VL-A3B-Instruct")
 class KimiVLModel(MmprojModel):
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
@@ -52,6 +53,7 @@ class KimiVLModel(MmprojModel):
 
 
 @ModelBase.register("KimiK25ForConditionalGeneration")
+@ModelBase.example("moonshotai/Kimi-K2.5")
 class KimiK25Model(MmprojModel):
     """Kimi-K2.5 with MoonViT3d vision encoder"""
 
@@ -155,6 +157,7 @@ class KimiK25Model(MmprojModel):
 
 
 @ModelBase.register("Glm5vForConditionalGeneration")
+# [TAG_HF_EXAMPLE_MISSING]
 class Glm5vModel(KimiK25Model):
     """GLM-5.2-Vision MoonViT3d encoder and projector
 

conversion/laguna.py

@@ -13,6 +13,7 @@ from .base import ModelBase, TextModel, gguf, logger
 
 
 @ModelBase.register("LagunaForCausalLM")
+@ModelBase.example("poolside/Laguna-XS.2", "poolside/Laguna-S-2.1")
 class LagunaModel(TextModel):
     model_arch = gguf.MODEL_ARCH.LAGUNA
     _experts: list[dict] | None = None

conversion/lfm2.py

@@ -13,6 +13,7 @@ from .gemma import ConformerAudioModel
 
 
 @ModelBase.register("Lfm2ForCausalLM", "LFM2ForCausalLM")
+@ModelBase.example("LiquidAI/LFM2-1.2B", "LiquidAI/LFM2.5-350M")
 class LFM2Model(TextModel):
     model_arch = gguf.MODEL_ARCH.LFM2
 
@@ -65,6 +66,7 @@ class LFM2Model(TextModel):
 
 
 @ModelBase.register("Lfm2Model", "Lfm2BidirectionalModel")
+@ModelBase.example("LiquidAI/LFM2.5-ColBERT-350M", "LiquidAI/LFM2.5-Embedding-350M")
 class LFM2ColBertModel(LFM2Model):
     model_arch = gguf.MODEL_ARCH.LFM2
     dense_tensor_name = "dense_2"
@@ -93,6 +95,7 @@ class LFM2ColBertModel(LFM2Model):
 
 
 @ModelBase.register("Lfm2MoeForCausalLM")
+@ModelBase.example("LiquidAI/LFM2-8B-A1B")
 class LFM2MoeModel(TextModel):
     model_arch = gguf.MODEL_ARCH.LFM2MOE
 
@@ -166,6 +169,7 @@ class LFM2MoeModel(TextModel):
 
 
 @ModelBase.register("Lfm2VlForConditionalGeneration")
+@ModelBase.example("LiquidAI/LFM2-VL-450M")
 class LFM2VLModel(MmprojModel):
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
@@ -200,6 +204,7 @@ class LFM2VLModel(MmprojModel):
 
 
 @ModelBase.register("Lfm2AudioForConditionalGeneration")
+@ModelBase.example("LiquidAI/LFM2.5-Audio-1.5B", "LiquidAI/LFM2-Audio-1.5B")
 class LFM2AudioModel(ConformerAudioModel):
     has_vision_encoder = False
     has_audio_encoder = True
@@ -238,6 +243,7 @@ class LFM2AudioModel(ConformerAudioModel):
 
 
 @ModelBase.register("Lfm25AudioTokenizer")
+@ModelBase.example("LiquidAI/LFM2.5-Audio-1.5B")
 class LFM25AudioTokenizer(LFM2Model):
     model_arch = gguf.MODEL_ARCH.LFM2
 

conversion/lighton_ocr.py

@@ -11,6 +11,7 @@ from .llava import LlavaVisionModel
 
 
 @ModelBase.register("LightOnOCRForConditionalGeneration")
+@ModelBase.example("lightonai/LightOnOCR-1B-1025")
 class LightOnOCRVisionModel(LlavaVisionModel):
     is_mistral_format = False
     use_break_tok = False

conversion/llada.py

@@ -11,6 +11,7 @@ from .base import ModelBase, TextModel, gguf
 
 
 @ModelBase.register("LLaDAModelLM")
+@ModelBase.example("GSAI-ML/LLaDA-8B-Instruct")
 class LLaDAModel(TextModel):
     model_arch = gguf.MODEL_ARCH.LLADA
     undo_permute = True
@@ -114,6 +115,7 @@ class LLaDAModel(TextModel):
 
 
 @ModelBase.register("LLaDAMoEModel", "LLaDAMoEModelLM")
+@ModelBase.example("inclusionAI/LLaDA-MoE-7B-A1B-Instruct")
 class LLaDAMoEModel(TextModel):
     model_arch = gguf.MODEL_ARCH.LLADA_MOE
 

conversion/llama.py

@@ -28,6 +28,8 @@ from .base import ModelBase, TextModel, gguf, logger
     "Eagle3DraftModel",
     "IQuestCoderForCausalLM",
     "LlamaModel")
+# [TAG_HF_EXAMPLE_GATED] meta-llama/Llama-3.2-1B-Instruct is gated
+@ModelBase.example("unsloth/Llama-3.2-1B-Instruct", "mistralai/Mistral-7B-Instruct-v0.3", "mistralai/Mixtral-8x7B-Instruct-v0.1")
 class LlamaModel(TextModel):
     model_arch = gguf.MODEL_ARCH.LLAMA
     undo_permute = True
@@ -359,6 +361,7 @@ class LlamaModel(TextModel):
 
 
 @ModelBase.register("ArceeForCausalLM")
+@ModelBase.example("arcee-ai/AFM-4.5B")
 class ArceeModel(LlamaModel):
     model_arch = gguf.MODEL_ARCH.ARCEE
 
@@ -371,6 +374,8 @@ class ArceeModel(LlamaModel):
     "Llama4ForConditionalGeneration",
     "Llama4ForCausalLM",
 )
+# [TAG_HF_EXAMPLE_GATED] meta-llama/Llama-4-Scout-17B-16E-Instruct is gated
+@ModelBase.example("unsloth/Llama-4-Scout-17B-16E-Instruct")
 class Llama4Model(LlamaModel):
     model_arch = gguf.MODEL_ARCH.LLAMA4
     undo_permute = False
@@ -412,16 +417,19 @@ class Llama4Model(LlamaModel):
 
 
 @ModelBase.register("LlamaBidirectionalModel")
+@ModelBase.example("nvidia/llama-embed-nemotron-8b")
 class LlamaEmbedNemotronModel(LlamaModel):
     model_arch = gguf.MODEL_ARCH.LLAMA_EMBED
 
 
 @ModelBase.register("SmolLM3ForCausalLM")
+@ModelBase.example("HuggingFaceTB/SmolLM3-3B")
 class SmolLM3Model(LlamaModel):
     model_arch = gguf.MODEL_ARCH.SMOLLM3
 
 
 @ModelBase.register("ApertusForCausalLM")
+@ModelBase.example("swiss-ai/Apertus-8B-Instruct-2509")
 class ApertusModel(LlamaModel):
     model_arch = gguf.MODEL_ARCH.APERTUS
     undo_permute = False

conversion/llama4.py

@@ -9,6 +9,8 @@ from .base import MmprojModel, ModelBase, gguf
 
 
 @ModelBase.register("Llama4ForConditionalGeneration")
+# [TAG_HF_EXAMPLE_GATED] meta-llama/Llama-4-Scout-17B-16E-Instruct is gated
+@ModelBase.example("unsloth/Llama-4-Scout-17B-16E-Instruct")
 class Llama4VisionModel(MmprojModel):
     def set_gguf_parameters(self):
         super().set_gguf_parameters()

conversion/llava.py

@@ -16,6 +16,7 @@ from .llama import LlamaModel
     "LlavaForConditionalGeneration", # pixtral
     "Mistral3ForConditionalGeneration", # mistral small 3.1
 )
+@ModelBase.example("mistral-community/pixtral-12b", "mistralai/Mistral-Small-3.1-24B-Instruct-2503")
 class LlavaVisionModel(MmprojModel):
     img_break_tok_id = -1
     use_break_tok = True

conversion/maincoder.py

@@ -4,6 +4,7 @@ from .base import ModelBase, TextModel, gguf
 
 
 @ModelBase.register("MaincoderForCausalLM")
+@ModelBase.example("Maincode/Maincoder-1B")
 class MaincoderModel(TextModel):
     model_arch = gguf.MODEL_ARCH.MAINCODER
 

conversion/mamba.py

@@ -14,6 +14,7 @@ from .base import ModelBase, TextModel, gguf, logger
 
 
 @ModelBase.register("MambaForCausalLM", "MambaLMHeadModel", "FalconMambaForCausalLM")
+@ModelBase.example("state-spaces/mamba-130m-hf", "tiiuae/falcon-mamba-7b")
 class MambaModel(TextModel):
     model_arch = gguf.MODEL_ARCH.MAMBA
 
@@ -100,6 +101,7 @@ class MambaModel(TextModel):
 
 
 @ModelBase.register("Mamba2ForCausalLM")
+@ModelBase.example("mistralai/Mamba-Codestral-7B-v0.1")
 class Mamba2Model(TextModel):
     model_arch = gguf.MODEL_ARCH.MAMBA2
 

conversion/mellum.py

@@ -11,6 +11,7 @@ from .base import ModelBase, TextModel, gguf, logger
 
 
 @ModelBase.register("MellumForCausalLM")
+@ModelBase.example("JetBrains/Mellum2-12B-A2.5B-Base")
 class MellumModel(TextModel):
     model_arch = gguf.MODEL_ARCH.MELLUM
 

conversion/mimo.py

@@ -14,6 +14,7 @@ from .base import MmprojModel, ModelBase, TextModel, gguf
 
 
 @ModelBase.register("MiMoV2FlashForCausalLM", "MiMoV2ForCausalLM")
+@ModelBase.example("XiaomiMiMo/MiMo-V2.5")
 class MimoV2Model(TextModel):
     model_arch = gguf.MODEL_ARCH.MIMO2
 
@@ -230,6 +231,7 @@ class MimoV2Model(TextModel):
 
 
 @ModelBase.register("MiMoV2ForCausalLM")
+@ModelBase.example("XiaomiMiMo/MiMo-V2.5")
 class MiMoV2VisionAudioModel(MmprojModel):
     has_audio_encoder = True
 

conversion/minicpm.py

@@ -14,6 +14,7 @@ from .qwen import Qwen3_5TextModel
 
 
 @ModelBase.register("MiniCPMForCausalLM")
+@ModelBase.example("openbmb/MiniCPM-2B-sft-bf16")
 class MiniCPMModel(TextModel):
     model_arch = gguf.MODEL_ARCH.MINICPM
 
@@ -61,6 +62,7 @@ class MiniCPMModel(TextModel):
 
 
 @ModelBase.register("MiniCPM3ForCausalLM")
+@ModelBase.example("openbmb/MiniCPM3-4B")
 class MiniCPM3Model(TextModel):
     model_arch = gguf.MODEL_ARCH.MINICPM3
 
@@ -117,6 +119,7 @@ class MiniCPM3Model(TextModel):
 # the LM (text mode) and once as the mmproj (vision mode), mirroring the Qwen3-VL setup.
 
 @ModelBase.register("MiniCPMV4_6ForConditionalGeneration")
+@ModelBase.example("openbmb/MiniCPM-V-4_6")
 class MiniCPMV4_6TextModel(Qwen3_5TextModel):
     model_arch = gguf.MODEL_ARCH.QWEN35
 
@@ -134,6 +137,7 @@ class MiniCPMV4_6TextModel(Qwen3_5TextModel):
 
 
 @ModelBase.register("MiniCPMV4_6ForConditionalGeneration")
+@ModelBase.example("openbmb/MiniCPM-V-4_6")
 class MiniCPMV4_6VisionModel(MmprojModel):
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)

conversion/minimax.py

@@ -12,6 +12,7 @@ from .base import ModelBase, TextModel, MmprojModel, gguf, logger
 
 @ModelBase.register("MiniMaxText01ForCausalLM")
 @ModelBase.register("MiniMaxM1ForCausalLM")
+@ModelBase.example("MiniMaxAI/MiniMax-Text-01", "MiniMaxAI/MiniMax-M1-40k")
 class MiniMaxText01Model(TextModel):
     model_arch = gguf.MODEL_ARCH.MINIMAX01
 
@@ -119,6 +120,7 @@ class MiniMaxText01Model(TextModel):
 
 
 @ModelBase.register("MiniMaxM2ForCausalLM")
+@ModelBase.example("MiniMaxAI/MiniMax-M2")
 class MiniMaxM2Model(TextModel):
     model_arch = gguf.MODEL_ARCH.MINIMAXM2
     _experts_cache: dict[int, dict[str, Tensor]] = {}
@@ -163,6 +165,7 @@ class MiniMaxM2Model(TextModel):
 
 
 @ModelBase.register("MiniMaxM3SparseForCausalLM", "MiniMaxM3SparseForConditionalGeneration")
+@ModelBase.example("MiniMaxAI/MiniMax-M3")
 class MiniMaxM3Model(MiniMaxM2Model):
     model_arch = gguf.MODEL_ARCH.MINIMAXM3
 
@@ -203,6 +206,7 @@ class MiniMaxM3Model(MiniMaxM2Model):
 
 
 @ModelBase.register("MiniMaxM3SparseForConditionalGeneration", "MiniMaxM3VLForConditionalGeneration")
+@ModelBase.example("MiniMaxAI/MiniMax-M3")
 class MiniMaxM3VisionModel(MmprojModel):
     @classmethod
     def filter_tensors(cls, item):

conversion/mistral3.py

@@ -15,6 +15,7 @@ from .llama import LlamaModel
     "Mistral3ForConditionalGeneration",
     "Ministral3ForCausalLM",
 )
+@ModelBase.example("mistralai/Mistral-Small-3.1-24B-Instruct-2503", "hf-tiny-v2/tiny-random-Ministral3ForCausalLM")
 class Mistral3Model(TextModel):
     class Ministral3Model(LlamaModel):
         model_arch = gguf.MODEL_ARCH.MISTRAL3

conversion/mpt.py

@@ -9,6 +9,7 @@ from .base import ModelBase, TextModel, gguf
 
 
 @ModelBase.register("MPTForCausalLM")
+@ModelBase.example("anas-awadalla/mpt-7b")
 class MPTModel(TextModel):
     model_arch = gguf.MODEL_ARCH.MPT
 

conversion/muse_glimmer.py

@@ -24,6 +24,7 @@ def _unpermute_for_rope(tensor: "Tensor", n_heads: int) -> "Tensor":
 
 
 @ModelBase.register("MuseGlimmerForConditionalGeneration")
+@ModelBase.example("meta-models/Muse-Glimmer-30B")
 class MuseGlimmerModel(TextModel):
     model_arch = gguf.MODEL_ARCH.MUSE_GLIMMER
 
@@ -78,6 +79,7 @@ class MuseGlimmerModel(TextModel):
 
 
 @ModelBase.register("MuseGlimmerForConditionalGeneration")
+@ModelBase.example("meta-models/Muse-Glimmer-30B")
 class MuseGlimmerVisionModel(MmprojModel):
     def get_vision_config(self) -> dict[str, Any] | None:
         c = self.global_config.get("vision_config")
@@ -131,6 +133,7 @@ class MuseGlimmerVisionModel(MmprojModel):
 
 
 @ModelBase.register("MuseGlimmerAssistantModel")
+@ModelBase.example("meta-models/Muse-Glimmer-30B-assistant")
 class MuseGlimmerAssistantModel(TextModel):
     model_arch = gguf.MODEL_ARCH.DFLASH
 

conversion/nanbeige.py

@@ -5,6 +5,7 @@ from .llama import LlamaModel
 
 
 @ModelBase.register("NanbeigeForCausalLM")
+@ModelBase.example("Nanbeige/Nanbeige4.2-3B")
 class NanbeigeModel(LlamaModel):
     model_arch = gguf.MODEL_ARCH.NANBEIGE
     undo_permute = True

conversion/nemotron.py

@@ -16,6 +16,7 @@ from .granite import GraniteHybridModel
     "NemotronH_Nano_VL_V2",
     "RADIOModel",
 )
+@ModelBase.example("nvidia/NVIDIA-Nemotron-Nano-12B-v2-VL-BF16")
 class NemotronNanoV2VLModel(MmprojModel):
     # ViT-Huge architecture parameters for RADIO v2.5-h
     _vit_hidden_size = 1280
@@ -151,6 +152,7 @@ class NemotronNanoV2VLModel(MmprojModel):
 
 
 @ModelBase.register("NemotronForCausalLM")
+@ModelBase.example("nvidia/Minitron-4B-Base")
 class NemotronModel(TextModel):
     model_arch = gguf.MODEL_ARCH.NEMOTRON
 
@@ -193,6 +195,7 @@ class NemotronModel(TextModel):
 
 
 @ModelBase.register("NemotronHForCausalLM")
+@ModelBase.example("nvidia/Nemotron-H-8B-Base-8K")
 class NemotronHModel(GraniteHybridModel):
     """Hybrid mamba2/attention model from NVIDIA"""
     model_arch = gguf.MODEL_ARCH.NEMOTRON_H

conversion/olmo.py

@@ -14,6 +14,7 @@ from .llama import LlamaModel
 
 @ModelBase.register("OlmoForCausalLM")
 @ModelBase.register("OLMoForCausalLM")
+@ModelBase.example("allenai/OLMo-1.7-7B-hf")
 class OlmoModel(TextModel):
     model_arch = gguf.MODEL_ARCH.OLMO
 
@@ -39,12 +40,14 @@ class OlmoModel(TextModel):
 
 
 @ModelBase.register("SeedOssForCausalLM")
+@ModelBase.example("ByteDance-Seed/Seed-OSS-36B-Instruct")
 class SeedOssModel(TextModel):
     model_arch = gguf.MODEL_ARCH.SEED_OSS
 
 
 @ModelBase.register("Olmo2ForCausalLM")
 @ModelBase.register("Olmo3ForCausalLM")
+@ModelBase.example("allenai/OLMo-2-1124-7B-Instruct", "allenai/Olmo-3-7B-Instruct")
 class Olmo2Model(TextModel):
     model_arch = gguf.MODEL_ARCH.OLMO2
 
@@ -67,6 +70,7 @@ class Olmo2Model(TextModel):
 
 
 @ModelBase.register("OlmoeForCausalLM")
+@ModelBase.example("allenai/OLMoE-1B-7B-0924")
 class OlmoeModel(TextModel):
     model_arch = gguf.MODEL_ARCH.OLMOE
 

conversion/openelm.py

@@ -9,6 +9,7 @@ from .base import ModelBase, TextModel, gguf
 
 
 @ModelBase.register("OpenELMForCausalLM")
+@ModelBase.example("apple/OpenELM-270M")
 class OpenELMModel(TextModel):
     model_arch = gguf.MODEL_ARCH.OPENELM
 

conversion/orion.py

@@ -4,6 +4,7 @@ from .base import ModelBase, TextModel, gguf
 
 
 @ModelBase.register("OrionForCausalLM")
+@ModelBase.example("OrionStarAI/Orion-14B-Base")
 class OrionModel(TextModel):
     model_arch = gguf.MODEL_ARCH.ORION
 

conversion/pangu.py

@@ -11,6 +11,7 @@ from .base import ModelBase, TextModel, gguf, logger
 
 
 @ModelBase.register("PanguEmbeddedForCausalLM")
+@ModelBase.example("FreedomIntelligence/openPangu-Embedded-7B-V1.1")
 class PanguEmbeddedModel(TextModel):
     model_arch = gguf.MODEL_ARCH.PANGU_EMBED
 

conversion/phi.py

@@ -14,6 +14,7 @@ from .base import MmprojModel, ModelBase, SentencePieceTokenTypes, TextModel, gg
 
 
 @ModelBase.register("PhiForCausalLM")
+@ModelBase.example("microsoft/phi-2")
 class Phi2Model(TextModel):
     model_arch = gguf.MODEL_ARCH.PHI2
 
@@ -36,6 +37,7 @@ class Phi2Model(TextModel):
 
 
 @ModelBase.register("Phi3ForCausalLM", "Phi4ForCausalLMV")
+@ModelBase.example("microsoft/Phi-3-mini-4k-instruct")
 class Phi3MiniModel(TextModel):
     model_arch = gguf.MODEL_ARCH.PHI3
 
@@ -210,6 +212,7 @@ class Phi3MiniModel(TextModel):
 
 
 @ModelBase.register("Phi4ForCausalLMV")
+# [TAG_HF_EXAMPLE_MISSING]
 class Phi4VisionMmprojModel(MmprojModel):
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
@@ -336,6 +339,7 @@ class Phi4VisionMmprojModel(MmprojModel):
 
 
 @ModelBase.register("PhiMoEForCausalLM")
+@ModelBase.example("microsoft/Phi-3.5-MoE-instruct")
 class PhiMoeModel(Phi3MiniModel):
     model_arch = gguf.MODEL_ARCH.PHIMOE
 

conversion/plamo.py

@@ -13,6 +13,7 @@ from .base import ModelBase, TextModel, gguf
 
 
 @ModelBase.register("PlamoForCausalLM")
+@ModelBase.example("pfnet/plamo-13b")
 class PlamoModel(TextModel):
     model_arch = gguf.MODEL_ARCH.PLAMO
 
@@ -58,6 +59,7 @@ class PlamoModel(TextModel):
 
 
 @ModelBase.register("Plamo2ForCausalLM", "PLaMo2ForCausalLM")
+@ModelBase.example("pfnet/plamo-2-1b")
 class Plamo2Model(TextModel):
     model_arch = gguf.MODEL_ARCH.PLAMO2
 
@@ -147,6 +149,8 @@ class Plamo2Model(TextModel):
 
 
 @ModelBase.register("Plamo3ForCausalLM", "PLaMo3ForCausalLM")
+# [TAG_HF_EXAMPLE_GATED] pfnet/plamo-3-nict-2b-base is gated
+@ModelBase.example("midorin-Linux/plamo-3-12b-self-merged-base")
 class Plamo3Model(TextModel):
     model_arch = gguf.MODEL_ARCH.PLAMO3
 

conversion/plm.py

@@ -4,6 +4,7 @@ from .base import ModelBase, TextModel, gguf
 
 
 @ModelBase.register("PLMForCausalLM")
+@ModelBase.example("PLM-Team/PLM-1.8B-Instruct")
 class PLMModel(TextModel):
     model_arch = gguf.MODEL_ARCH.PLM
 

conversion/pockettts.py

@@ -77,6 +77,7 @@ def _load_hparams(dir_model: Path) -> dict[str, Any]:
 
 
 @ModelBase.register("PocketTTSModel")
+# [TAG_HF_EXAMPLE_MISSING] model is gated, and the checkpoint requires cd to subdir, not supported here
 class PocketTTSModel(TextModel):
     model_arch = gguf.MODEL_ARCH.POCKETTTS
 
@@ -174,6 +175,7 @@ class PocketTTSModel(TextModel):
 
 
 @ModelBase.register("PocketTTSModel")
+# [TAG_HF_EXAMPLE_MISSING] model is gated, and the checkpoint requires cd to subdir, not supported here
 class PocketTTSMmprojModel(MmprojModel):
     has_audio_encoder = True
     has_vision_encoder = False

conversion/qwen.py

@@ -13,6 +13,7 @@ from .base import ModelBase, TextModel, gguf, logger
 
 
 @ModelBase.register("QWenLMHeadModel")
+@ModelBase.example("Qwen/Qwen-7B")
 class QwenModel(TextModel):
     model_arch = gguf.MODEL_ARCH.QWEN
 
@@ -51,6 +52,7 @@ class QwenModel(TextModel):
     "AudioFlamingo3ForConditionalGeneration",
     "DotsOCRForCausalLM",
 )
+@ModelBase.example("Qwen/Qwen2.5-7B-Instruct")
 class Qwen2Model(TextModel):
     model_arch = gguf.MODEL_ARCH.QWEN2
 
@@ -71,6 +73,7 @@ class Qwen2Model(TextModel):
 
 
 @ModelBase.register("Qwen2MoeForCausalLM")
+@ModelBase.example("Qwen/Qwen1.5-MoE-A2.7B")
 class Qwen2MoeModel(TextModel):
     model_arch = gguf.MODEL_ARCH.QWEN2MOE
 
@@ -153,6 +156,7 @@ class Qwen2MoeModel(TextModel):
 
 
 @ModelBase.register("Qwen3ForCausalLM", "Qwen3Model")
+@ModelBase.example("Qwen/Qwen3-8B")
 class Qwen3Model(Qwen2Model):
     model_arch = gguf.MODEL_ARCH.QWEN3
 
@@ -251,6 +255,7 @@ class Qwen3Model(Qwen2Model):
 
 
 @ModelBase.register("Qwen3MoeForCausalLM")
+@ModelBase.example("Qwen/Qwen3-30B-A3B")
 class Qwen3MoeModel(Qwen2MoeModel):
     model_arch = gguf.MODEL_ARCH.QWEN3MOE
 
@@ -362,6 +367,7 @@ class _QwenMtpMixin:
 
 
 @ModelBase.register("Qwen3NextForCausalLM")
+@ModelBase.example("Qwen/Qwen3-Next-80B-A3B-Instruct")
 class Qwen3NextModel(_QwenMtpMixin, Qwen2MoeModel):
     model_arch = gguf.MODEL_ARCH.QWEN3NEXT
 
@@ -421,6 +427,7 @@ class Qwen3NextModel(_QwenMtpMixin, Qwen2MoeModel):
 
 
 @ModelBase.register("RND1")
+@ModelBase.example("radicalnumerics/RND1-Base-0910")
 class RND1Model(Qwen2MoeModel):
     model_arch = gguf.MODEL_ARCH.RND1
 
@@ -620,16 +627,19 @@ class _Qwen35MRopeMixin:
 
 
 @ModelBase.register("Qwen3_5ForConditionalGeneration", "Qwen3_5ForCausalLM")
+@ModelBase.example("Qwen/Qwen3.5-9B")
 class Qwen3_5TextModel(_Qwen35MRopeMixin, _LinearAttentionVReorderBase):
     model_arch = gguf.MODEL_ARCH.QWEN35
 
 
 @ModelBase.register("Qwen3_5MoeForConditionalGeneration", "Qwen3_5MoeForCausalLM")
+@ModelBase.example("Qwen/Qwen3.5-35B-A3B")
 class Qwen3_5MoeTextModel(_Qwen35MRopeMixin, _LinearAttentionVReorderBase):
     model_arch = gguf.MODEL_ARCH.QWEN35MOE
 
 
 @ModelBase.register("DFlashDraftModel")
+@ModelBase.example("z-lab/Qwen3.5-9B-DFlash")
 class DFlashModel(Qwen3Model):
     model_arch = gguf.MODEL_ARCH.DFLASH
 
@@ -699,6 +709,7 @@ class DFlashModel(Qwen3Model):
 
 
 @ModelBase.register("Qwen3DSparkModel")
+@ModelBase.example("satgeze/Qwen3.6-27B-DSpark")
 class DSparkModel(DFlashModel):
     # DSpark = DFlash + a semi-autoregressive Markov head
     model_arch = gguf.MODEL_ARCH.DFLASH

conversion/qwen3tts.py

@@ -37,6 +37,7 @@ _ACT2FN = {
 
 
 @ModelBase.register("Qwen3TTSForConditionalGeneration")
+@ModelBase.example("Qwen/Qwen3-TTS-12Hz-1.7B-Base")
 class Qwen3TTSTalkerModel(TextModel):
     model_arch = gguf.MODEL_ARCH.QWEN3TTS
 
@@ -185,6 +186,7 @@ class Qwen3TTSTalkerModel(TextModel):
 
 
 @ModelBase.register("Qwen3TTSForConditionalGeneration")
+@ModelBase.example("Qwen/Qwen3-TTS-12Hz-1.7B-Base")
 class Qwen3TTSSpeakerEncoderModel(MmprojModel):
     has_vision_encoder = False
     has_audio_encoder = True

conversion/qwen3vl.py

@@ -14,6 +14,7 @@ from .qwenvl import Qwen25AudioModel
 
 
 @ModelBase.register("Qwen3VLForConditionalGeneration", "Qwen3VLMoeForConditionalGeneration", "Qwen3_5ForConditionalGeneration", "Qwen3_5MoeForConditionalGeneration")
+@ModelBase.example("Qwen/Qwen3-VL-4B-Instruct", "Qwen/Qwen3-VL-30B-A3B-Instruct", "Qwen/Qwen3.5-9B", "Qwen/Qwen3.5-35B-A3B")
 class Qwen3VLVisionModel(MmprojModel):
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
@@ -144,6 +145,7 @@ class Qwen3VLVisionModel(MmprojModel):
 
 
 @ModelBase.register("Qwen3OmniMoeForConditionalGeneration")
+@ModelBase.example("Qwen/Qwen3-Omni-30B-A3B-Instruct")
 class Qwen3OmniMmprojModel(Qwen3VLVisionModel, Qwen25AudioModel):
     has_audio_encoder = True
     has_vision_encoder = True
@@ -217,12 +219,14 @@ class Qwen3OmniMmprojModel(Qwen3VLVisionModel, Qwen25AudioModel):
 
 
 @ModelBase.register("Qwen3ASRForConditionalGeneration")
+@ModelBase.example("Qwen/Qwen3-ASR-0.6B-hf")
 class Qwen3ASRMmprojModel(Qwen3OmniMmprojModel):
     has_audio_encoder = True
     has_vision_encoder = False
 
 
 @ModelBase.register("Glm4vForConditionalGeneration", "Glm4vMoeForConditionalGeneration", "GlmOcrForConditionalGeneration")
+@ModelBase.example("zai-org/GLM-4.1V-9B-Thinking", "zai-org/GLM-4.5V")
 class Glm4VVisionModel(Qwen3VLVisionModel):
     def set_gguf_parameters(self):
         MmprojModel.set_gguf_parameters(self) # skip Qwen3VLVisionModel parameters
@@ -246,6 +250,7 @@ class Glm4VVisionModel(Qwen3VLVisionModel):
 
 
 @ModelBase.register("Qwen3VLForConditionalGeneration")
+@ModelBase.example("Qwen/Qwen3-VL-4B-Instruct")
 class Qwen3VLTextModel(Qwen3Model):
     model_arch = gguf.MODEL_ARCH.QWEN3VL
 
@@ -268,6 +273,7 @@ class Qwen3VLTextModel(Qwen3Model):
 
 
 @ModelBase.register("Qwen3VLMoeForConditionalGeneration")
+@ModelBase.example("Qwen/Qwen3-VL-30B-A3B-Instruct")
 class Qwen3VLMoeTextModel(Qwen3MoeModel):
     model_arch = gguf.MODEL_ARCH.QWEN3VLMOE
 
@@ -317,6 +323,7 @@ class Qwen3VLMoeTextModel(Qwen3MoeModel):
 
 
 @ModelBase.register("Qwen3OmniMoeForConditionalGeneration")
+@ModelBase.example("Qwen/Qwen3-Omni-30B-A3B-Instruct")
 class Qwen3OmniMoeTextModel(Qwen3VLMoeTextModel):
     model_arch = gguf.MODEL_ARCH.QWEN3VLMOE
 
@@ -338,6 +345,7 @@ class Qwen3OmniMoeTextModel(Qwen3VLMoeTextModel):
 
 
 @ModelBase.register("Qwen3ASRForConditionalGeneration")
+@ModelBase.example("Qwen/Qwen3-ASR-0.6B-hf")
 class Qwen3ASRTextModel(Qwen3VLTextModel):
     model_arch = gguf.MODEL_ARCH.QWEN3VL
 

conversion/qwenvl.py

@@ -17,6 +17,7 @@ from .base import MmprojModel, ModelBase, TextModel, gguf
     "Qwen2_5_VLForConditionalGeneration",
     "Qwen2_5OmniModel",
 )
+@ModelBase.example("Qwen/Qwen2-VL-2B-Instruct", "Qwen/Qwen2.5-VL-3B-Instruct")
 class Qwen2VLModel(TextModel):
     model_arch = gguf.MODEL_ARCH.QWEN2VL
 
@@ -40,6 +41,7 @@ class Qwen2VLModel(TextModel):
 
 
 @ModelBase.register("Qwen2VLModel", "Qwen2VLForConditionalGeneration", "Qwen2_5_VLForConditionalGeneration")
+@ModelBase.example("Qwen/Qwen2-VL-2B-Instruct", "Qwen/Qwen2.5-VL-3B-Instruct")
 class Qwen2VLVisionModel(MmprojModel):
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
@@ -161,6 +163,7 @@ class Qwen25AudioModel(MmprojModel):
 
 
 @ModelBase.register("Qwen2_5OmniModel")
+@ModelBase.example("Qwen/Qwen2.5-Omni-3B")
 class Qwen25OmniModel(Qwen2VLVisionModel, Qwen25AudioModel):
     has_audio_encoder = True
     has_vision_encoder = True

conversion/refact.py

@@ -9,6 +9,7 @@ from .base import ModelBase, TextModel, gguf
 
 
 @ModelBase.register("GPTRefactForCausalLM")
+@ModelBase.example("smallcloudai/Refact-1_6-base")
 class RefactModel(TextModel):
     model_arch = gguf.MODEL_ARCH.REFACT
 

conversion/rwkv.py

@@ -11,6 +11,7 @@ from .base import ModelBase, TextModel, gguf
 
 
 @ModelBase.register("Rwkv6ForCausalLM")
+@ModelBase.example("RWKV/v6-Finch-1B6-HF")
 class Rwkv6Model(TextModel):
     model_arch = gguf.MODEL_ARCH.RWKV6
 
@@ -83,6 +84,7 @@ class Rwkv6Model(TextModel):
 
 
 @ModelBase.register("RWKV6Qwen2ForCausalLM")
+@ModelBase.example("recursal/QRWKV6-32B-Instruct-Preview-v0.1")
 class RWKV6Qwen2Model(Rwkv6Model):
     model_arch = gguf.MODEL_ARCH.RWKV6QWEN2
 
@@ -136,6 +138,7 @@ class RWKV6Qwen2Model(Rwkv6Model):
 
 
 @ModelBase.register("Rwkv7ForCausalLM", "RWKV7ForCausalLM")
+@ModelBase.example("fla-hub/rwkv7-1.5B-world")
 class Rwkv7Model(TextModel):
     model_arch = gguf.MODEL_ARCH.RWKV7
 
@@ -261,6 +264,7 @@ class Rwkv7Model(TextModel):
 
 
 @ModelBase.register("RwkvHybridForCausalLM")
+@ModelBase.example("RWKV-Red-Team/ARWKV-7B-Preview-0.1")
 class ARwkv7Model(Rwkv7Model):
     model_arch = gguf.MODEL_ARCH.ARWKV7
 

conversion/sarashina2.py

@@ -12,6 +12,7 @@ from .qwenvl import Qwen2VLVisionModel
 
 
 @ModelBase.register("Sarashina2VisionForCausalLM")
+@ModelBase.example("sbintuitions/sarashina2.2-vision-3b")
 class Sarashina2VLTextModel(LlamaModel):
     model_arch = gguf.MODEL_ARCH.LLAMA
 
@@ -26,6 +27,7 @@ class Sarashina2VLTextModel(LlamaModel):
 
 
 @ModelBase.register("Sarashina2VisionForCausalLM")
+@ModelBase.example("sbintuitions/sarashina2.2-vision-3b")
 class Sarashina2VLVisionModel(Qwen2VLVisionModel):
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)

conversion/smallthinker.py

@@ -11,6 +11,7 @@ from .base import ModelBase, TextModel, gguf, logger
 
 
 @ModelBase.register("SmallThinkerForCausalLM")
+@ModelBase.example("PowerInfer/SmallThinker-4BA0.6B-Instruct")
 class SmallThinkerModel(TextModel):
     model_arch = gguf.MODEL_ARCH.SMALLTHINKER
 

conversion/smolvlm.py

@@ -9,6 +9,7 @@ from .base import MmprojModel, ModelBase, gguf
 
 
 @ModelBase.register("Idefics3ForConditionalGeneration", "SmolVLMForConditionalGeneration")
+@ModelBase.example("HuggingFaceTB/SmolVLM-Instruct", "HuggingFaceM4/Idefics3-8B-Llama3")
 class SmolVLMModel(MmprojModel):
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)

conversion/stablelm.py

@@ -11,6 +11,7 @@ from .base import ModelBase, TextModel, gguf
 
 
 @ModelBase.register("StableLmForCausalLM", "StableLMEpochForCausalLM", "LlavaStableLMEpochForCausalLM")
+@ModelBase.example("stabilityai/stablelm-2-1_6b")
 class StableLMModel(TextModel):
     model_arch = gguf.MODEL_ARCH.STABLELM
 

conversion/starcoder.py

@@ -4,6 +4,7 @@ from .base import ModelBase, TextModel, gguf
 
 
 @ModelBase.register("GPTBigCodeForCausalLM")
+@ModelBase.example("bigcode/gpt_bigcode-santacoder")
 class StarCoderModel(TextModel):
     model_arch = gguf.MODEL_ARCH.STARCODER
 
@@ -19,5 +20,6 @@ class StarCoderModel(TextModel):
 
 
 @ModelBase.register("Starcoder2ForCausalLM")
+@ModelBase.example("bigcode/starcoder2-3b")
 class StarCoder2Model(TextModel):
     model_arch = gguf.MODEL_ARCH.STARCODER2

conversion/step3.py

@@ -16,6 +16,7 @@ from .qwen import Qwen3Model
 
 
 @ModelBase.register("StepVLForConditionalGeneration", "Step3p7ForConditionalGeneration")
+@ModelBase.example("stepfun-ai/Step3-VL-10B", "stepfun-ai/Step-3.7-Flash")
 class Step3VLVisionModel(MmprojModel):
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
@@ -91,11 +92,13 @@ class Step3VLVisionModel(MmprojModel):
 
 
 @ModelBase.register("StepVLForConditionalGeneration")
+@ModelBase.example("stepfun-ai/Step3-VL-10B")
 class Step3VLTextModel(Qwen3Model):
     model_arch = gguf.MODEL_ARCH.QWEN3
 
 
 @ModelBase.register("Step3p5ForCausalLM", "Step3p7ForConditionalGeneration")
+@ModelBase.example("stepfun-ai/Step-3.7-Flash")
 class Step35Model(TextModel):
     model_arch = gguf.MODEL_ARCH.STEP35
     supports_mtp_export = True

conversion/t5.py

@@ -16,6 +16,7 @@ from .base import ModelBase, SentencePieceTokenTypes, TextModel, gguf, logger
 @ModelBase.register("MT5ForConditionalGeneration")
 @ModelBase.register("UMT5ForConditionalGeneration")
 @ModelBase.register("UMT5Model")
+@ModelBase.example("google-t5/t5-small", "google/flan-t5-small", "google/umt5-small")
 class T5Model(TextModel):
     model_arch = gguf.MODEL_ARCH.T5
 
@@ -153,6 +154,7 @@ class T5Model(TextModel):
 
 
 @ModelBase.register("T5EncoderModel")
+@ModelBase.example("sentence-transformers/sentence-t5-base")
 class T5EncoderModel(TextModel):
     model_arch = gguf.MODEL_ARCH.T5ENCODER
 

conversion/talkie.py

@@ -11,6 +11,7 @@ from .base import LazyTorchTensor, ModelBase, TextModel, gguf
 
 
 @ModelBase.register("TalkieForCausalLM")
+@ModelBase.example("lewtun/talkie-1930-13b-it-hf")
 class TalkieModel(TextModel):
     model_arch = gguf.MODEL_ARCH.TALKIE
 

conversion/ultravox.py

@@ -9,6 +9,7 @@ from .base import MmprojModel, ModelBase, TextModel, gguf
 
 
 @ModelBase.register("UltravoxModel")
+@ModelBase.example("fixie-ai/ultravox-v0_5-llama-3_2-1b")
 class UltravoxModel(TextModel):
     model_arch = gguf.MODEL_ARCH.LLAMA # dummy
 
@@ -18,6 +19,7 @@ class UltravoxModel(TextModel):
 
 
 @ModelBase.register("GlmasrModel")
+@ModelBase.example("zai-org/GLM-ASR-Nano-2512")
 class GlmASRWhisperEncoderModel(MmprojModel):
     has_vision_encoder = False
     has_audio_encoder = True
@@ -82,6 +84,7 @@ class GlmASRWhisperEncoderModel(MmprojModel):
 
 
 @ModelBase.register("Qwen2AudioForConditionalGeneration")
+@ModelBase.example("Qwen/Qwen2-Audio-7B-Instruct")
 class WhisperEncoderModel(MmprojModel):
     has_vision_encoder = False # no vision encoder
     has_audio_encoder = True
@@ -123,6 +126,7 @@ class WhisperEncoderModel(MmprojModel):
 
 
 @ModelBase.register("UltravoxModel")
+@ModelBase.example("fixie-ai/ultravox-v0_5-llama-3_2-1b")
 class UltravoxWhisperEncoderModel(WhisperEncoderModel):
     has_vision_encoder = False # no vision encoder
     has_audio_encoder = True
@@ -134,6 +138,7 @@ class UltravoxWhisperEncoderModel(WhisperEncoderModel):
 
 
 @ModelBase.register("MERaLiON2ForConditionalGeneration")
+@ModelBase.example("MERaLiON/MERaLiON-2-3B")
 class MERaLiONWhisperEncoderModel(WhisperEncoderModel):
     has_vision_encoder = False
     has_audio_encoder = True
@@ -180,6 +185,7 @@ class MERaLiONWhisperEncoderModel(WhisperEncoderModel):
 
 
 @ModelBase.register("VoxtralForConditionalGeneration")
+@ModelBase.example("mistralai/Voxtral-Mini-3B-2507")
 class VoxtralWhisperEncoderModel(WhisperEncoderModel):
     has_vision_encoder = False # no vision encoder
     has_audio_encoder = True
@@ -191,6 +197,7 @@ class VoxtralWhisperEncoderModel(WhisperEncoderModel):
 
 
 @ModelBase.register("AudioFlamingo3ForConditionalGeneration")
+@ModelBase.example("nvidia/audio-flamingo-3-hf")
 class AudioFlamingo3WhisperEncoderModel(WhisperEncoderModel):
     def set_gguf_parameters(self):
         super().set_gguf_parameters()

conversion/wavtokenizer.py

@@ -9,6 +9,7 @@ from .base import ModelBase, TextModel, gguf, logger
 
 
 @ModelBase.register("WavTokenizerDec")
+@ModelBase.example("novateur/WavTokenizer-large-speech-75token")
 class WavTokenizerDecModel(TextModel):
     model_arch = gguf.MODEL_ARCH.WAVTOKENIZER_DEC
 

conversion/xverse.py

@@ -11,6 +11,7 @@ from .base import ModelBase, TextModel, gguf
 
 
 @ModelBase.register("XverseForCausalLM")
+@ModelBase.example("xverse/XVERSE-7B")
 class XverseModel(TextModel):
     model_arch = gguf.MODEL_ARCH.XVERSE
 

conversion/youtuvl.py

@@ -9,6 +9,7 @@ from .base import MmprojModel, ModelBase, gguf, logger
 
 
 @ModelBase.register("YoutuVLForConditionalGeneration")
+@ModelBase.example("tencent/Youtu-VL-4B-Instruct")
 class YoutuVLVisionModel(MmprojModel):
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)

docs/development/HOWTO-add-model.md

@@ -29,6 +29,7 @@ The required steps to implement for an HF model are:
 
 ```python
 @ModelBase.register("MyModelForCausalLM")
+@ModelBase.example("user/model")
 class MyModel(TextModel):
     model_arch = gguf.MODEL_ARCH.MYMODEL
 ```
@@ -37,10 +38,13 @@ or
 
 ```python
 @ModelBase.register("MyModelForConditionalGeneration")
+@ModelBase.example("user/model")
 class MyModel(MmprojModel):
     model_arch = gguf.MODEL_ARCH.MYMODEL
 ```
 
+The `example` should point to a valid Hugging Face model that will be used for testing. You can add multiple models if necessary. Prefer a non-gated model, or tiny random weights if no such model exists.
+
 2. Define the layout of the GGUF tensors in [constants.py](/gguf-py/gguf/constants.py)
 
 Add an enum entry in `MODEL_ARCH`, the model human friendly name in `MODEL_ARCH_NAMES` and the GGUF tensor names in `MODEL_TENSORS`.

docs/release.md

@@ -29,6 +29,12 @@ identify which PRs require a version bump before cutting a release._
 Releases are created by running the [make-release](.github/workflows/make-release.yml)
 which is a manual workflow.
 
+The workflow runs against the branch selected in the "Run workflow" dialog
+(default `master`) and takes an optional `commit` SHA. When a commit is given,
+the workflow validates that the commit belongs to the branch and is not older
+than 3 days from the branch HEAD, then releases that commit instead of the
+branch HEAD.
+
 The workflow creates an annotated git tag (e.g. `v0.1.0`) and pushes it to the
 remote. No GitHub Release object is created, the tag is the release artifact.
 

gguf-py/gguf/constants.py

@@ -261,6 +261,7 @@ class Keys:
 
     class KDA:
         HEAD_DIM         = "{arch}.kda.head_dim"
+        SAFE_GATE        = "{arch}.kda.safe_gate"
         GATE_LOWER_BOUND = "{arch}.kda.gate_lower_bound"
 
     class WKV:
@@ -552,6 +553,7 @@ class MODEL_ARCH(IntEnum):
     PLM              = auto()
     BAILINGMOE       = auto()
     BAILINGMOE2      = auto()
+    BAILINGMOE3      = auto()
     DOTS1            = auto()
     ARCEE            = auto()
     AFMOE            = auto()
@@ -1267,6 +1269,7 @@ MODEL_ARCH_NAMES: dict[MODEL_ARCH, str] = {
     MODEL_ARCH.PLM:              "plm",
     MODEL_ARCH.BAILINGMOE:       "bailingmoe",
     MODEL_ARCH.BAILINGMOE2:      "bailingmoe2",
+    MODEL_ARCH.BAILINGMOE3:      "bailingmoe3",
     MODEL_ARCH.DOTS1:            "dots1",
     MODEL_ARCH.ARCEE:            "arcee",
     MODEL_ARCH.AFMOE:            "afmoe",
@@ -4234,6 +4237,50 @@ MODEL_TENSORS: dict[MODEL_ARCH, list[MODEL_TENSOR]] = {
         MODEL_TENSOR.NEXTN_SHARED_HEAD_NORM,
         MODEL_TENSOR.LAYER_OUT_NORM,
     ],
+    MODEL_ARCH.BAILINGMOE3: [
+        MODEL_TENSOR.TOKEN_EMBD,
+        MODEL_TENSOR.OUTPUT_NORM,
+        MODEL_TENSOR.OUTPUT,
+        MODEL_TENSOR.ATTN_NORM,
+        MODEL_TENSOR.ATTN_Q,
+        MODEL_TENSOR.ATTN_Q_A,
+        MODEL_TENSOR.ATTN_Q_B,
+        MODEL_TENSOR.ATTN_Q_A_NORM,
+        MODEL_TENSOR.ATTN_K,
+        MODEL_TENSOR.ATTN_V,
+        MODEL_TENSOR.ATTN_OUT,
+        MODEL_TENSOR.ATTN_GATE,
+        MODEL_TENSOR.ATTN_KV_A_MQA,
+        MODEL_TENSOR.ATTN_KV_B,
+        MODEL_TENSOR.ATTN_K_B,
+        MODEL_TENSOR.ATTN_V_B,
+        MODEL_TENSOR.ATTN_KV_A_NORM,
+        MODEL_TENSOR.FFN_NORM,
+        MODEL_TENSOR.FFN_GATE,
+        MODEL_TENSOR.FFN_DOWN,
+        MODEL_TENSOR.FFN_UP,
+        MODEL_TENSOR.FFN_GATE_INP,
+        MODEL_TENSOR.FFN_GATE_EXP,
+        MODEL_TENSOR.FFN_DOWN_EXP,
+        MODEL_TENSOR.FFN_UP_EXP,
+        MODEL_TENSOR.FFN_GATE_SHEXP,
+        MODEL_TENSOR.FFN_DOWN_SHEXP,
+        MODEL_TENSOR.FFN_UP_SHEXP,
+        MODEL_TENSOR.FFN_EXP_PROBS_B,
+        MODEL_TENSOR.SSM_CONV1D_Q,
+        MODEL_TENSOR.SSM_CONV1D_K,
+        MODEL_TENSOR.SSM_CONV1D_V,
+        MODEL_TENSOR.SSM_F_A,
+        MODEL_TENSOR.SSM_BETA,
+        MODEL_TENSOR.SSM_A,
+        MODEL_TENSOR.SSM_G_A,
+        MODEL_TENSOR.SSM_DT,
+        MODEL_TENSOR.SSM_NORM,
+        MODEL_TENSOR.NEXTN_EH_PROJ,
+        MODEL_TENSOR.NEXTN_ENORM,
+        MODEL_TENSOR.NEXTN_HNORM,
+        MODEL_TENSOR.LAYER_OUT_NORM,
+    ],
     MODEL_ARCH.DOTS1: [
         MODEL_TENSOR.TOKEN_EMBD,
         MODEL_TENSOR.OUTPUT_NORM,
@@ -5487,7 +5534,9 @@ KEY_SSM_GROUP_COUNT    = Keys.SSM.GROUP_COUNT
 KEY_SSM_DT_B_C_RMS     = Keys.SSM.DT_B_C_RMS
 
 # KDA
-KEY_KDA_HEAD_DIM       = Keys.KDA.HEAD_DIM
+KEY_KDA_HEAD_DIM         = Keys.KDA.HEAD_DIM
+KEY_KDA_SAFE_GATE        = Keys.KDA.SAFE_GATE
+KEY_KDA_GATE_LOWER_BOUND = Keys.KDA.GATE_LOWER_BOUND
 
 # tokenization
 KEY_TOKENIZER_MODEL      = Keys.Tokenizer.MODEL

gguf-py/gguf/gguf_writer.py

@@ -1103,9 +1103,6 @@ class GGUFWriter:
     def add_ssm_dt_b_c_rms(self, value: bool) -> None:
         self.add_bool(Keys.SSM.DT_B_C_RMS.format(arch=self.arch), value)
 
-    def add_kda_gate_lower_bound(self, value: float) -> None:
-        self.add_float32(Keys.KDA.GATE_LOWER_BOUND.format(arch=self.arch), value)
-
     def add_expert_latent_length(self, value: int) -> None:
         self.add_uint32(Keys.LLM.EXPERT_LATENT_LENGTH.format(arch=self.arch), value)
 
@@ -1121,6 +1118,12 @@ class GGUFWriter:
     def add_kda_head_dim(self, value: int) -> None:
         self.add_uint32(Keys.KDA.HEAD_DIM.format(arch=self.arch), value)
 
+    def add_kda_safe_gate(self, value: bool) -> None:
+        self.add_bool(Keys.KDA.SAFE_GATE.format(arch=self.arch), value)
+
+    def add_kda_gate_lower_bound(self, value: float) -> None:
+        self.add_float32(Keys.KDA.GATE_LOWER_BOUND.format(arch=self.arch), value)
+
     def add_tokenizer_model(self, model: str) -> None:
         self.add_string(Keys.Tokenizer.MODEL, model)
 

gguf-py/gguf/tensor_mapping.py

@@ -255,6 +255,7 @@ class TensorNameMap:
         # Attention query
         MODEL_TENSOR.ATTN_Q: (
             "model.layers.{bid}.self_attn.q_proj",                       # llama-hf nemotron olmoe olmo2 phimoe
+            "model.layers.{bid}.attention.q_proj",                       # bailingmoe3
             "layers.{bid}.self_attn.q_proj",                             # embeddinggemma
             "model.layers.{bid}.self_attn.q_proj_no_perm",               # llama-custom
             "layers.{bid}.attention.wq",                                 # llama-pth
@@ -275,6 +276,7 @@ class TensorNameMap:
         # Attention key
         MODEL_TENSOR.ATTN_K: (
             "model.layers.{bid}.self_attn.k_proj",                     # llama-hf nemotron olmoe olmo2 phimoe
+            "model.layers.{bid}.attention.k_proj",                     # bailingmoe3
             "layers.{bid}.self_attn.k_proj",                           # embeddinggemma
             "model.layers.{bid}.self_attn.k_proj_no_perm",             # llama-custom
             "layers.{bid}.attention.wk",                               # llama-pth
@@ -296,6 +298,7 @@ class TensorNameMap:
         # Attention value
         MODEL_TENSOR.ATTN_V: (
             "model.layers.{bid}.self_attn.v_proj",                       # llama-hf nemotron olmoe olmo2 phimoe
+            "model.layers.{bid}.attention.v_proj",                       # bailingmoe3
             "layers.{bid}.self_attn.v_proj",                             # embeddinggemma
             "layers.{bid}.attention.wv",                                 # llama-pth
             "encoder.layer.{bid}.attention.self.value",                  # bert
@@ -321,6 +324,8 @@ class TensorNameMap:
             "transformer.h.{bid}.self_attention.dense",                     # falcon
             "h.{bid}.self_attention.dense",                                 # bloom
             "model.layers.{bid}.self_attn.o_proj",                          # llama-hf nemotron olmoe olmo2 phimoe
+            "model.layers.{bid}.attention.o_proj",                          # bailingmoe3
+            "model.layers.{bid}.attention.dense",                           # bailingmoe3 MLA
             "layers.{bid}.self_attn.o_proj",                                # embeddinggemma
             "model.layers.{bid}.self_attn.out_proj",                        # lfm2 minimax-01
             "model.layers.{bid}.self_attn.linear_attn",                     # deci
@@ -834,6 +839,7 @@ class TensorNameMap:
             "model.layers.{bid}.linear_attn.dt_proj",   # qwen3next
             "backbone.layers.{bid}.mixer.dt",           # nemotron-h-moe
             "model.layers.{bid}.self_attn.dt_proj",     # kimi
+            "model.layers.{bid}.attention.dt_proj",     # bailingmoe3
         ),
 
         MODEL_TENSOR.SSM_DT_NORM: (
@@ -848,6 +854,7 @@ class TensorNameMap:
             "model.layers.layers.{bid}.mixer.A_log",  # plamo2
             "model.layers.{bid}.linear_attn.A_log",   # qwen3next
             "model.layers.{bid}.self_attn.A_log",     # kimi
+            "model.layers.{bid}.attention.A_log",     # bailingmoe3
         ),
 
         MODEL_TENSOR.SSM_B_NORM: (
@@ -874,6 +881,7 @@ class TensorNameMap:
             "model.layers.{bid}.linear_attn.norm",  # qwen3next
             "backbone.layers.{bid}.mixer.norm",     # mamba2
             "model.layers.{bid}.self_attn.o_norm",  # kimi
+            "model.layers.{bid}.attention.o_norm",  # bailingmoe3
         ),
 
         MODEL_TENSOR.SSM_OUT: (
@@ -895,12 +903,15 @@ class TensorNameMap:
         # Kimi Linear KDA (using SSM_ prefix for consistency)
         MODEL_TENSOR.SSM_CONV1D_Q: (
             "model.layers.{bid}.self_attn.q_conv1d",
+            "model.layers.{bid}.attention.q_conv1d",
         ),
         MODEL_TENSOR.SSM_CONV1D_K: (
             "model.layers.{bid}.self_attn.k_conv1d",
+            "model.layers.{bid}.attention.k_conv1d",
         ),
         MODEL_TENSOR.SSM_CONV1D_V: (
             "model.layers.{bid}.self_attn.v_conv1d",
+            "model.layers.{bid}.attention.v_conv1d",
         ),
         MODEL_TENSOR.SSM_F_A: (
             "model.layers.{bid}.self_attn.f_a_proj",
@@ -911,6 +922,7 @@ class TensorNameMap:
         MODEL_TENSOR.SSM_BETA: (
             "model.layers.{bid}.linear_attn.in_proj_b",  # qwen3.5
             "model.layers.{bid}.self_attn.b_proj",       # Kimi Linear
+            "model.layers.{bid}.attention.b_proj",       # bailingmoe3
         ),
         # Kimi K3 latent MoE: routed experts operate in a down-projected space
         MODEL_TENSOR.FFN_ROUTED_DOWN: (
@@ -1103,40 +1115,48 @@ class TensorNameMap:
 
         MODEL_TENSOR.ATTN_Q_A: (
             "model.layers.{bid}.self_attn.q_a_proj", # deepseek2
+            "model.layers.{bid}.attention.q_a_proj",  # bailingmoe3 (Ling-3.0-tiny)
             "layers.{bid}.attention.wq_a",           # mistral-large
         ),
 
         MODEL_TENSOR.ATTN_Q_B: (
             "model.layers.{bid}.self_attn.q_b_proj", # deepseek2
+            "model.layers.{bid}.attention.q_b_proj",  # bailingmoe3 (Ling-3.0-tiny)
             "layers.{bid}.attention.wq_b",           # mistral-large
         ),
 
         MODEL_TENSOR.ATTN_KV_A_MQA: (
             "model.layers.{bid}.self_attn.kv_a_proj_with_mqa", # deepseek2
+            "model.layers.{bid}.attention.kv_a_proj_with_mqa", # bailingmoe3
             "layers.{bid}.attention.wkv_a_with_mqa",           # mistral-large
         ),
 
         MODEL_TENSOR.ATTN_KV_B: (
             "model.layers.{bid}.self_attn.kv_b_proj", # deepseek2
+            "model.layers.{bid}.attention.kv_b_proj", # bailingmoe3
         ),
 
         MODEL_TENSOR.ATTN_K_B: (
             "model.layers.{bid}.self_attn.k_b_proj",  # deepseek2
+            "model.layers.{bid}.attention.k_b_proj",  # bailingmoe3
             "layers.{bid}.attention.k_b_proj",        # mistral-large
         ),
 
         MODEL_TENSOR.ATTN_V_B: (
             "model.layers.{bid}.self_attn.v_b_proj",  # deepseek2
+            "model.layers.{bid}.attention.v_b_proj",  # bailingmoe3
             "layers.{bid}.attention.v_b_proj",        # mistral-large
         ),
 
         MODEL_TENSOR.ATTN_Q_A_NORM: (
             "model.layers.{bid}.self_attn.q_a_layernorm", # deepseek2
+            "model.layers.{bid}.attention.q_a_layernorm", # bailingmoe3 (Ling-3.0-tiny)
             "layers.{bid}.attention.q_a_norm",            # mistral-large
         ),
 
         MODEL_TENSOR.ATTN_KV_A_NORM: (
             "model.layers.{bid}.self_attn.kv_a_layernorm", # deepseek2
+            "model.layers.{bid}.attention.kv_a_layernorm", # bailingmoe3
             "layers.{bid}.attention.kv_a_norm",            # mistral-large
         ),
 

scripts/make-release-checks.sh

@@ -4,7 +4,10 @@
 # Usage: make-release-checks.sh [--dry-run]
 #   --dry-run: warn on failures instead of aborting
 #
-# Env (when running in GitHub Actions): GH_TOKEN, GITHUB_REPOSITORY, GITHUB_OUTPUT
+# Env (when running in GitHub Actions):
+#   GH_TOKEN, GITHUB_REPOSITORY, GITHUB_OUTPUT
+#   RELEASE_BRANCH: when set, HEAD must belong to origin/RELEASE_BRANCH and must
+#     not be older than 3 days from the branch HEAD (skipped when unset)
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
@@ -28,6 +31,39 @@ if [[ -n "${GITHUB_OUTPUT:-}" ]]; then
     echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
 fi
 
+SHA=$(git rev-parse HEAD)
+
+echo "Checking that commit ${SHA} belongs to the release branch..."
+if [[ -z "${RELEASE_BRANCH:-}" ]]; then
+    echo "Warning: RELEASE_BRANCH not set - skipping commit check (local run)"
+else
+    TIP="origin/${RELEASE_BRANCH}"
+    COMMIT_ERR=""
+    if ! git rev-parse --verify "${TIP}" >/dev/null 2>&1; then
+        COMMIT_ERR="branch ${RELEASE_BRANCH} not found on remote"
+    elif ! git merge-base --is-ancestor "${SHA}" "${TIP}"; then
+        COMMIT_ERR="commit ${SHA} is not part of branch ${RELEASE_BRANCH}"
+    else
+        COMMIT_TS=$(git show -s --format=%ct "${SHA}")
+        TIP_TS=$(git show -s --format=%ct "${TIP}")
+        AGE_DAYS=$(( (TIP_TS - COMMIT_TS) / 86400 ))
+        if (( TIP_TS - COMMIT_TS > 3 * 86400 )); then
+            COMMIT_ERR="commit ${SHA} is ${AGE_DAYS} day(s) older than the HEAD of ${RELEASE_BRANCH} (max: 3)"
+        fi
+    fi
+    if [[ -n "${COMMIT_ERR}" ]]; then
+        if [[ "$DRY_RUN" == "true" ]]; then
+            echo "Warning: ${COMMIT_ERR} (dry run, continuing)."
+            CHECKS_PASSED=false
+        else
+            echo "Error: ${COMMIT_ERR}"
+            exit 1
+        fi
+    else
+        echo "Commit ${SHA} is on branch ${RELEASE_BRANCH} and within 3 days of its HEAD - OK"
+    fi
+fi
+
 echo "Checking that tag ${VERSION} does not already exist..."
 if git ls-remote --tags origin "${VERSION}" | grep -q "${VERSION}"; then
     echo "Error: tag ${VERSION} already exists on remote"
@@ -35,27 +71,6 @@ if git ls-remote --tags origin "${VERSION}" | grep -q "${VERSION}"; then
 fi
 echo "Tag ${VERSION} does not exist on remote - OK"
 
-SHA=$(git rev-parse HEAD)
-echo "Checking release.yml status for commit ${SHA}..."
-if [[ -z "${GITHUB_REPOSITORY:-}" ]]; then
-    echo "Warning: GITHUB_REPOSITORY not set - skipping CI check (local run)"
-else
-    RUNS=$(gh api "repos/${GITHUB_REPOSITORY}/actions/workflows/release.yml/runs" \
-        --jq "[.workflow_runs[] | select(.head_sha == \"${SHA}\" and .conclusion == \"success\")] | length")
-    if [[ "$RUNS" -eq 0 ]]; then
-        if [[ "$DRY_RUN" == "true" ]]; then
-            echo "Warning: no successful release.yml run found for HEAD (${SHA}) (dry run, continuing)."
-            CHECKS_PASSED=false
-        else
-            echo "Error: no successful release.yml run found for HEAD (${SHA})"
-            echo "The nightly build must complete successfully before making a release."
-            exit 1
-        fi
-    else
-        echo "Found successful release.yml run for HEAD."
-    fi
-fi
-
 MAJOR=$(grep "set(GGML_VERSION_MAJOR" "$REPO_ROOT/ggml/CMakeLists.txt" | grep -oP '\d+')
 MINOR=$(grep "set(GGML_VERSION_MINOR" "$REPO_ROOT/ggml/CMakeLists.txt" | grep -oP '\d+')
 PATCH=$(grep "set(GGML_VERSION_PATCH" "$REPO_ROOT/ggml/CMakeLists.txt" | grep -oP '\d+')

scripts/test_convert.py

@@ -0,0 +1,630 @@
+#!/usr/bin/env python3
+"""
+Build small test "slices" of the HF repos declared with @ModelBase.example().
+
+For each example repo, a reduced copy of the model is constructed without ever
+downloading the full weights, using HTTP range requests against the safetensors
+shards (the 8-byte length + JSON header of each shard tells us the exact byte
+span of every tensor):
+  1. keep only the first N transformer layers (per numeric "family" in tensor
+     names whose cardinality matches a layer count declared in config.json)
+  2. keep only the first E experts (per-expert tensors are dropped, stacked
+     expert tensors and router weights are row-sliced along dim 0)
+  3. keep only the first V rows of vocab-sized tensors (embeddings, lm_head)
+config.json is patched to match (layer/expert/vocab counts, per-layer lists are
+index-sliced). All other repo files are copied as-is, except a blacklist of
+files that are useless for conversion testing (alternate-format weights, media,
+demo assets, ...).
+
+Output layout: {output}/{user}--{model}/...
+
+Usage:
+    python scripts/test_convert.py --dry-run
+    python scripts/test_convert.py --repos "Qwen/*" --max-size 100M
+"""
+from __future__ import annotations
+
+import argparse
+import concurrent.futures as cf
+import fnmatch
+import json
+import logging
+import os
+import re
+import struct
+import sys
+import threading
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import requests
+from huggingface_hub import HfApi, get_token, hf_hub_url
+
+logging.basicConfig(level=logging.INFO, format="%(message)s")
+logger = logging.getLogger("test_convert")
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+
+INDEX_FILE = "model.safetensors.index.json"
+CONFIG_FILE = "config.json"
+
+# files not worth copying into a conversion-test slice
+AUX_BLACKLIST = [
+    # weights in other formats (the slice replaces them)
+    "*.bin", "*.pth", "*.pt", "*.ckpt", "*.h5", "*.msgpack",
+    "*.onnx", "*.tflite", "*.mlmodel", "*.mlpackage/*", "*.gguf", "*.nemo",
+    "onnx/*", "openvino/*", "coreml/*", "original/*", "metal/*",
+    # media / demo assets
+    "*.png", "*.jpg", "*.jpeg", "*.gif", "*.webp", "*.avif", "*.svg",
+    "*.mp4", "*.webm", "*.mov", "*.wav", "*.mp3", "*.flac", "*.ogg", "*.pdf",
+    ".gitattributes",
+]
+
+# per-file cap for aux files that are not on the blacklist (e.g. nested
+# safetensors weights of a sub-model); bigger files are skipped with a warning
+AUX_MAX_SIZE = 50 * 1024 * 1024
+
+LAYER_CONTAINERS = {"layers", "layer", "blocks", "block", "h"}
+EXPERT_ROW_KEYWORDS = ("expert", "router", "gate", "score")
+
+LAYER_KEYS = {
+    "num_hidden_layers", "num_layers", "n_layer", "n_layers", "num_layer",
+    "num_decoder_layers", "encoder_layers", "decoder_layers", "depth",
+    "num_encoder_layers", "num_attention_layers", "layer_count",
+}
+VOCAB_KEYS = {"vocab_size", "padded_vocab_size"}
+NEXTN_KEYS = {"num_nextn_predict_layers", "num_mtp_layers"}
+TOPK_SUBSTR = ("per_tok", "topk", "top_k", "moe_k")
+EXPERT_KEY_EXCLUDE = ("per_tok", "topk", "top_k", "shared", "group", "intermediate", "size", "dim", "dtype")
+
+
+def parse_size(text: str) -> int:
+    m = re.fullmatch(r"(\d+(?:\.\d+)?)\s*([kKmMgGtT]?)[bB]?", text.strip())
+    if not m:
+        raise argparse.ArgumentTypeError(f"invalid size: {text!r}")
+    mult = {"": 1, "k": 1024, "m": 1024**2, "g": 1024**3, "t": 1024**4}[m.group(2).lower()]
+    return int(float(m.group(1)) * mult)
+
+
+def human(n: int) -> str:
+    for unit in ("B", "KB", "MB", "GB"):
+        if n < 1024 or unit == "GB":
+            return f"{n:.1f}{unit}" if unit != "B" else f"{n}B"
+        n /= 1024
+    return f"{n}GB"
+
+
+def collect_examples() -> dict[str, list[str]]:
+    """Map example repo id -> sorted list of model class names using it."""
+    sys.path.insert(0, str(REPO_ROOT))
+    import conversion
+    conversion.load_all_models()
+    from conversion.base import ModelBase
+
+    repos: dict[str, set[str]] = {}
+    for classes in ModelBase._model_classes.values():
+        for modelcls in classes.values():
+            if "model_hf_examples" not in modelcls.__dict__:
+                continue
+            for repo in modelcls.model_hf_examples:
+                repos.setdefault(repo, set()).add(modelcls.__name__)
+    return {r: sorted(c) for r, c in sorted(repos.items())}
+
+
+# --------------------------------------------------------------------------------------
+# HTTP
+# --------------------------------------------------------------------------------------
+
+_tls = threading.local()
+
+
+def _session() -> requests.Session:
+    s = getattr(_tls, "s", None)
+    if s is None:
+        s = requests.Session()
+        _tls.s = s
+    return s
+
+
+class HubClient:
+    def __init__(self, repo_id: str, revision: str, token: str | None):
+        self.repo_id = repo_id
+        self.revision = revision
+        self.headers = {"Authorization": f"Bearer {token}"} if token else {}
+
+    def url(self, filename: str) -> str:
+        return hf_hub_url(self.repo_id, filename, revision=self.revision)
+
+    def _request(self, filename: str, headers: dict, stream: bool = False, retries: int = 5):
+        last: Exception | None = None
+        for attempt in range(1, retries + 1):
+            try:
+                r = _session().get(self.url(filename), headers=headers, stream=stream, timeout=90, allow_redirects=True)
+                if r.status_code in (429, 500, 502, 503, 504):
+                    raise requests.HTTPError(f"HTTP {r.status_code}", response=r)
+                r.raise_for_status()
+                return r
+            except Exception as e:  # noqa: BLE001
+                last = e
+                if attempt == retries or "404" in str(e) or "401" in str(e) or "403" in str(e):
+                    break
+                time.sleep(2.0 * attempt)
+        raise RuntimeError(f"{self.repo_id}/{filename}: {last}") from last
+
+    def get_range(self, filename: str, start: int, end_inclusive: int) -> bytes:
+        h = dict(self.headers)
+        h["Range"] = f"bytes={start}-{end_inclusive}"
+        return self._request(filename, h).content
+
+    def get_json(self, filename: str) -> Any:
+        return json.loads(self._request(filename, dict(self.headers)).content)
+
+    def download_file(self, filename: str, dest: Path):
+        r = self._request(filename, dict(self.headers), stream=True)
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        with open(dest, "wb") as f:
+            for chunk in r.iter_content(chunk_size=4 * 1024 * 1024):
+                if chunk:
+                    f.write(chunk)
+
+    def stream_range_into_fd(self, filename: str, start: int, end_inclusive: int, fd: int, write_offset: int):
+        h = dict(self.headers)
+        h["Range"] = f"bytes={start}-{end_inclusive}"
+        r = self._request(filename, h, stream=True)
+        pos = write_offset
+        for chunk in r.iter_content(chunk_size=8 * 1024 * 1024):
+            if chunk:
+                os.pwrite(fd, chunk, pos)
+                pos += len(chunk)
+        expected = end_inclusive - start + 1
+        if pos - write_offset != expected:
+            raise RuntimeError(f"short read: {filename} bytes={start}-{end_inclusive}")
+
+
+def fetch_shard_header(client: HubClient, filename: str) -> tuple[dict, int]:
+    (header_len,) = struct.unpack("<Q", client.get_range(filename, 0, 7))
+    header = json.loads(client.get_range(filename, 8, 8 + header_len - 1))
+    header.pop("__metadata__", None)
+    return header, 8 + header_len
+
+
+# --------------------------------------------------------------------------------------
+# config.json analysis / patching
+# --------------------------------------------------------------------------------------
+
+def walk_config(cfg: Any):
+    """Yield (container_dict, key, value) for every leaf in nested dicts."""
+    if isinstance(cfg, dict):
+        for k, v in cfg.items():
+            if isinstance(v, dict):
+                yield from walk_config(v)
+            else:
+                yield cfg, k, v
+
+
+@dataclass
+class ConfigInfo:
+    cfg: dict | None
+    layer_counts: set[int] = field(default_factory=set)
+    nextn_counts: set[int] = field(default_factory=set)
+    expert_counts: set[int] = field(default_factory=set)
+    vocab_sizes: set[int] = field(default_factory=set)
+    first_k_dense: int = 0
+
+
+def analyze_config(cfg: dict | None) -> ConfigInfo:
+    info = ConfigInfo(cfg=cfg)
+    if cfg is None:
+        return info
+    for _d, key, val in walk_config(cfg):
+        if not isinstance(val, int) or isinstance(val, bool) or val <= 0:
+            continue
+        if key in LAYER_KEYS:
+            info.layer_counts.add(val)
+        elif key in NEXTN_KEYS:
+            info.nextn_counts.add(val)
+        elif key in VOCAB_KEYS:
+            info.vocab_sizes.add(val)
+        elif key == "first_k_dense_replace":
+            info.first_k_dense = val
+        elif "expert" in key and val > 1 and not any(x in key for x in EXPERT_KEY_EXCLUDE):
+            info.expert_counts.add(val)
+    return info
+
+
+def patch_config(cfg: dict, families: dict[str, "Family"], new_vocab: int | None, orig_vocabs: set[int]) -> list[str]:
+    """Patch counts in-place to match the slice. Returns log lines."""
+    log = []
+    # map original cardinality -> family (for int patching and list slicing)
+    by_card: dict[int, Family] = {}
+    for fam in families.values():
+        if fam.kept is not None:
+            by_card.setdefault(fam.card, fam)
+            by_card.setdefault(fam.regular_total, fam)
+    max_new_experts = max((f.new_count for f in families.values() if f.kind == "expert" and f.kept is not None), default=None)
+
+    for d, key, val in list(walk_config(cfg)):
+        if isinstance(val, int) and not isinstance(val, bool):
+            fam = by_card.get(val)
+            if key in LAYER_KEYS and fam is not None and fam.kind == "layer":
+                d[key] = fam.new_regular
+                log.append(f"{key}: {val} -> {d[key]}")
+            elif key == "first_k_dense_replace" and fam is not None and val >= fam.new_regular:
+                d[key] = fam.new_regular - 1
+                log.append(f"{key}: {val} -> {d[key]}")
+            elif "expert" in key and fam is not None and fam.kind == "expert" and not any(x in key for x in EXPERT_KEY_EXCLUDE):
+                d[key] = fam.new_count
+                log.append(f"{key}: {val} -> {d[key]}")
+            elif "expert" in key and any(x in key for x in TOPK_SUBSTR) and max_new_experts is not None and val > max_new_experts:
+                d[key] = max_new_experts
+                log.append(f"{key}: {val} -> {d[key]}")
+            elif key in VOCAB_KEYS and new_vocab is not None and val in orig_vocabs:
+                d[key] = new_vocab
+                log.append(f"{key}: {val} -> {d[key]}")
+        elif isinstance(val, list) and val and all(not isinstance(x, (dict, list)) for x in val):
+            fam = by_card.get(len(val))
+            if fam is not None and fam.kind == "layer" and len(val) == fam.card:
+                d[key] = [val[i] for i in fam.kept]
+                log.append(f"{key}: list[{len(val)}] -> list[{len(d[key])}]")
+    return log
+
+
+# --------------------------------------------------------------------------------------
+# tensor name analysis
+# --------------------------------------------------------------------------------------
+
+@dataclass
+class Family:
+    """One numeric slot in tensor names, e.g. 'model.layers.#'."""
+    prefix: str
+    kind: str            # "layer" | "expert" | "other"
+    indices: set[int] = field(default_factory=set)
+    kept: list[int] | None = None    # None = keep all, no renumbering
+    renumber: dict[int, int] = field(default_factory=dict)
+    regular_total: int = 0           # layer count excluding MTP tail
+    new_regular: int = 0
+
+    @property
+    def card(self) -> int:
+        return len(self.indices)
+
+    @property
+    def new_count(self) -> int:
+        return len(self.kept) if self.kept is not None else self.card
+
+
+def name_slots(name: str):
+    """Yield (slot_pos, family_prefix, index) for each numeric path component."""
+    tokens = name.split(".")
+    norm: list[str] = []
+    for i, tok in enumerate(tokens):
+        if tok.isdigit():
+            yield i, ".".join(norm), int(tok)
+            norm.append("#")
+        else:
+            norm.append(tok)
+
+
+def build_families(names: list[str], cfg_info: ConfigInfo) -> dict[str, Family]:
+    families: dict[str, Family] = {}
+    for name in names:
+        for i, prefix, idx in name_slots(name):
+            tokens = name.split(".")
+            container = tokens[i - 1] if i > 0 else ""
+            fam = families.get(prefix)
+            if fam is None:
+                kind = "expert" if "expert" in container else "other"
+                fam = Family(prefix=prefix, kind=kind)
+                families[prefix] = fam
+            fam.indices.add(idx)
+
+    acceptable_layer_cards: dict[int, int] = {}  # card -> regular layer count
+    for c in cfg_info.layer_counts:
+        acceptable_layer_cards[c] = c
+        for m in cfg_info.nextn_counts:
+            acceptable_layer_cards[c + m] = c
+
+    for fam in families.values():
+        if fam.kind == "expert":
+            continue
+        container = fam.prefix.rsplit(".", 1)[-1] if "." in fam.prefix else fam.prefix
+        if cfg_info.cfg is not None:
+            if fam.card in acceptable_layer_cards:
+                fam.kind = "layer"
+                fam.regular_total = acceptable_layer_cards[fam.card]
+        elif fam.card >= 4 and container in LAYER_CONTAINERS:
+            fam.kind = "layer"
+            fam.regular_total = fam.card
+    return families
+
+
+def plan_families(families: dict[str, Family], num_layers: int, num_experts: int, first_k_dense: int):
+    for fam in families.values():
+        if fam.kind == "layer":
+            base = min(num_layers, fam.regular_total)
+            kept = list(range(base))
+            # keep one MoE layer for models whose first k layers are dense
+            if 0 < first_k_dense < fam.regular_total and first_k_dense >= base and base >= 1:
+                kept = list(range(base - 1)) + [first_k_dense]
+            # keep the MTP tail (layer indices beyond the regular count)
+            kept += [i for i in sorted(fam.indices) if i >= fam.regular_total]
+            fam.kept = sorted(kept)
+            fam.new_regular = base
+        elif fam.kind == "expert":
+            fam.kept = sorted(fam.indices)[:num_experts]
+            fam.new_regular = len(fam.kept)
+        else:
+            fam.kept = None
+            continue
+        fam.renumber = {old: new for new, old in enumerate(fam.kept)}
+
+
+def slice_tensor_name(name: str, families: dict[str, Family]) -> str | None:
+    """Return the renumbered output name, or None if the tensor is dropped."""
+    tokens = name.split(".")
+    for i, prefix, idx in name_slots(name):
+        fam = families[prefix]
+        if fam.kept is None:
+            continue
+        if idx not in fam.renumber:
+            return None
+        tokens[i] = str(fam.renumber[idx])
+    return ".".join(tokens)
+
+
+# --------------------------------------------------------------------------------------
+# per-repo slicing
+# --------------------------------------------------------------------------------------
+
+@dataclass
+class TensorPlan:
+    out_name: str
+    dtype: str
+    shape: list[int]
+    size: int
+    src_file: str
+    seg_start: int       # absolute byte range in src_file
+    seg_end: int         # inclusive
+
+
+@dataclass
+class RepoResult:
+    repo: str
+    status: str          # OK | DRY | TOO_BIG | NO_WEIGHTS | SKIPPED | ERROR
+    detail: str = ""
+    est_size: int = 0
+    params: str = ""
+
+
+def pick_weight_files(filenames: list[str]) -> tuple[list[str], bool]:
+    """Return (weight files, has_index). Preference: index -> model.safetensors -> any root safetensors."""
+    if INDEX_FILE in filenames:
+        return [], True
+    if "model.safetensors" in filenames:
+        return ["model.safetensors"], False
+    root_st = [f for f in filenames if f.endswith(".safetensors") and "/" not in f]
+    if len(root_st) >= 1:
+        # prefer consolidated.safetensors over arbitrary extra files
+        if "consolidated.safetensors" in root_st:
+            return ["consolidated.safetensors"], False
+        return root_st[:1], False
+    return [], False
+
+
+def row_slice(shape: list[int], size: int, keep_rows: int) -> tuple[list[int], int] | None:
+    if len(shape) < 1 or shape[0] <= keep_rows or size % shape[0] != 0:
+        return None
+    row_bytes = size // shape[0]
+    return [keep_rows] + shape[1:], keep_rows * row_bytes
+
+
+def slice_repo(repo: str, args, token: str | None, api: HfApi) -> RepoResult:
+    out_dir = Path(args.output) / repo.replace("/", "--")
+    meta_path = out_dir / ".slice_meta.json"
+    if meta_path.exists() and not args.force and not args.dry_run:
+        return RepoResult(repo, "SKIPPED", "already sliced (use --force to redo)")
+
+    info = api.model_info(repo, files_metadata=True)
+    client = HubClient(repo, info.sha or "main", token)
+    siblings = {s.rfilename: (s.size or 0) for s in info.siblings}
+    filenames = sorted(siblings)
+
+    weight_files, has_index = pick_weight_files(filenames)
+    weight_map: dict[str, str] = {}
+    if has_index:
+        index = client.get_json(INDEX_FILE)
+        weight_map = index["weight_map"]
+        weight_files = sorted(set(weight_map.values()))
+    elif not weight_files:
+        return RepoResult(repo, "NO_WEIGHTS", "no .safetensors found")
+
+    cfg = client.get_json(CONFIG_FILE) if CONFIG_FILE in filenames else None
+    cfg_info = analyze_config(cfg)
+
+    # fetch headers (all shards; names alone are not enough for row slicing)
+    headers: dict[str, tuple[dict, int]] = {}
+    with cf.ThreadPoolExecutor(max_workers=args.jobs) as ex:
+        for fname, hd in zip(weight_files, ex.map(lambda f: fetch_shard_header(client, f), weight_files)):
+            headers[fname] = hd
+    all_names = [n for fname in weight_files for n in headers[fname][0]]
+    src_file_of = weight_map if has_index else {n: weight_files[0] for n in all_names}
+
+    families = build_families(all_names, cfg_info)
+
+    # shrink ladder: try requested params first, then reduce until under --max-size
+    attempts = [(args.num_layers, args.num_experts, args.vocab_size)]
+    v = args.vocab_size
+    while v > 1024:
+        v //= 2
+        attempts.append((args.num_layers, args.num_experts, v))
+    attempts += [(args.num_layers, max(2, args.num_experts // 2), v), (1, 2, v)]
+
+    plans: list[TensorPlan] = []
+    est = 0
+    used = attempts[-1]
+    for num_layers, num_experts, vocab_size in attempts:
+        plan_families(families, num_layers, num_experts, cfg_info.first_k_dense)
+        plans, est = [], 0
+        for fname in weight_files:
+            header, data_start = headers[fname]
+            for name, meta in header.items():
+                out_name = slice_tensor_name(name, families)
+                if out_name is None:
+                    continue
+                start, end = meta["data_offsets"]
+                shape, size = list(meta["shape"]), end - start
+                new_rows = None
+                if any(shape[0] >= vs and shape[0] - vs <= 1024 for vs in cfg_info.vocab_sizes if shape) and shape[0] > vocab_size:
+                    new_rows = vocab_size
+                elif shape and shape[0] in cfg_info.expert_counts and shape[0] > num_experts \
+                        and any(k in name for k in EXPERT_ROW_KEYWORDS):
+                    new_rows = num_experts
+                if new_rows is not None:
+                    sliced = row_slice(shape, size, new_rows)
+                    if sliced is not None:
+                        shape, size = sliced
+                plans.append(TensorPlan(out_name, meta["dtype"], shape, size, src_file_of[name],
+                                        data_start + start, data_start + start + size - 1))
+                est += size
+        used = (num_layers, num_experts, vocab_size)
+        if est <= args.max_size:
+            break
+
+    params = f"layers={used[0]} experts={used[1]} vocab={used[2]}"
+    if est > args.max_size:
+        return RepoResult(repo, "TOO_BIG", f"best effort {human(est)} > {human(args.max_size)}", est, params)
+    if args.dry_run:
+        return RepoResult(repo, "DRY", f"{len(plans)}/{len(all_names)} tensors", est, params)
+
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    # write the single output shard
+    out_shard = weight_files[0] if not has_index and len(weight_files) == 1 else "model.safetensors"
+    header_out: dict[str, Any] = {}
+    offset = 0
+    for t in plans:
+        header_out[t.out_name] = {"dtype": t.dtype, "shape": t.shape, "data_offsets": [offset, offset + t.size]}
+        offset += t.size
+    header_out["__metadata__"] = {"format": "pt"}
+    hbytes = json.dumps(header_out, separators=(",", ":")).encode()
+    hbytes += b" " * ((-(len(hbytes) + 8)) % 8)
+    data_start = 8 + len(hbytes)
+
+    shard_path = out_dir / out_shard
+    with open(shard_path, "wb") as f:
+        f.write(struct.pack("<Q", len(hbytes)))
+        f.write(hbytes)
+        f.truncate(data_start + est)
+    fd = os.open(shard_path, os.O_WRONLY)
+    try:
+        offsets = {t.out_name: header_out[t.out_name]["data_offsets"][0] for t in plans}
+
+        def fetch(t: TensorPlan):
+            client.stream_range_into_fd(t.src_file, t.seg_start, t.seg_end, fd, data_start + offsets[t.out_name])
+
+        with cf.ThreadPoolExecutor(max_workers=args.jobs) as ex:
+            list(ex.map(fetch, plans))
+    finally:
+        os.close(fd)
+
+    # aux files
+    skipped_aux = []
+    for fname in filenames:
+        if fname in weight_files or fname == INDEX_FILE or fname.endswith(".safetensors"):
+            continue
+        if any(fnmatch.fnmatch(fname, p) or fnmatch.fnmatch(Path(fname).name, p) for p in AUX_BLACKLIST):
+            continue
+        if fname == CONFIG_FILE:
+            continue  # patched below
+        if siblings[fname] > AUX_MAX_SIZE:
+            skipped_aux.append(f"{fname} ({human(siblings[fname])})")
+            continue
+        client.download_file(fname, out_dir / fname)
+    for f in skipped_aux:
+        logger.warning(f"  {repo}: skipped large aux file {f}")
+
+    patch_log = []
+    if cfg is not None:
+        new_vocab = used[2] if any(vs > used[2] for vs in cfg_info.vocab_sizes) else None
+        patch_log = patch_config(cfg, families, new_vocab, cfg_info.vocab_sizes)
+        with open(out_dir / CONFIG_FILE, "w") as f:
+            json.dump(cfg, f, indent=2)
+            f.write("\n")
+
+    with open(meta_path, "w") as f:
+        json.dump({
+            "repo": repo, "revision": info.sha, "params": params,
+            "tensors": len(plans), "total_tensors": len(all_names),
+            "size": est, "config_patches": patch_log, "skipped_aux": skipped_aux,
+        }, f, indent=2)
+
+    return RepoResult(repo, "OK", f"{len(plans)}/{len(all_names)} tensors", est, params)
+
+
+# --------------------------------------------------------------------------------------
+# main
+# --------------------------------------------------------------------------------------
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("--output", type=Path, default=REPO_ROOT / "tmp" / "hf_slices")
+    ap.add_argument("--max-size", type=parse_size, default="100M",
+                    help="max total size of the sliced safetensors weight (default: 100M)")
+    ap.add_argument("--hf-token", default=None,
+                    help="HF token (default: HF_TOKEN env var or the token stored by 'hf auth login')")
+    ap.add_argument("--dry-run", action="store_true", help="plan and estimate sizes only, write nothing")
+    ap.add_argument("--repos", default=None,
+                    help="comma-separated globs/substrings to select a subset of example repos")
+    ap.add_argument("--num-layers", type=int, default=2)
+    ap.add_argument("--num-experts", type=int, default=8)
+    ap.add_argument("--vocab-size", type=int, default=4096)
+    ap.add_argument("--jobs", type=int, default=8, help="concurrent HTTP requests per repo")
+    ap.add_argument("--force", action="store_true", help="re-slice repos that already have an output dir")
+    args = ap.parse_args()
+
+    token = args.hf_token or get_token()
+    if not token:
+        logger.warning("no HF token found, you may hit rate limits (set HF_TOKEN or run 'hf auth login')")
+
+    examples = collect_examples()
+    if args.repos:
+        pats = [p.strip() for p in args.repos.split(",") if p.strip()]
+        examples = {r: c for r, c in examples.items()
+                    if any(fnmatch.fnmatch(r.lower(), p.lower()) or p.lower() in r.lower() for p in pats)}
+    logger.info(f"{len(examples)} example repo(s) to process\n")
+
+    api = HfApi(token=token)
+    results: list[RepoResult] = []
+    for i, (repo, classes) in enumerate(examples.items(), 1):
+        logger.info(f"[{i}/{len(examples)}] {repo} ({', '.join(classes)})")
+        try:
+            res = slice_repo(repo, args, token, api)
+        except Exception as e:  # noqa: BLE001
+            res = RepoResult(repo, "ERROR", str(e)[:200])
+        results.append(res)
+        extra = f" [{res.params}]" if res.params else ""
+        logger.info(f"    {res.status}: {res.detail} {human(res.est_size) if res.est_size else ''}{extra}")
+
+    logger.info("\n=== summary ===")
+    counts: dict[str, int] = {}
+    for res in results:
+        counts[res.status] = counts.get(res.status, 0) + 1
+    for status in ("OK", "DRY", "SKIPPED", "TOO_BIG", "NO_WEIGHTS", "ERROR"):
+        if counts.get(status):
+            logger.info(f"{status}: {counts[status]}")
+    for res in results:
+        if res.status in ("TOO_BIG", "NO_WEIGHTS", "ERROR"):
+            logger.info(f"  {res.status} {res.repo}: {res.detail}")
+
+    if not args.dry_run:
+        args.output.mkdir(parents=True, exist_ok=True)
+        with open(args.output / "report.json", "w") as f:
+            json.dump([res.__dict__ for res in results], f, indent=2)
+
+    return 1 if counts.get("ERROR") else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

src/llama-arch.cpp

@@ -107,6 +107,7 @@ static const std::map<llm_arch, const char *> LLM_ARCH_NAMES = {
     { LLM_ARCH_PLM,              "plm"              },
     { LLM_ARCH_BAILINGMOE,       "bailingmoe"       },
     { LLM_ARCH_BAILINGMOE2,      "bailingmoe2"      },
+    { LLM_ARCH_BAILINGMOE3,      "bailingmoe3"      },
     { LLM_ARCH_DOTS1,            "dots1"            },
     { LLM_ARCH_ARCEE,            "arcee"            },
     { LLM_ARCH_AFMOE,            "afmoe"            },
@@ -317,7 +318,8 @@ static const std::map<llm_kv, const char *> LLM_KV_NAMES = {
     { LLM_KV_SSM_GROUP_COUNT,    "%s.ssm.group_count"    },
     { LLM_KV_SSM_DT_B_C_RMS,     "%s.ssm.dt_b_c_rms"     },
 
-    { LLM_KV_KDA_HEAD_DIM, "%s.kda.head_dim" },
+    { LLM_KV_KDA_HEAD_DIM,         "%s.kda.head_dim"         },
+    { LLM_KV_KDA_SAFE_GATE,        "%s.kda.safe_gate"        },
     { LLM_KV_KDA_GATE_LOWER_BOUND, "%s.kda.gate_lower_bound" },
 
     { LLM_KV_WKV_HEAD_SIZE, "%s.wkv.head_size" },
@@ -996,6 +998,7 @@ bool llm_arch_is_hybrid(const llm_arch & arch) {
         case LLM_ARCH_NEMOTRON_H_MOE:
         case LLM_ARCH_QWEN3NEXT:
         case LLM_ARCH_KIMI_LINEAR:
+        case LLM_ARCH_BAILINGMOE3:
         case LLM_ARCH_KIMI_K3:
         case LLM_ARCH_QWEN35:
         case LLM_ARCH_QWEN35MOE:
@@ -1061,6 +1064,7 @@ bool llm_arch_supports_sm_tensor(const llm_arch & arch) {
         case LLM_ARCH_MINIMAX_M3:
         case LLM_ARCH_MISTRAL4:
         case LLM_ARCH_KIMI_LINEAR:
+        case LLM_ARCH_BAILINGMOE3:
         case LLM_ARCH_KIMI_K3:
         case LLM_ARCH_QWEN3TTS:
             return false;

src/llama-arch.h

@@ -112,6 +112,7 @@ enum llm_arch {
     LLM_ARCH_PLM,
     LLM_ARCH_BAILINGMOE,
     LLM_ARCH_BAILINGMOE2,
+    LLM_ARCH_BAILINGMOE3,
     LLM_ARCH_DOTS1,
     LLM_ARCH_ARCEE,
     LLM_ARCH_AFMOE,
@@ -323,6 +324,7 @@ enum llm_kv {
     LLM_KV_SSM_DT_B_C_RMS,
 
     LLM_KV_KDA_HEAD_DIM,
+    LLM_KV_KDA_SAFE_GATE,
     LLM_KV_KDA_GATE_LOWER_BOUND,
 
     LLM_KV_WKV_HEAD_SIZE,

src/llama-context.cpp

@@ -2298,6 +2298,7 @@ uint32_t llama_context::graph_max_nodes(uint32_t n_tokens) const {
         res = std::max<uint32_t>(n_tokens * 160, 64u * model.n_tensors());
     } else if (model.arch == LLM_ARCH_QWEN3NEXT ||
         model.arch == LLM_ARCH_KIMI_LINEAR ||
+        model.arch == LLM_ARCH_BAILINGMOE3 ||
         model.arch == LLM_ARCH_QWEN35 ||
         model.arch == LLM_ARCH_QWEN35MOE ||
         model.arch == LLM_ARCH_DEEPSEEK4 ||