Initial release of AutoRound + ASHQ1 suite

00_SAFETENSORS-to-AutoRound-BF16-GGUF.py

@@ -0,0 +1,1109 @@
+#!/usr/bin/env python
+r"""00_SAFETENSORS-to-AutoRound-BF16-GGUF.py — Universal AutoRound-infused GGUF builder.
+
+Handles both:
+	1. Raw unquantized BF16 safetensors (runs AutoRound optimization, then builds GGUF)
+	2. Pre-AutoRounded safetensors (dequantizes streaming to BF16, then builds GGUF)
+
+Always produces:
+	model-BF16.gguf        — full model, MTP head included when present
+	model-no-mtp-BF16.gguf — trunk for imatrix (split via 00b when MTP present)
+	mtp-BF16.gguf          — standalone speculative draft (if MTP present)
+	mmproj-BF16.gguf       — vision projector (if multimodal)
+Every GGUF gets a .provenance.json sidecar recording its AutoRound lineage.
+
+Usage:
+	python 00_SAFETENSORS-to-AutoRound-BF16-GGUF.py                 # processes .\safetensors\
+	python 00_SAFETENSORS-to-AutoRound-BF16-GGUF.py <folder_path>  # drag-and-drop
+"""
+import argparse,json,os,re,shutil,subprocess,sys,time,urllib.request
+if os.name=="nt":os.environ.setdefault("KMP_AFFINITY","disabled")
+os.environ.setdefault("PYTORCH_CUDA_ALLOC_CONF","expandable_segments:True")
+import torch
+from safetensors.torch import load_file,save_file
+from safetensors import safe_open
+
+SCRIPT_DIR=os.path.dirname(os.path.abspath(__file__))
+LLAMA_CPP=os.path.join(SCRIPT_DIR,"llama-cpp")
+CONVERTER=os.path.join(LLAMA_CPP,"convert_hf_to_gguf.py")
+EXTRACTOR=os.path.join(SCRIPT_DIR,"00b_BF16-GGUF-MTP-extract.py")
+if not os.path.isfile(EXTRACTOR):
+	EXTRACTOR=os.path.join(SCRIPT_DIR,"00a_gguf-mtp-extract.py")
+CALIB_SCRIPT=os.path.join(SCRIPT_DIR,"01_create-calibration-dataset.py")
+if not os.path.isfile(CALIB_SCRIPT):
+	CALIB_SCRIPT=os.path.join(SCRIPT_DIR,"01_create-calibration-dataset-and-imatrix.py")
+CALIB_DIR=os.path.join(SCRIPT_DIR,"01_create-calibration-dataset-and-imatrix")
+DEFAULT_CALIB_NAME="bartowski-imatrix-v5-semantic.txt"
+DEFAULT_CALIB_JSONL_NAME="bartowski-imatrix-v5-semantic.jsonl"
+DEFAULT_CALIB_TXT=os.path.join(CALIB_DIR,DEFAULT_CALIB_NAME)
+DEFAULT_CALIB_JSONL=os.path.join(CALIB_DIR,DEFAULT_CALIB_JSONL_NAME)
+DEFAULT_CALIB_TXT_URL="https://huggingface.co/datasets/lemon07r/bartowski-imatrix-v5-semantic/resolve/main/bartowski-imatrix-v5-semantic.txt"
+DEFAULT_CALIB_JSONL_URL="https://huggingface.co/datasets/lemon07r/bartowski-imatrix-v5-semantic/resolve/main/bartowski-imatrix-v5-semantic.jsonl"
+DEFAULT_EXP_DATASET=os.path.join(CALIB_DIR,"experimental.txt")
+_SIGLIP_NORM=[0.5,0.5,0.5]
+LLAMA_CPP_REPO="https://github.com/ggml-org/llama.cpp.git"
+
+# Per-architecture batch profiles: looped/compact architectures saturate at bs>=2
+ARCH_BS_OVERRIDE={"nanbeige":{"bs":2,"min_vram":6,"max_gb":8}}
+
+def _has_mod(name):
+	try:__import__(name);return True
+	except ImportError:return False
+
+def _torch_whl_index():
+	ver=getattr(getattr(torch,"version",None),"cuda",None)
+	if not ver:return None
+	parts=str(ver).split(".")
+	if len(parts)<2:return None
+	return f"https://download.pytorch.org/whl/cu{parts[0]}{parts[1]}"
+
+def ensure_pkg(pip_name,import_name=None,extra_args=None):
+	mod=import_name or pip_name.replace("-","_")
+	if _has_mod(mod):return True
+	print(f"\n[Setup] Installing missing package: {pip_name} …")
+	cmd=[sys.executable,"-m","pip","install","-U",pip_name]
+	if extra_args:cmd+=extra_args
+	if subprocess.run(cmd).returncode!=0:
+		print(f"  ✗ pip install {pip_name} failed.")
+		return False
+	return _has_mod(mod)
+
+def ensure_torchvision():
+	if _has_mod("torchvision"):return True
+	if ensure_pkg("torchvision"):return True
+	idx=_torch_whl_index()
+	if idx:
+		print(f"  Retrying torchvision from {idx} …")
+		if ensure_pkg("torchvision",extra_args=["--index-url",idx]):return True
+	print("  ✗ torchvision is required for Qwen3.5 AutoProcessor.")
+	return False
+
+def ensure_python_deps():
+	ok=ensure_pkg("auto-round","auto_round")
+	ok=ensure_torchvision() and ok
+	return ok
+
+def ensure_llama_cpp():
+	if os.path.isfile(CONVERTER):return True
+	print(f"\n[Setup] llama.cpp converter missing — installing into {LLAMA_CPP}")
+	if shutil.which("git") is None:
+		print("  ✗ git is not on PATH. Install Git for Windows, then retry.")
+		return False
+	git_dir=os.path.join(LLAMA_CPP,".git")
+	if os.path.isdir(git_dir):
+		print("  Updating existing llama.cpp clone …")
+		rc=subprocess.run(["git","-C",LLAMA_CPP,"pull","--ff-only"]).returncode
+	elif os.path.isdir(LLAMA_CPP) and os.listdir(LLAMA_CPP):
+		print(f"  ✗ {LLAMA_CPP} exists without convert_hf_to_gguf.py and without a git repo.")
+		return False
+	else:
+		rc=subprocess.run(["git","clone","--depth","1",LLAMA_CPP_REPO,LLAMA_CPP]).returncode
+	if rc!=0 or not os.path.isfile(CONVERTER):
+		print("  ✗ Unable to obtain convert_hf_to_gguf.py")
+		return False
+	req=os.path.join(LLAMA_CPP,"requirements.txt")
+	if os.path.isfile(req):
+		print("  Installing llama.cpp Python requirements …")
+		subprocess.run([sys.executable,"-m","pip","install","-q","-r",req])
+	print(f"  ✓ llama.cpp ready: {CONVERTER}")
+	return True
+
+def read_json(path):
+	if not os.path.isfile(path):return None
+	with open(path,"r",encoding="utf-8") as f:return json.load(f)
+
+def read_safetensors_header(path):
+	import struct
+	with open(path,"rb") as f:
+		hlen=struct.unpack("<Q",f.read(8))[0]
+		return json.loads(f.read(hlen).decode("utf-8"))
+
+_ROPE_RULES=(
+	(re.compile(r'if\s+(self\.config\.rope_scaling)\s+is\s+None\s*:'),
+		lambda m:f'if not {m.group(1)} or ({m.group(1)}.get("type") or {m.group(1)}.get("rope_type") or "default")=="default":'),
+	(re.compile(r'if\s+(self\.config\.rope_scaling)\s+is\s+not\s+None\s*:'),
+		lambda m:f'if {m.group(1)} and ({m.group(1)}.get("type") or {m.group(1)}.get("rope_type") or "default")!="default":'),
+	(re.compile(r'([A-Za-z_][\w\.]*rope_scaling)\["type"\]'),
+		lambda m:f'{m.group(1)}.get("type",{m.group(1)}.get("rope_type","default"))'),
+	(re.compile(r'([A-Za-z_][\w\.]*rope_scaling)\["factor"\]'),
+		lambda m:f'{m.group(1)}.get("factor",1.0)'),
+	# Recent transformers expects mapping {key: source}; remote code declared a list
+	(re.compile(r'_tied_weights_keys\s*=\s*\[[^\]]*\]'),
+		lambda m:'_tied_weights_keys={}'),
+)
+
+def _clear_dynamic_module_cache(st_dir):
+	base=os.path.basename(os.path.abspath(st_dir).rstrip("\\/"))
+	sanitized=base.replace(".","_dot_").replace("-","_hyphen_")
+	root=os.environ.get("HF_MODULES_CACHE") or os.path.join(os.path.expanduser("~"),".cache","huggingface","modules")
+	root=os.path.join(root,"transformers_modules")
+	if os.path.isdir(root):
+		for name in os.listdir(root):
+			if name in(base,sanitized) or base.lower() in name.lower():
+				shutil.rmtree(os.path.join(root,name),ignore_errors=True)
+	for mod in [m for m in list(sys.modules) if "transformers_modules" in m]:
+		sys.modules.pop(mod,None)
+
+def patch_remote_code_compat(st_dir):
+	# Match transformers rope_scaling default dict to remote code guard
+	patched=[]
+	for fn in sorted(os.listdir(st_dir)):
+		if not fn.endswith(".py"):continue
+		p=os.path.join(st_dir,fn)
+		try:
+			with open(p,"r",encoding="utf-8") as f:src=f.read()
+		except Exception:continue
+		new=src;n=0
+		for rx,fix in _ROPE_RULES:
+			new,c=rx.subn(fix,new)
+			n+=c
+		if n:
+			bak=p+".bak-00"
+			if not os.path.exists(bak):shutil.copy2(p,bak)
+			with open(p,"w",encoding="utf-8",newline="\n") as f:f.write(new)
+			patched.append(f"{fn}×{n}")
+	if patched:
+		_clear_dynamic_module_cache(st_dir)
+		print(f"  ℹ  Remote code compat (rope_scaling): {', '.join(patched)}")
+	return bool(patched)
+
+def normalize_rope_config(st_dir):
+	p=os.path.join(st_dir,"config.json")
+	cfg=read_json(p)
+	if not isinstance(cfg,dict):return False
+	changed=[]
+	holders=[cfg]
+	if isinstance(cfg.get("text_config"),dict):holders.append(cfg["text_config"])
+	for holder in holders:
+		rs=holder.get("rope_scaling")
+		if not isinstance(rs,dict):continue
+		rtype=rs.get("type") or rs.get("rope_type")
+		if rtype in(None,"default"):
+			holder["rope_scaling"]=None
+			changed.append("rope_scaling=null (default)")
+		elif "type" not in rs:
+			rs["type"]=rtype
+			changed.append(f'rope_scaling.type="{rtype}"')
+		if rtype not in(None,"default","linear","dynamic"):
+			print(f'  ℹ  rope_scaling detected: {json.dumps(rs)}')
+	if changed:
+		bak=p+".bak-00"
+		if not os.path.exists(bak):shutil.copy2(p,bak)
+		with open(p,"w",encoding="utf-8") as f:json.dump(cfg,f,indent=2)
+		print(f"  ℹ  config.json normalized: {', '.join(changed)}")
+	return bool(changed)
+
+def _scan_for_arch(arch):
+	roots=[CONVERTER,os.path.join(LLAMA_CPP,"conversion"),os.path.join(LLAMA_CPP,"gguf-py","gguf")]
+	for r in roots:
+		if os.path.isfile(r):files=[r]
+		elif os.path.isdir(r):files=[os.path.join(dp,f) for dp,_,fs in os.walk(r) for f in fs if f.endswith(".py")]
+		else:continue
+		for f in files:
+			try:
+				with open(f,"r",encoding="utf-8",errors="ignore") as fh:
+					if arch in fh.read():return True
+			except Exception:pass
+	return False
+
+def ensure_arch_support(arch):
+	if not arch or arch=="?" or _scan_for_arch(arch):return True
+	print(f"\n[Setup] {arch} missing from llama.cpp — updating repository …")
+	if os.path.isdir(os.path.join(LLAMA_CPP,".git")):
+		subprocess.run(["git","-C",LLAMA_CPP,"pull","--ff-only"])
+	if _scan_for_arch(arch):
+		print(f"  ✓ {arch} supported after update")
+		return True
+	print(f"  ⚠ {arch} missing from master — support in review (llama.cpp PR #25994).")
+	print(f'  PR branch: git -C "{LLAMA_CPP}" fetch origin pull/25994/head:nanbeige && git -C "{LLAMA_CPP}" checkout nanbeige')
+	return False
+
+_MTP_PROJ_HINT=("eh_proj",".fc.","pre_fc_norm","enorm","hnorm","embed_proj")
+
+def _is_mtp_key(k):
+	return k.startswith("mtp.") or "nextn." in k
+
+def _has_mtp_projector(keys):
+	# Distinguishes complete MTP fusion head from bare attention blocks
+	return any(any(h in k for h in _MTP_PROJ_HINT) for k in keys if _is_mtp_key(k))
+
+def _find_mtp_sidecar(st_dir):
+	cands=sorted(f for f in os.listdir(st_dir) if f.startswith("model-mtp") and f.endswith(".safetensors"))
+	if not cands:
+		for f in sorted(os.listdir(st_dir)):
+			if not f.endswith(".safetensors"):continue
+			try:hdr=read_safetensors_header(os.path.join(st_dir,f))
+			except Exception:continue
+			keys=[k for k in hdr if k!="__metadata__"]
+			if keys and all(_is_mtp_key(k) for k in keys):cands.append(f)
+	if not cands:return None
+	for f in cands:
+		if "restored" in f.lower():return os.path.join(st_dir,f)
+	return os.path.join(st_dir,cands[0])
+
+def _dir_has_weights(st_dir):
+	return os.path.isdir(st_dir) and any(f.endswith(".safetensors") for f in os.listdir(st_dir))
+
+def _iter_st_headers(st_dir):
+	idx=read_json(os.path.join(st_dir,"model.safetensors.index.json"))
+	names=sorted(set((idx or {}).get("weight_map",{}).values()))
+	if not names:
+		names=sorted(f for f in os.listdir(st_dir) if f.endswith(".safetensors"))
+	for fn in names:
+		p=fn if os.path.isabs(fn) else os.path.join(st_dir,fn)
+		if not os.path.isfile(p):continue
+		try:yield fn,read_safetensors_header(p)
+		except Exception:continue
+
+def _dir_looks_quantized(st_dir):
+	if not os.path.isdir(st_dir):return False
+	for _,hdr in _iter_st_headers(st_dir):
+		if any(k.endswith((".qweight",".scales",".qzeros")) for k in hdr if k!="__metadata__"):
+			return True
+	return False
+
+def _resolve_export_dir(path):
+	if not os.path.isdir(path):return path
+	if os.path.isfile(os.path.join(path,"config.json")) or _dir_has_weights(path):
+		return path
+	for name in sorted(os.listdir(path)):
+		sub=os.path.join(path,name)
+		if os.path.isdir(sub) and(os.path.isfile(os.path.join(sub,"config.json")) or _dir_has_weights(sub)):
+			return sub
+	return path
+
+def _guess_source_dir(work_dir):
+	for suf in("_AutoRound_W4A16","_dequant_bf16"):
+		if work_dir.endswith(suf):
+			cand=work_dir[:-len(suf)]
+			if os.path.isdir(cand):return cand
+	return None
+
+def _ensure_export_sidecars(src_dir,dst_dir):
+	if not src_dir or not os.path.isdir(src_dir) or not os.path.isdir(dst_dir):return
+	copied=[]
+	for fn in os.listdir(src_dir):
+		if fn.endswith((".safetensors",".bin")) or fn=="model.safetensors.index.json":continue
+		low=fn.lower()
+		if not(low.endswith((".json",".model",".tiktoken",".txt",".py")) or "tokenizer" in low):continue
+		src,dst=os.path.join(src_dir,fn),os.path.join(dst_dir,fn)
+		if os.path.isfile(src) and not os.path.isfile(dst):
+			shutil.copy2(src,dst);copied.append(fn)
+	cfg_p=os.path.join(dst_dir,"config.json")
+	cfg=read_json(cfg_p)
+	qstandalone=read_json(os.path.join(dst_dir,"quantization_config.json"))
+	if isinstance(cfg,dict) and not cfg.get("quantization_config") and(_dir_looks_quantized(dst_dir) or qstandalone):
+		cfg["quantization_config"]=qstandalone or {"quant_method":"auto-round","bits":4,"group_size":128,"sym":True,"format":"auto_round"}
+		with open(cfg_p,"w",encoding="utf-8") as f:json.dump(cfg,f,indent=2)
+		copied.append("quantization_config")
+	if copied:
+		print(f"  ℹ  Restored export sidecars in {os.path.basename(dst_dir)}: {', '.join(copied)}")
+
+def _export_mtime(path):
+	best=0.0
+	try:entries=os.listdir(path)
+	except OSError:return 0.0
+	for fn in entries:
+		if not fn.endswith(".safetensors"):continue
+		try:best=max(best,os.path.getmtime(os.path.join(path,fn)))
+		except OSError:pass
+	return best
+
+def _autoround_name_hit(base,name):
+	low=name.lower()
+	pref=base.lower()
+	if low==pref:return False
+	if "dequant" in low:return False
+	if not(low.startswith(pref) or pref in low):return False
+	return any(tag in low for tag in("-w4g128","_w4g128","-w4a16","_autoround","-auto_round","autoround_w4"))
+
+def find_autoround_export(st_dir,explicit=None):
+	cands=[]
+	if explicit:
+		p=os.path.abspath(explicit)
+		cands.append(_resolve_export_dir(p) if os.path.isdir(p) else p)
+	base=os.path.basename(st_dir.rstrip("\\/"))
+	fixed=[
+		os.path.join(SCRIPT_DIR,f"{base}_AutoRound_W4A16"),
+		os.path.join(SCRIPT_DIR,f"{base}-w4g128"),
+		os.path.join(SCRIPT_DIR,f"{base}-W4A16"),
+		os.path.join(os.path.dirname(st_dir),f"{base}-w4g128"),
+	]
+	try:names=os.listdir(SCRIPT_DIR)
+	except OSError:names=[]
+	for n in names:
+		if _autoround_name_hit(base,n):
+			fixed.append(os.path.join(SCRIPT_DIR,n))
+	seen=set()
+	for p in fixed:
+		p=_resolve_export_dir(p)
+		if p in seen or not os.path.isdir(p):continue
+		seen.add(p)
+		cands.append(p)
+	best=None
+	best_score=-1.0
+	for p in cands:
+		if not _dir_has_weights(p):continue
+		score=_export_mtime(p)
+		if _dir_looks_quantized(p):score+=1e15
+		if score>best_score:
+			best,best_score=p,score
+	return best
+
+def detect_model(st_dir):
+	cfg=read_json(os.path.join(st_dir,"config.json"))
+	if not cfg:
+		if not _dir_has_weights(st_dir):return None
+		cfg={"architectures":["?"],"model_type":"?"}
+	idx=read_json(os.path.join(st_dir,"model.safetensors.index.json"))
+	qcfg=cfg.get("quantization_config",{})
+	info={
+		"arch":cfg.get("architectures",["?"])[0],
+		"type":cfg.get("model_type","?"),
+		"multimodal":"vision_config" in cfg or "audio_config" in cfg,
+		"mtp":False,
+		"mtp_declared":False,
+		"mtp_complete":False,
+		"mtp_in_index":False,
+		"mtp_shard":None,
+		"mtp_standalone":False,
+		"mtp_file":None,
+		"quantized":bool(qcfg),
+		"quant_method":qcfg.get("quant_method",qcfg.get("format","?")),
+		"quant_format":qcfg.get("format",qcfg.get("bits","?")),
+		"bits":qcfg.get("bits",qcfg.get("weight_bits",4)),
+		"group_size":qcfg.get("group_size",128),
+		"sym":qcfg.get("sym",True),
+		"shards":[],
+		"total_params":None,
+		"source_dir":st_dir,
+		"config":cfg,
+	}
+	text_cfg=cfg.get("text_config") if isinstance(cfg.get("text_config"),dict) else {}
+	if text_cfg.get("mtp_num_hidden_layers",0)>0 or cfg.get("mtp_num_hidden_layers",0)>0:
+		info["mtp_declared"]=True
+	if idx:
+		wm=idx.get("weight_map",{})
+		info["shards"]=sorted(set(wm.values()))
+		tp=idx.get("metadata",{}).get("total_parameters")
+		if isinstance(tp,(int,float)) and tp>1e8:
+			info["total_params"]=int(tp)
+		mtp_keys=[k for k in wm if _is_mtp_key(k)]
+		if mtp_keys:
+			info["mtp_declared"]=True
+			info["mtp_in_index"]=True
+			info["mtp_shard"]=wm[mtp_keys[0]]
+		if _has_mtp_projector(wm):
+			info["mtp_complete"]=True
+		if any("visual" in k or "vision" in k for k in wm):
+			info["multimodal"]=True
+	if not info["total_params"]:
+		info["total_params"]=_estimate_params(cfg)
+	if not info["total_params"]:
+		st_bytes=sum(os.path.getsize(os.path.join(st_dir,f)) for f in os.listdir(st_dir) if f.endswith(".safetensors"))
+		if st_bytes>0:info["total_params"]=st_bytes//2
+	sidecar=_find_mtp_sidecar(st_dir)
+	if sidecar:
+		hdr_keys=[k for k in read_safetensors_header(sidecar) if k!="__metadata__"]
+		info["mtp_file"]=os.path.basename(sidecar)
+		info["mtp_declared"]=True
+		if _has_mtp_projector(hdr_keys):
+			info["mtp_complete"]=True
+			if not info["mtp_in_index"]:
+				info["mtp_standalone"]=True
+	info["mtp"]=info["mtp_declared"] and info["mtp_complete"]
+	if not info["quantized"] and _dir_looks_quantized(st_dir):
+		info["quantized"]=True
+		info["quant_method"]="auto-round" if info["quant_method"]=="?" else info["quant_method"]
+		info["quant_format"]="auto_round" if info["quant_format"]=="?" else info["quant_format"]
+		info["bits"]=int(info.get("bits") or 4)
+		info["group_size"]=int(info.get("group_size") or 128)
+	return info
+
+def unpack_gptq_autoround(qweight,scales,qzeros,g_idx,bits=4,group_size=128,sym=True):
+	dev=qweight.device
+	pf=32 // bits
+	in_feat=qweight.shape[0]*pf
+	out_feat=qweight.shape[1]
+	shifts=torch.arange(0,32,bits,device=dev,dtype=torch.int32)
+	qw=qweight.to(torch.int32)
+	q_unp=(qw.unsqueeze(1) >> shifts.view(1,pf,1)) & ((1 << bits)-1)
+	q_unp=q_unp.view(in_feat,out_feat).to(torch.float32)
+	if qzeros is not None and qzeros.numel()>0:
+		if qzeros.dtype in(torch.int32,torch.int64):
+			qz=qzeros.to(torch.int32)
+			z_unp=(qz.unsqueeze(2) >> shifts.view(1,1,pf)) & ((1 << bits)-1)
+			z_unp=z_unp.view(qz.shape[0],-1)[:,:out_feat].to(torch.float32)
+			z_unp=z_unp+1
+		else:
+			z_unp=qzeros.to(torch.float32)
+	else:
+		z_unp=torch.full((scales.shape[0],out_feat),2**(bits-1) if sym else 0.0,device=dev,dtype=torch.float32)
+	ng=scales.shape[0]
+	calc_gs=in_feat // ng if ng>0 else group_size
+	gs=group_size if group_size>0 else calc_gs
+	if g_idx is not None and g_idx.numel()>0 and not torch.all(g_idx==torch.arange(in_feat,device=dev) // gs):
+		scale_map=scales[g_idx].to(torch.float32)
+		zero_map=z_unp[g_idx].to(torch.float32)
+	else:
+		scale_map=scales.to(torch.float32).repeat_interleave(gs,dim=0)[:in_feat,:]
+		zero_map=z_unp.repeat_interleave(gs,dim=0)[:in_feat,:]
+	w=(q_unp-zero_map)*scale_map
+	return w.t().contiguous().to(torch.bfloat16)
+
+def unpack_awq(qweight,scales,qzeros,bits=4,group_size=128):
+	dev=qweight.device
+	pf=32 // bits
+	in_feat=qweight.shape[0]
+	out_feat=qweight.shape[1]*pf
+	shifts=torch.arange(0,32,bits,device=dev,dtype=torch.int32)
+	qw=qweight.to(torch.int32)
+	q_unp=(qw.unsqueeze(2) >> shifts.view(1,1,pf)) & ((1 << bits)-1)
+	q_unp=q_unp.view(in_feat,out_feat).to(torch.float32)
+	if qzeros is not None and qzeros.numel()>0:
+		qz=qzeros.to(torch.int32)
+		z_unp=(qz.unsqueeze(2) >> shifts.view(1,1,pf)) & ((1 << bits)-1)
+		z_unp=z_unp.view(qz.shape[0],-1).to(torch.float32)
+	else:
+		z_unp=torch.full((scales.shape[0],out_feat),0.0,device=dev,dtype=torch.float32)
+	ng=scales.shape[0]
+	gs=group_size if group_size>0 else(in_feat // ng if ng>0 else 128)
+	scale_map=scales.to(torch.float32).repeat_interleave(gs,dim=0)[:in_feat,:]
+	zero_map=z_unp.repeat_interleave(gs,dim=0)[:in_feat,:]
+	w=(q_unp-zero_map)*scale_map
+	return w.t().contiguous().to(torch.bfloat16)
+
+def dequantize_shard(shard_path,info):
+	tensors=load_file(shard_path,device="cpu")
+	out_tensors={}
+	consumed=set()
+	int4_keys=set()
+	bits=int(info.get("bits",4))
+	group_size=int(info.get("group_size",128))
+	sym=bool(info.get("sym",True))
+	qmethod=str(info.get("quant_method","")).lower()
+	for k,t in tensors.items():
+		if k in consumed:continue
+		if k.endswith(".qweight"):
+			base=k[:-8]
+			int4_keys.add(base)
+			qw=t
+			scales=tensors.get(f"{base}.scales",tensors.get(f"{base}.scale"))
+			qzeros=tensors.get(f"{base}.qzeros",tensors.get(f"{base}.zeros"))
+			g_idx=tensors.get(f"{base}.g_idx")
+			consumed.update([k,f"{base}.scales",f"{base}.scale",f"{base}.qzeros",f"{base}.zeros",f"{base}.g_idx"])
+			if scales is not None:
+				if "awq" in qmethod:
+					out_tensors[f"{base}.weight"]=unpack_awq(qw,scales,qzeros,bits,group_size)
+				else:
+					out_tensors[f"{base}.weight"]=unpack_gptq_autoround(qw,scales,qzeros,g_idx,bits,group_size,sym)
+			else:
+				out_tensors[k]=t
+		elif k.endswith(".weight") and(f"{k[:-7]}.scales" in tensors or f"{k[:-7]}.scale" in tensors):
+			base=k[:-7]
+			qw=t
+			scales=tensors.get(f"{base}.scales",tensors.get(f"{base}.scale"))
+			qzeros=tensors.get(f"{base}.qzeros",tensors.get(f"{base}.zeros"))
+			g_idx=tensors.get(f"{base}.g_idx")
+			consumed.update([k,f"{base}.scales",f"{base}.scale",f"{base}.qzeros",f"{base}.zeros",f"{base}.g_idx"])
+			if qw.dtype in(torch.int32,torch.int64,torch.int8,torch.uint8):
+				int4_keys.add(base)
+				out_tensors[f"{base}.weight"]=unpack_gptq_autoround(qw,scales,qzeros,g_idx,bits,group_size,sym)
+			else:
+				out_tensors[f"{base}.weight"]=qw.to(torch.bfloat16)
+		elif k.endswith(".weight") and f"{k[:-7]}.weight_scale_inv" in tensors:
+			base=k[:-7]
+			inv=tensors[f"{base}.weight_scale_inv"].to(torch.float32)
+			consumed.update([k,f"{base}.weight_scale_inv"])
+			out_tensors[f"{base}.weight"]=(t.to(torch.float32)*inv).to(torch.bfloat16)
+		else:
+			out_tensors[k]=t.to(torch.bfloat16) if t.dtype==torch.float16 else t
+	return out_tensors,int4_keys
+
+def dequantize_model_to_dir(st_dir,out_dir,info):
+	os.makedirs(out_dir,exist_ok=True)
+	print(f"\n[Dequant] Streaming AutoRound ({info['quant_method']}/{info['bits']}bit) → BF16 safetensors")
+	st_files=sorted(f for f in os.listdir(st_dir) if f.endswith(".safetensors"))
+	idx_path=os.path.join(st_dir,"model.safetensors.index.json")
+	new_weight_map={}
+	int4_keys=set()
+	for i,fn in enumerate(st_files,1):
+		src_p=os.path.join(st_dir,fn)
+		dst_p=os.path.join(out_dir,fn)
+		print(f"  [{i}/{len(st_files)}] Dequantizing shard: {fn} …")
+		unpacked,shard_int4=dequantize_shard(src_p,info)
+		int4_keys|=shard_int4
+		save_file(unpacked,dst_p,metadata={"format":"pt"})
+		for k in unpacked:new_weight_map[k]=fn
+	for fn in os.listdir(st_dir):
+		src=os.path.join(st_dir,fn)
+		dst=os.path.join(out_dir,fn)
+		if fn.endswith(".json") and fn!="model.safetensors.index.json":
+			cfg_data=read_json(src)
+			if fn=="config.json" and isinstance(cfg_data,dict):
+				cfg_data.pop("quantization_config",None)
+			with open(dst,"w",encoding="utf-8") as f:json.dump(cfg_data,f,indent=2)
+		elif fn.endswith((".model",".tiktoken",".txt",".py",".jinja")):
+			shutil.copy2(src,dst)
+	if os.path.isfile(idx_path):
+		orig_idx=read_json(idx_path)
+		orig_idx["weight_map"]=new_weight_map
+		with open(os.path.join(out_dir,"model.safetensors.index.json"),"w",encoding="utf-8") as f:
+			json.dump(orig_idx,f,indent=2)
+	if int4_keys:
+		layers=set();subs=set();globals_=[]
+		for k in sorted(int4_keys):
+			m=re.search(r"\.layers\.(\d+)\.(.+)$",k)
+			if m:
+				layers.add(int(m.group(1)));subs.add(m.group(2))
+			else:
+				globals_.append(k)
+		info["int4_layers"]=sorted(layers)
+		info["int4_submodules"]=sorted(subs)
+		if globals_:info["int4_globals"]=globals_
+		print(f"  ℹ  Source int4: {len(layers)} layer(s), {len(subs)} submodule(s)"+(f", {len(globals_)} global tensor(s)" if globals_ else ""))
+	print(f"  ✓ Reconstructed pristine BF16 model in: {out_dir}\n")
+	return out_dir
+
+def _estimate_params(cfg):
+	if not isinstance(cfg,dict):return None
+	c=cfg.get("text_config") if isinstance(cfg.get("text_config"),dict) else cfg
+	h=c.get("hidden_size") or cfg.get("hidden_size")
+	L=c.get("num_hidden_layers") or c.get("num_layers") or cfg.get("num_hidden_layers")
+	V=c.get("vocab_size") or cfg.get("vocab_size") or 152064
+	if not(h and L):return None
+	inter=c.get("intermediate_size") or cfg.get("intermediate_size") or 4*h
+	num_heads=c.get("num_attention_heads") or cfg.get("num_attention_heads") or 1
+	head=c.get("head_dim") or cfg.get("head_dim") or h//max(num_heads,1)
+	kv_heads=c.get("num_key_value_heads") or cfg.get("num_key_value_heads") or num_heads
+	kv=head*kv_heads
+	attn=2*h*h+2*h*kv
+	moe=c.get("num_experts") or c.get("n_routed_experts") or cfg.get("num_experts") or 0
+	mlp=3*h*inter*(moe if moe else 1)
+	return L*(attn+mlp)+V*h*(1 if(c.get("tie_word_embeddings") or cfg.get("tie_word_embeddings")) else 2)
+
+def _fast_path_ready():
+	return _has_mod("fla") and _has_mod("causal_conv1d")
+
+def _hybrid_linear_attn(cfg):
+	if not isinstance(cfg,dict):return False
+	blob=json.dumps(cfg).lower()
+	return any(t in blob for t in("linear_attention","gated_delta","linear_attn","mamba"))
+
+def auto_tune_profile(info,device,vram):
+	p=(info or {}).get("total_params") or _estimate_params((info or {}).get("config") or {})
+	b=(p or 8e9)/1e9
+	if device=="cpu":iters=max(20,min(50,int(200/max(b,1))))
+	else:iters=50
+	return iters,p
+
+def _autoround_device():
+	if torch.cuda.is_available():return "cuda"
+	xpu=getattr(torch,"xpu",None)
+	if xpu is not None and xpu.is_available():return "xpu"
+	return "cpu"
+
+def _download_file(url,dest):
+	os.makedirs(os.path.dirname(dest) or ".",exist_ok=True)
+	print(f"  [DL] {os.path.basename(dest)}")
+	urllib.request.urlretrieve(url,dest)
+	print(f"  [DONE] {os.path.basename(dest)} ({os.path.getsize(dest)/1024/1024:.2f} MB)")
+
+def _load_jsonl_texts(path):
+	out=[]
+	with open(path,"r",encoding="utf-8",errors="replace") as f:
+		for line in f:
+			line=line.strip()
+			if not line:continue
+			try:obj=json.loads(line)
+			except Exception:out.append(line);continue
+			if isinstance(obj,str):out.append(obj)
+			elif isinstance(obj,dict):
+				t=obj.get("text") or obj.get("content") or ""
+				if t:out.append(t)
+	return out
+
+def _load_txt_texts(path):
+	with open(path,"r",encoding="utf-8",errors="replace") as f:text=f.read()
+	if "‗" in text:
+		return [b.strip() for b in re.split(r"\n(?=‗user‗)",text) if len(b.strip())>80]
+	samples=[]
+	for p in re.split(r"\n{2,}",text):
+		p=p.strip()
+		if not p:continue
+		if len(p)>50000 and p.count("\n")>100:
+			samples.extend(ln.strip() for ln in p.splitlines() if len(ln.strip())>=200)
+		elif len(p)>=200:
+			samples.append(p)
+	if not samples:
+		samples=[ln.strip() for ln in text.splitlines() if len(ln.strip())>=200]
+	return samples
+
+def _load_calib_texts(path):
+	low=path.lower()
+	if low.endswith(".json") and not low.endswith(".jsonl"):
+		data=read_json(path)
+		if isinstance(data,list):
+			out=[]
+			for obj in data:
+				if isinstance(obj,str) and obj.strip():out.append(obj)
+				elif isinstance(obj,dict):
+					t=obj.get("text") or obj.get("content") or ""
+					if t:out.append(t)
+			return out
+		if isinstance(data,dict):
+			t=data.get("text") or data.get("content") or ""
+			return [t] if t else []
+	if low.endswith(".jsonl"):
+		return _load_jsonl_texts(path)
+	return _load_txt_texts(path)
+
+def _stable_chunk(tokenizer,ids,seqlen):
+	# Enforce round-trip token count stability against edge BPE merges
+	for _ in range(4):
+		text=tokenizer.decode(ids,skip_special_tokens=False)
+		back=tokenizer(text,add_special_tokens=False,truncation=False)["input_ids"]
+		if back and isinstance(back[0],list):back=back[0]
+		n=len(back)
+		if n==seqlen:return text
+		if n<seqlen:return None
+		ids=back[:seqlen]
+	return None
+
+def _pack_texts(tokenizer,texts,seqlen,nsamples):
+	chunks=[]
+	buf=[]
+	dropped=0
+	stride=max(seqlen//8,1)
+	for t in texts:
+		if not t:continue
+		ids=tokenizer(t,add_special_tokens=False,truncation=False)["input_ids"]
+		if ids and isinstance(ids[0],list):ids=ids[0]
+		buf.extend(ids)
+		while len(buf)>=seqlen+stride:
+			text=_stable_chunk(tokenizer,buf[:seqlen+stride],seqlen)
+			buf=buf[seqlen:]
+			if text is None:
+				dropped+=1
+				continue
+			chunks.append(text)
+			if len(chunks)>=nsamples:
+				_report_packing(len(chunks),dropped,nsamples)
+				return chunks
+	_report_packing(len(chunks),dropped,nsamples)
+	return chunks
+
+def _report_packing(kept,dropped,nsamples):
+	if dropped:print(f"  ℹ  {dropped} block(s) dropped (unstable round-trip length)")
+	if kept<nsamples:
+		print(f"  ⚠ {kept}/{nsamples} samples only — degraded calibration.")
+		print("    Expand corpus (--dataset) or reduce --seqlen to densify blocks.")
+	if dropped>kept:
+		print("  ⚠ Tokenizer rewrites more blocks than kept: unstable BPE round-trip.")
+		print("    A seqlen multiple of 512 stabilizes merge boundaries.")
+
+def resolve_autoround_dataset(tokenizer,experimental=False,dataset_path=None,seqlen=2048,nsamples=128):
+	path=label=None
+	if dataset_path:
+		cand=os.path.abspath(dataset_path)
+		if os.path.isfile(cand):
+			path,label=cand,os.path.basename(cand)
+		else:
+			print(f"  ✗ Custom dataset not found: {cand}")
+	if path is None and experimental:
+		if not os.path.isfile(DEFAULT_EXP_DATASET) and os.path.isfile(CALIB_SCRIPT):
+			print("\n[Prep] Building experimental.txt (same flag as 01 --experimental) …")
+			subprocess.run([sys.executable,CALIB_SCRIPT,"--dataset-only","--experimental"],cwd=SCRIPT_DIR)
+		if os.path.isfile(DEFAULT_EXP_DATASET):
+			path,label=DEFAULT_EXP_DATASET,"experimental.txt"
+	if path is None:
+		if not os.path.isfile(DEFAULT_CALIB_JSONL):
+			try:_download_file(DEFAULT_CALIB_JSONL_URL,DEFAULT_CALIB_JSONL)
+			except Exception as e:print(f"  [WARN] JSONL download failed: {e}")
+		if not os.path.isfile(DEFAULT_CALIB_TXT):
+			try:_download_file(DEFAULT_CALIB_TXT_URL,DEFAULT_CALIB_TXT)
+			except Exception as e:print(f"  [WARN] TXT download failed: {e}")
+		if os.path.isfile(DEFAULT_CALIB_JSONL):
+			path,label=DEFAULT_CALIB_JSONL,DEFAULT_CALIB_JSONL_NAME
+		elif os.path.isfile(DEFAULT_CALIB_TXT):
+			path,label=DEFAULT_CALIB_TXT,DEFAULT_CALIB_NAME
+	if path:
+		packed=_pack_texts(tokenizer,_load_calib_texts(path),seqlen,nsamples)
+		if packed:
+			print(f"  Calib: {label} → {len(packed)} packed samples × {seqlen} tokens")
+			return packed
+		print(f"  [WARN] {label} produced no seqlen-sized chunks")
+	print("  Fallback: NeelNanda/pile-10k:concat=True")
+	return "NeelNanda/pile-10k:concat=True"
+
+def run_autoround_tune(st_dir,out_dir,iters=None,experimental=False,dataset_path=None,info=None,bs_override=None,seqlen_override=None):
+	if not ensure_python_deps():
+		raise SystemExit(1)
+	ensure_preprocessor_config(st_dir)
+	normalize_rope_config(st_dir)
+	patch_remote_code_compat(st_dir)
+	from auto_round import AutoRound
+	from transformers import AutoTokenizer
+	try:tokenizer=AutoTokenizer.from_pretrained(st_dir,trust_remote_code=True)
+	except Exception:tokenizer=AutoTokenizer.from_pretrained(st_dir,use_fast=False,trust_remote_code=True)
+	if torch.cuda.is_available():
+		device="cuda"
+		vram=torch.cuda.get_device_properties(0).total_memory/(1024**3)
+		gpu_name=torch.cuda.get_device_name(0)
+		os.environ.setdefault("PYTORCH_CUDA_ALLOC_CONF","expandable_segments:True")
+	else:
+		xpu=getattr(torch,"xpu",None)
+		device="xpu" if xpu is not None and xpu.is_available() else "cpu"
+		vram=0.0
+		gpu_name="-"
+	if iters is None or iters<=0:
+		iters,est=auto_tune_profile(info,device,vram)
+	else:
+		est=(info or {}).get("total_params") or _estimate_params((info or {}).get("config") or {})
+	if not est or est<1e8:
+		st_bytes=sum(os.path.getsize(os.path.join(st_dir,f)) for f in os.listdir(st_dir) if f.endswith(".safetensors"))
+		est=(st_bytes//2) if st_bytes>0 else 8e9
+	gb=est/1e9
+	hybrid=_hybrid_linear_attn((info or {}).get("config"))
+	fast_ok=_fast_path_ready()
+	print(f"  Auto profile: ~{gb:.2f}B params, {device} {vram:.1f} GiB → iters={iters}")
+	if device=="cuda" and gb>16:print("  ⚠ >16B on 8 GB: long tuning duration; --skip-tune with an existing export is recommended.")
+	print(f"\n[AutoRound] Optimizing raw BF16 weights ({iters} iters, W4A16) …")
+	# Maintain effective batch budget bs*acc=8; higher bs amortizes kernel launch overhead
+	if device=="cpu":
+		bs,acc,seqlen,nsamples=1,4,2048,128
+		print("  AutoRound device is CPU. A 9B W4A16 tune takes a very long time.")
+		print("  Install CUDA 13 torch+torchvision, then retry:")
+		print("  python -m pip install --force-reinstall torch torchvision --index-url https://download.pytorch.org/whl/cu130")
+	elif gb<=2 and vram>=6:
+		bs,acc,seqlen,nsamples=8,1,2048,128
+	elif gb<=4 and vram>=8:
+		bs,acc,seqlen,nsamples=4,2,2048,128
+	elif vram<10:
+		bs,acc,seqlen,nsamples=1,8,2048,128
+	elif vram<16:
+		bs,acc,seqlen,nsamples=1,4,2048,128
+	else:
+		bs,acc,seqlen,nsamples=4,2,2048,128
+	if hybrid and not fast_ok:
+		seqlen=min(seqlen,1024)
+		print("  ⚠ Hybrid linear attention using torch fallback (fla + causal-conv1d missing).")
+		print(f"    seqlen capped at {seqlen} — enable fast path: pip install triton-windows flash-linear-attention")
+	arch_ov=ARCH_BS_OVERRIDE.get(str((info or {}).get("type","")).lower()) or ARCH_BS_OVERRIDE.get(str((info or {}).get("arch","")).lower())
+	if arch_ov and device=="cuda" and arch_ov["bs"]>bs and vram>=arch_ov.get("min_vram",6) and gb<=arch_ov.get("max_gb",8):
+		bs,acc=arch_ov["bs"],max(1,(bs*acc)//arch_ov["bs"])
+		print(f"  ℹ  Arch profile ({info['type']}): batch_size={bs} grad_acc={acc}")
+	if bs_override and bs_override>0:bs,acc=bs_override,max(1,(bs*acc)//bs_override)
+	if seqlen_override and seqlen_override>0:seqlen=seqlen_override
+	lr=5e-3 if 0<iters<=50 else None
+	print(f"  Device: {device}  GPU: {gpu_name}  VRAM: {vram:.1f} GiB")
+	print(f"  batch_size={bs}  grad_acc={acc}  seqlen={seqlen}  nsamples={nsamples}  iters={iters}")
+	dataset=resolve_autoround_dataset(tokenizer,experimental=experimental,dataset_path=dataset_path,seqlen=seqlen,nsamples=nsamples)
+	ar=AutoRound(
+		model=st_dir,tokenizer=tokenizer,bits=4,group_size=128,sym=True,
+		scheme="W4A16",dataset=dataset,iters=iters,seqlen=seqlen,nsamples=nsamples,
+		batch_size=bs,gradient_accumulate_steps=acc,low_gpu_mem_usage=True,
+		quant_nontext_module=False,device_map=device,enable_torch_compile=False,
+		**({} if lr is None else {"lr":lr}),
+	)
+	saved=ar.quantize_and_save(output_dir=out_dir,format="auto_round",inplace=False)
+	actual=out_dir
+	if isinstance(saved,(tuple,list)) and len(saved)>=2:
+		folders=saved[1]
+		if isinstance(folders,dict):
+			folders=[v for v in folders.values() if isinstance(v,str)]
+		elif isinstance(folders,str):
+			folders=[folders]
+		if isinstance(folders,(list,tuple)):
+			for p in folders:
+				if isinstance(p,str) and _dir_has_weights(p):
+					actual=p
+					break
+	actual=_resolve_export_dir(actual)
+	if not _dir_has_weights(actual):
+		found=find_autoround_export(st_dir)
+		if found:actual=found
+	print(f"  ✓ AutoRound tuning complete → {actual}\n")
+	return actual
+
+def patch_index_with_mtp(st_dir,mtp_name=None):
+	mtp_path=os.path.join(st_dir,mtp_name) if mtp_name else _find_mtp_sidecar(st_dir)
+	if not mtp_path or not os.path.isfile(mtp_path):return None
+	mtp_name=os.path.basename(mtp_path)
+	idx_path=os.path.join(st_dir,"model.safetensors.index.json")
+	idx=read_json(idx_path)
+	if idx is None:return None
+	header=read_safetensors_header(mtp_path)
+	patched=dict(idx)
+	wm=dict(idx.get("weight_map",{}))
+	for k in [k for k in header if k!="__metadata__"]:wm[k]=mtp_name
+	for k in list(wm):
+		if(k.startswith("mtp.") or ".nextn." in k) and k not in header:
+			del wm[k]
+	patched["weight_map"]=wm
+	return patched
+
+def ensure_preprocessor_config(st_dir):
+	path=os.path.join(st_dir,"preprocessor_config.json")
+	cfg=read_json(path) or {}
+	cfg_main=read_json(os.path.join(st_dir,"config.json")) or {}
+	vis=cfg_main.get("vision_config",{})
+	if not vis:return True
+	added=[]
+	for key in("image_mean","image_std"):
+		if key not in cfg:
+			cfg[key]=list(_SIGLIP_NORM);added.append(key)
+	defaults={
+		"do_convert_rgb":True,"do_normalize":True,"do_rescale":True,"do_resize":True,
+		"rescale_factor":1/255,
+		"patch_size":vis.get("patch_size",16),
+		"merge_size":vis.get("spatial_merge_size",2),
+		"temporal_patch_size":vis.get("temporal_patch_size",2),
+		"processor_class":"Qwen3VLProcessor",
+	}
+	for k,v in defaults.items():
+		if k not in cfg:cfg[k]=v;added.append(k)
+	if added:
+		bak=path+".bak-00"
+		if os.path.isfile(path) and not os.path.exists(bak):
+			with open(bak,"w",encoding="utf-8") as f:json.dump(read_json(path),f,indent=2)
+		with open(path,"w",encoding="utf-8") as f:json.dump(cfg,f,indent=2)
+		print(f"\n  ℹ  preprocessor_config.json updated: {', '.join(added)}")
+	return True
+
+def size_str(path):
+	mb=os.path.getsize(path)/(1024*1024)
+	return f"{mb/1024:.2f} GB" if mb>=1024 else f"{mb:.0f} MiB"
+
+def _record_provenance(gguf_path,autoround,info):
+	rec={"autoround":bool(autoround),"quant_method":info.get("quant_method","bf16"),"bits":info.get("bits",16),"source":os.path.basename(info.get("source_dir","")),"created":time.strftime("%Y-%m-%dT%H:%M:%S")}
+	for k in("int4_layers","int4_submodules","int4_globals"):
+		if info.get(k):rec[k]=info[k]
+	try:
+		with open(os.path.splitext(gguf_path)[0]+".provenance.json","w",encoding="utf-8") as f:json.dump(rec,f,indent=2)
+	except Exception as e:
+		print(f"  [WARN] Provenance sidecar not written: {e}")
+	fmap_path=os.path.join(SCRIPT_DIR,"quant-provenance.json")
+	lock=fmap_path+".lock"
+	# Exclusive lock file ensures concurrent instances merge records safely
+	for _ in range(50):
+		try:
+			fd=os.open(lock,os.O_CREAT|os.O_EXCL|os.O_WRONLY)
+			os.close(fd)
+			break
+		except FileExistsError:
+			time.sleep(0.1)
+	else:
+		print("  [WARN] Provenance lock busy — global map not updated")
+		return
+	try:
+		fmap=read_json(fmap_path) or {}
+		fmap[os.path.basename(gguf_path)]=rec
+		tmp=fmap_path+".tmp"
+		with open(tmp,"w",encoding="utf-8") as f:json.dump(fmap,f,indent=2)
+		os.replace(tmp,fmap_path)
+	except Exception as e:
+		print(f"  [WARN] Provenance map not written: {e}")
+	finally:
+		try:os.remove(lock)
+		except OSError:pass
+
+def run_converter(st_dir,outtype,outfile,no_mtp=False,mmproj_only=False):
+	env=os.environ.copy()
+	env["PYTHONPATH"]=LLAMA_CPP+os.pathsep+env.get("PYTHONPATH","")
+	cmd=[sys.executable,CONVERTER,st_dir,"--outtype",outtype,"--outfile",os.path.join(SCRIPT_DIR,outfile)]
+	if mmproj_only:cmd.append("--mmproj")
+	if no_mtp:cmd.append("--no-mtp")
+	print(f"\n  CMD: convert_hf_to_gguf.py \"{st_dir}\" --outtype {outtype} --outfile {outfile}\n")
+	return subprocess.run(cmd,cwd=LLAMA_CPP,env=env).returncode==0
+
+def split_mtp(st_dir,suffix,model_out,model_path,extract=False):
+	trunk_out=f"model-no-mtp-{suffix}.gguf"
+	trunk_path=os.path.join(SCRIPT_DIR,trunk_out)
+	mtp_out=f"mtp-{suffix}.gguf"
+	mtp_path=os.path.join(SCRIPT_DIR,mtp_out)
+	if os.path.exists(trunk_path):
+		print(f"\n  Output exists: {trunk_out} ({size_str(trunk_path)})")
+	else:
+		print(f"\n[1b] Converting → {trunk_out}")
+		if not run_converter(st_dir,suffix.lower(),trunk_out,no_mtp=True):
+			print(f"  ✗ no-mtp conversion failed.")
+			return False
+		print(f"  ✓ {trunk_out} ({size_str(trunk_path)})")
+	if not extract:
+		print("  ℹ  MTP extraction skipped — use --mtp-gguf or run 00b_BF16-GGUF-MTP-extract.py on demand.")
+		return True
+	if os.path.exists(mtp_path):
+		print(f"\n  Output exists: {mtp_out} ({size_str(mtp_path)})")
+		return True
+	if not os.path.isfile(EXTRACTOR):
+		print(f"  ✗ {os.path.basename(EXTRACTOR)} missing — MTP extraction skipped.")
+		return False
+	print(f"\n[1c] Extracting → {mtp_out}")
+	cmd=[sys.executable,EXTRACTOR,model_path,trunk_path,mtp_path,"--keep-index"]
+	if subprocess.run(cmd,cwd=SCRIPT_DIR).returncode!=0 or not os.path.exists(mtp_path):
+		print(f"  ✗ MTP extraction failed.")
+		return False
+	print(f"  ✓ {mtp_out} ({size_str(mtp_path)})")
+	return True
+
+def main():
+	ap=argparse.ArgumentParser(description="Universal AutoRound-infused GGUF builder",formatter_class=argparse.RawDescriptionHelpFormatter)
+	ap.add_argument("dir",nargs="?",default=None,help="safetensors directory (drag-drop supported)")
+	ap.add_argument("--iters",type=int,default=None,help="tuning iters for raw BF16 (default: auto from model size + hardware)")
+	ap.add_argument("--batch-size",type=int,default=None,help="override AutoRound batch size (effective batch bs×acc kept)")
+	ap.add_argument("--seqlen",type=int,default=None,help="override AutoRound calibration seqlen")
+	ap.add_argument("--skip-tune",action="store_true",help="skip AutoRound tuning on raw BF16")
+	ap.add_argument("--experimental","--exp",action="store_true",help="use experimental.txt (same flag as 01)")
+	ap.add_argument("--dataset",default=None,help="custom calib .txt/.json/.jsonl (overrides bartowski)")
+	ap.add_argument("--autoround-dir",default=None,help="reuse this AutoRound export (skips tuning)")
+	ap.add_argument("--outtype",default="bf16",choices=["bf16","f16"],help="GGUF precision (default: bf16)")
+	ap.add_argument("--force",action="store_true",help="overwrite existing GGUF outputs")
+	ap.add_argument("--mtp-gguf",action="store_true",help="also extract mtp-<SUF>.gguf (fusion-ready, via 00b)")
+	args=ap.parse_args()
+	SUF=args.outtype.upper()
+	st_dir=os.path.abspath(args.dir) if args.dir else os.path.join(SCRIPT_DIR,"safetensors")
+	if not os.path.isdir(st_dir):
+		print(f"Error: directory not found: {st_dir}")
+		return 1
+	st_files=[f for f in os.listdir(st_dir) if f.endswith((".safetensors",".bin"))]
+	if not st_files:
+		print(f"Error: no .safetensors files in {st_dir}")
+		return 1
+	st_dir=_resolve_export_dir(st_dir)
+	info=detect_model(st_dir)
+	if not info:
+		src=_guess_source_dir(st_dir)
+		if src:_ensure_export_sidecars(src,st_dir)
+		info=detect_model(st_dir)
+	if not info:
+		print(f"Error: config.json not found in {st_dir}")
+		return 1
+	print("="*68)
+	print("  00 — Universal AutoRound-infused GGUF Builder")
+	print("="*68)
+	print(f"  Source:        {st_dir}")
+	print(f"  Output dir:    {SCRIPT_DIR}")
+	print(f"  Architecture:  {info['arch']}")
+	print(f"  Model type:    {info['type']}")
+	print(f"  Quantized:     {'yes ('+str(info['quant_method'])+'/'+str(info['quant_format'])+')' if info['quantized'] else 'no (raw BF16)'}")
+	mtp_str="PHANTOM" if(info["mtp_declared"] and not info["mtp_complete"]) else("yes" if info["mtp"] else "no")
+	print(f"  MTP:           {mtp_str}")
+	print(f"  Multimodal:    {'yes' if info['multimodal'] else 'no'}")
+	if args.dataset:calib_label=os.path.basename(args.dataset)
+	elif args.experimental:calib_label="experimental.txt"
+	else:calib_label=DEFAULT_CALIB_NAME
+	print(f"  Calib:         {calib_label}")
+	print("="*68)
+	work_st_dir=st_dir
+	temp_cleanup_dirs=[]
+	used_autoround=False
+	if not info["quantized"] and not args.skip_tune:
+		tuned_dir=os.path.join(SCRIPT_DIR,f"{os.path.basename(st_dir)}_AutoRound_W4A16")
+		existing=find_autoround_export(st_dir,explicit=args.autoround_dir)
+		if existing and _dir_looks_quantized(existing):
+			print(f"\n[AutoRound] Reusing existing W4A16 export: {existing}")
+			print("  Previous tuning is kept. Conversion resumes from this folder.")
+			tuned_dir=existing
+		else:
+			saved=run_autoround_tune(st_dir,tuned_dir,iters=args.iters,experimental=args.experimental,dataset_path=args.dataset,info=info,bs_override=args.batch_size,seqlen_override=args.seqlen)
+			if saved:tuned_dir=saved
+		tuned_dir=_resolve_export_dir(tuned_dir)
+		_ensure_export_sidecars(st_dir,tuned_dir)
+		work_st_dir=tuned_dir
+		used_autoround=True
+		info=detect_model(work_st_dir)
+		if not info:
+			print(f"Error: AutoRound output is not a readable HF folder: {tuned_dir}")
+			return 1
+	if info and info["quantized"]:
+		target_dequant=os.path.join(SCRIPT_DIR,f"{os.path.basename(work_st_dir)}_dequant_bf16")
+		dequantize_model_to_dir(work_st_dir,target_dequant,info)
+		qm=(str(info["quant_method"])+str(info["quant_format"])).lower()
+		used_autoround=used_autoround or "round" in qm
+		src_method=info["quant_method"]
+		int4_meta={k:info[k] for k in("int4_layers","int4_submodules","int4_globals") if k in info}
+		work_st_dir=target_dequant
+		temp_cleanup_dirs.append(target_dequant)
+		info=detect_model(work_st_dir)
+		if info:
+			info["quant_method"]=src_method
+			info.update(int4_meta)
+	ensure_preprocessor_config(work_st_dir)
+	if not ensure_llama_cpp():
+		print(f"Error: {CONVERTER} not found")
+		return 1
+	phantom_head=info["mtp_declared"] and not info["mtp_complete"]
+	model_out=f"model-no-mtp-{SUF}.gguf" if(phantom_head or not info["mtp"]) else f"model-{SUF}.gguf"
+	model_path=os.path.join(SCRIPT_DIR,model_out)
+	skip_convert=os.path.exists(model_path) and not args.force
+	if skip_convert:
+		print(f"\n  Output exists: {model_out} ({size_str(model_path)}) — use --force to overwrite")
+		if not(args.mtp_gguf and info["mtp"] and not phantom_head and "no-mtp" not in model_out):
+			return 0
+	before=set(f for f in os.listdir(SCRIPT_DIR) if f.endswith(".gguf"))
+	idx_path=os.path.join(work_st_dir,"model.safetensors.index.json")
+	idx_backup=None
+	if info["mtp_standalone"] and not skip_convert:
+		patched=patch_index_with_mtp(work_st_dir,info.get("mtp_file"))
+		if patched:
+			idx_backup=idx_path+".bak-00"
+			os.replace(idx_path,idx_backup)
+			with open(idx_path,"w",encoding="utf-8") as f:json.dump(patched,f,indent=2)
+	no_mtp=phantom_head or not info["mtp"]
+	if skip_convert:
+		ok=True
+	else:
+		print(f"\n[1] Converting → {model_out}")
+		try:
+			ok=run_converter(work_st_dir,args.outtype,model_out,no_mtp=no_mtp and info["mtp_declared"])
+		finally:
+			if idx_backup and os.path.exists(idx_backup):
+				os.replace(idx_backup,idx_path)
+		if not ok and not no_mtp:
+			print("  ⚠ Full conversion rejected by convert_hf_to_gguf — falling back without MTP head.")
+			model_out=f"model-no-mtp-{SUF}.gguf"
+			model_path=os.path.join(SCRIPT_DIR,model_out)
+			no_mtp=True
+			ok=run_converter(work_st_dir,args.outtype,model_out,no_mtp=True)
+		if not ok or not os.path.exists(model_path):
+			print(f"\n  ✗ Conversion failed.")
+			return 1
+		print(f"  ✓ {model_out} ({size_str(model_path)})")
+	if info["mtp"] and not no_mtp:
+		split_mtp(work_st_dir,SUF,model_out,model_path,extract=args.mtp_gguf)
+	if info["multimodal"] and not(skip_convert and os.path.exists(os.path.join(SCRIPT_DIR,f"mmproj-{SUF}.gguf"))):
+		mmproj_out=f"mmproj-{SUF}.gguf"
+		mmproj_path=os.path.join(SCRIPT_DIR,mmproj_out)
+		print(f"\n[2] Converting → {mmproj_out}")
+		if run_converter(work_st_dir,args.outtype,mmproj_out,mmproj_only=True) and os.path.exists(mmproj_path):
+			print(f"  ✓ {mmproj_out} ({size_str(mmproj_path)})")
+	after=set(f for f in os.listdir(SCRIPT_DIR) if f.endswith(".gguf"))
+	new_files=sorted(after-before-{model_out,f"mmproj-{SUF}.gguf"})
+	mmproj_renamed=os.path.exists(os.path.join(SCRIPT_DIR,f"mmproj-{SUF}.gguf"))
+	for f in new_files:
+		src=os.path.join(SCRIPT_DIR,f)
+		if any(x in f.lower() for x in["mmproj","vision","proj","clip"]) and not mmproj_renamed:
+			mmproj_path=os.path.join(SCRIPT_DIR,f"mmproj-{SUF}.gguf")
+			os.replace(src,mmproj_path)
+			f=f"mmproj-{SUF}.gguf"
+			src=mmproj_path
+			mmproj_renamed=True
+		print(f" +{f} ({size_str(src)})")
+	for gg in(model_out,f"model-no-mtp-{SUF}.gguf",f"mtp-{SUF}.gguf",f"mmproj-{SUF}.gguf"):
+		gp=os.path.join(SCRIPT_DIR,gg)
+		if os.path.isfile(gp):
+			is_mm="mmproj" in gg
+			mm_info={"quant_method":"bf16","bits":16,"source_dir":info.get("source_dir","")}
+			_record_provenance(gp,False if is_mm else used_autoround,mm_info if is_mm else info)
+	for p in temp_cleanup_dirs:
+		if os.path.isdir(p):
+			print(f"  ℹ  Cleaning up temporary workspace: {os.path.basename(p)}")
+			shutil.rmtree(p,ignore_errors=True)
+	print("\n"+"="*68)
+	print("  Step 00 complete: AutoRound-infused GGUF files ready!")
+	print("="*68)
+	return 0
+
+if __name__=="__main__":
+	raise SystemExit(main())

00b_BF16-GGUF-MTP-extract.py

@@ -0,0 +1,94 @@
+#!/usr/bin/env python
+r"""00b_BF16-GGUF-MTP-extract.py — Extract the MTP head as a standalone GGUF.
+
+Diffs a full GGUF against its no-mtp variant: tensors only present in the
+full file (the MTP layer) plus shared embedding/output tensors needed by a
+speculative draft are written to mtp-<suffix>.gguf.
+
+Usage:
+	python 00b_BF16-GGUF-MTP-extract.py model-BF16.gguf model-no-mtp-BF16.gguf
+"""
+import os,re,shutil,sys
+
+SCRIPT_DIR=os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0,os.path.join(SCRIPT_DIR,"llama-cpp","gguf-py"))
+import gguf
+
+SHARED_EXACT={"token_embd.weight","token_embd_norm.weight","output.weight","output_norm.weight"}
+# Exact names avoid matching blk.N.attn_output.weight tensors
+MTP_PROJ_HINT=("nextn.eh_proj","nextn.fc","nextn.enorm","nextn.hnorm","nextn.embed_tokens","nextn.shared_head")
+
+SCALAR_WRITERS={
+	gguf.GGUFValueType.UINT8:"add_uint8",gguf.GGUFValueType.INT8:"add_int8",
+	gguf.GGUFValueType.UINT16:"add_uint16",gguf.GGUFValueType.INT16:"add_int16",
+	gguf.GGUFValueType.UINT32:"add_uint32",gguf.GGUFValueType.INT32:"add_int32",
+	gguf.GGUFValueType.FLOAT32:"add_float32",gguf.GGUFValueType.UINT64:"add_uint64",
+	gguf.GGUFValueType.INT64:"add_int64",gguf.GGUFValueType.FLOAT64:"add_float64",
+	gguf.GGUFValueType.BOOL:"add_bool",gguf.GGUFValueType.STRING:"add_string",
+}
+
+def _copy_field(writer,field):
+	vtype=field.types[0]
+	val=field.contents()
+	if vtype==gguf.GGUFValueType.ARRAY:
+		# Arrays without elements are skipped by the GGUF writer
+		if not val:
+			print(f"  ! empty array skipped: {field.name}")
+			return
+		writer.add_array(field.name,val)
+	else:
+		getattr(writer,SCALAR_WRITERS[vtype])(field.name,val)
+
+def main():
+	args=[a for a in sys.argv[1:] if not a.startswith("--")]
+	# Preserve blk.N indices to prevent collision with trunk blk.0 on fusion re-merge
+	keep_idx="--keep-index" in sys.argv
+	if len(args)<2:
+		print("Usage: python 00b_BF16-GGUF-MTP-extract.py <full.gguf> <no-mtp.gguf> [out.gguf] [--keep-index]")
+		return 1
+	full_path=os.path.abspath(args[0])
+	stripped_path=os.path.abspath(args[1])
+	m=re.search(r"-(BF16|F16|F32)",os.path.basename(full_path),re.I)
+	out_path=os.path.abspath(args[2]) if len(args)>2 else os.path.join(
+		SCRIPT_DIR,f"mtp-{m.group(1).upper() if m else 'BF16'}.gguf")
+	full=gguf.GGUFReader(full_path)
+	stripped_names={t.name for t in gguf.GGUFReader(stripped_path).tensors}
+	mtp_tensors=[t for t in full.tensors if t.name not in stripped_names]
+	if not mtp_tensors:
+		print("No extra tensors in the full GGUF — nothing to extract.")
+		return 1
+	if not any(any(h in t.name for h in MTP_PROJ_HINT) for t in mtp_tensors):
+		print("Extra tensors found without a nextn projector (eh_proj/fc/enorm/hnorm) —")
+		print("this represents an unprojected attention block rather than a complete MTP head.")
+		return 1
+	shared=[] if keep_idx else [t for t in full.tensors if t.name in stripped_names and t.name in SHARED_EXACT]
+	arch=str(full.fields["general.architecture"].parts[full.fields["general.architecture"].data[0]],encoding="utf-8")
+	writer=gguf.GGUFWriter(out_path,arch)
+	layers=sorted({int(m.group(1)) for t in mtp_tensors if(m:=re.match(r"blk\.(\d+)\.",t.name))})
+	for field in full.fields.values():
+		if field.name.startswith("GGUF.") or field.name=="general.architecture":continue
+		if field.name.endswith(".block_count"):
+			writer.add_key_value(field.name,(max(layers)+1) if keep_idx else len(layers),field.types[0])
+			continue
+		_copy_field(writer,field)
+	remap={} if keep_idx else {old:new for new,old in enumerate(layers)}
+	for t in mtp_tensors+shared:
+		name=t.name
+		if(m:=re.match(r"blk\.(\d+)\.",name)):
+			old=int(m.group(1))
+			if old in remap:name=f"blk.{remap[old]}."+name[m.end():]
+		writer.add_tensor(name,t.data,raw_shape=t.data.shape,raw_dtype=t.tensor_type)
+	writer.write_header_to_file()
+	writer.write_kv_data_to_file()
+	writer.write_tensors_to_file(progress=True)
+	writer.close()
+	prov_src=os.path.splitext(full_path)[0]+".provenance.json"
+	if os.path.isfile(prov_src):
+		shutil.copy2(prov_src,os.path.splitext(out_path)[0]+".provenance.json")
+	mb=os.path.getsize(out_path)/(1024*1024)
+	print(f"  ✓ {os.path.basename(out_path)} ({mb:.0f} MiB) — {len(mtp_tensors)} MTP tensor(s)"
+		f" (layer(s) {layers}) + {len(shared)} shared tensor(s)")
+	return 0
+
+if __name__=="__main__":
+	raise SystemExit(main())

01_create-calibration-dataset-and-imatrix.py

@@ -0,0 +1,1025 @@
+#!/usr/bin/env python3
+"""01_create-calibration-dataset-and-imatrix.py — End-to-end imatrix calibration pipeline.
+
+1. Download & reassemble datasets → 01_create-calibration-dataset-and-imatrix/raw/
+2. Normalize sources → 01_create-calibration-dataset-and-imatrix/normalized/
+3. Build calibration text (Agentic / Frontier / Logic / Diversity quota targets)
+4. Compute imatrix.dat via llama-imatrix (with GPU autotuning and PPL verification)
+"""
+import collections,concurrent.futures,itertools,json,os,re,struct,subprocess,sys,time,urllib.request
+from huggingface_hub import hf_hub_download,list_repo_files
+
+# Managed pages instead of rigid VMM pool to tolerate fragmentation across loaded VRAM
+os.environ.setdefault("GGML_CUDA_ENABLE_UNIFIED_MEMORY","1")
+
+LLAMA_GGUF_PY=os.path.join(os.path.dirname(os.path.abspath(__file__)),"llama-cpp","gguf-py")
+if os.path.isdir(LLAMA_GGUF_PY):sys.path.insert(0,LLAMA_GGUF_PY)
+
+ROOT=os.path.dirname(os.path.abspath(__file__))
+DATA=os.path.join(ROOT,"01_create-calibration-dataset-and-imatrix")
+RAW=os.path.join(DATA,"raw")
+NORM=os.path.join(DATA,"normalized")
+EXPERIMENTAL_CALIB=os.path.join(DATA,"experimental.txt")
+DEFAULT_CALIB_NAME="bartowski-imatrix-v5-semantic.txt"
+DEFAULT_CALIB_URL="https://huggingface.co/datasets/lemon07r/bartowski-imatrix-v5-semantic/blob/main/bartowski-imatrix-v5-semantic.txt"
+DEFAULT_CALIB_PATH=os.path.join(DATA,DEFAULT_CALIB_NAME)
+IMATRIX=os.path.join(ROOT,"imatrix.dat")
+LLAMA=os.path.join(ROOT,"llama-cpp")
+MODEL_CANDIDATES=[
+	"model-no-mtp-BF16.gguf",
+	"model-BF16-no-mtp.gguf",
+	"model-BF16.gguf",
+	"model-no-mtp-F16.gguf",
+	"model-F16-no-mtp.gguf",
+	"model-F16.gguf",
+]
+BF16=next(
+	(os.path.join(ROOT,name) for name in MODEL_CANDIDATES
+		if os.path.exists(os.path.join(ROOT,name))),
+	os.path.join(ROOT,MODEL_CANDIDATES[-1])
+)
+
+# ═══════════════════════════════════════════════════════════════════════════
+#  STEP 1 — DOWNLOAD & REASSEMBLY
+# ═══════════════════════════════════════════════════════════════════════════
+GISTS=[("calibration_data_v5_rc.txt","https://gist.github.com/tristandruyen/9e207a95c7d75ddf37525d353e00659c/raw/571fda718462de863e5a0171078c175420c7649a/calibration_data_v5_rc.txt"),]
+DATASETS=[
+	("fable-5-claude-code","armand0e/claude-fable-5-claude-code","Frontier"),
+	("minimax-m3-traces","armand0e/minimax-m3-claude-code-traces","Frontier"),
+	("opus-4.8-pi-traces","armand0e/claude-opus-4.8-pi-traces","Frontier"),
+	("hermes-function-calling","NousResearch/hermes-function-calling-v1","Others"),
+	("python-codes-25k","flytech/python-codes-25k","Others"),
+	("ma-proofbench","openbmb/MA-ProofBench","Others"),
+	("multi-hop-websearch","lugman-madhiai/multi-hop-websearch-tool-calling","Agentic"),
+]
+SKIP_NAMES={"readme.md",".gitattributes"}
+DATA_EXT=(".jsonl",".json")
+CACHE=os.path.join(DATA,"_hf_cache")
+
+def list_data_files(repo_id):
+	files=list_repo_files(repo_id,repo_type="dataset")
+	out=[]
+	for f in files:
+		low=f.lower()
+		if low in SKIP_NAMES:continue
+		if os.path.basename(low) in SKIP_NAMES:continue
+		if low.endswith(DATA_EXT):out.append(f)
+	jsonl_stems={f[:-6] for f in out if f.lower().endswith(".jsonl")}
+	deduped=[]
+	for f in out:
+		if f.lower().endswith(".json") and f[:-5] in jsonl_stems:
+			print(f"    [DEDUP] Skipping duplicate: {f} (keeping .jsonl)")
+			continue
+		deduped.append(f)
+	return sorted(deduped)
+
+def download_one(repo_id,filename):
+	return hf_hub_download(repo_id=repo_id,filename=filename,repo_type="dataset",cache_dir=CACHE)
+
+def iter_records(path):
+	if path.lower().endswith(".jsonl"):
+		with open(path,"r",encoding="utf-8") as f:
+			for line in f:
+				line=line.strip()
+				if not line:continue
+				try:yield json.loads(line)
+				except Exception:continue
+	else:
+		try:
+			with open(path,"r",encoding="utf-8") as f:data=json.load(f)
+		except Exception:return
+		if isinstance(data,list):
+			for rec in data:yield rec
+		elif isinstance(data,dict):
+			yield data
+
+def reassemble(out_name,repo_id):
+	out_path=os.path.join(RAW,out_name+".jsonl")
+	if os.path.exists(out_path):
+		print(f"  [OK] Already assembled: {out_name}.jsonl")
+		return
+	try:files=list_data_files(repo_id)
+	except Exception as e:
+		print(f"  [ERR] Failed listing repo files for {repo_id}: {e}")
+		return
+	if not files:
+		print(f"  [WARN] No data files found in {repo_id}")
+		return
+	print(f"  [DL] {repo_id} → {len(files)} files")
+	local_paths=[]
+	with concurrent.futures.ThreadPoolExecutor(max_workers=8) as ex:
+		futures={ex.submit(download_one,repo_id,f):f for f in files}
+		for fut in concurrent.futures.as_completed(futures):
+			f=futures[fut]
+			try:local_paths.append(fut.result())
+			except Exception as e:print(f"    [ERR] {f}: {e}")
+	n_rec=0
+	with open(out_path,"w",encoding="utf-8") as out:
+		for lp in local_paths:
+			for rec in iter_records(lp):
+				out.write(json.dumps(rec,ensure_ascii=False)+"\n")
+				n_rec+=1
+	size_mb=os.path.getsize(out_path)/1024/1024
+	print(f"  [DONE] {out_name}.jsonl → {n_rec} records ({size_mb:.1f} MB)")
+
+def download_gists():
+	for fname,url in GISTS:
+		dest=os.path.join(RAW,fname)
+		if os.path.exists(dest):
+			print(f"  [OK] Already present: {fname}")
+			continue
+		print(f"  [DL] {fname}")
+		try:
+			urllib.request.urlretrieve(url,dest)
+			print(f"  [DONE] {fname} ({os.path.getsize(dest)/1024/1024:.1f} MB)")
+		except Exception as e:
+			print(f"  [ERR] {fname}: {e}")
+
+def step_download():
+	os.makedirs(RAW,exist_ok=True)
+	print("\n"+"="*72)
+	print(" 📥 STEP 1/4 — DOWNLOAD & REASSEMBLY")
+	print("="*72)
+	for out_name,repo_id,cat in DATASETS:
+		print(f"\n── [{cat}] {out_name} ──")
+		reassemble(out_name,repo_id)
+	print(f"\n── [Diversity] calibration gists ──")
+	download_gists()
+
+# ═══════════════════════════════════════════════════════════════════════════
+#  STEP 2 — NORMALIZATION
+# ═══════════════════════════════════════════════════════════════════════════
+def extract_blocks(content):
+	if isinstance(content,str):
+		return [("text",content)] if content.strip() else []
+	out=[]
+	if isinstance(content,list):
+		for b in content:
+			if not isinstance(b,dict):continue
+			t=b.get("type")
+			if t=="text":out.append(("text",b.get("text","")))
+			elif t=="thinking":out.append(("think",b.get("thinking","")))
+			elif t in("tool_use","toolCall"):
+				name=b.get("name")
+				args=b.get("input") if b.get("input") is not None else b.get("arguments")
+				out.append(("toolcall",json.dumps({"name":name,"input":args},ensure_ascii=False)))
+			elif t in("tool_result","toolResult"):
+				c=b.get("content")
+				out.append(("tool",c if isinstance(c,str) else json.dumps(c,ensure_ascii=False)))
+	return out
+
+BLOCK_ROLE={"text":None,"think":"think","toolcall":"toolcall","tool":"tool"}
+
+def parse_hermes(row):
+	chat=[]
+	rolemap={"system":"system","human":"user","gpt":"assistant","tool":"tool"}
+	for msg in row.get("conversations",[]):
+		role=rolemap.get(msg.get("from"))
+		c=(msg.get("value") or "").strip()
+		if not role or not c:continue
+		if role=="assistant":
+			m=re.search(r"<think>\s*(.*?)\s*</think>",c,re.DOTALL)
+			if m:
+				chat.append({"role":"think","content":m.group(1).strip()})
+				c=re.sub(r"<think>.*?</think>","",c,flags=re.DOTALL).strip()
+			last=0
+			for tc in re.finditer(r"<tool_call>(.*?)</tool_call>",c,re.DOTALL):
+				chunk=c[last:tc.start()].strip()
+				if chunk:chat.append({"role":"assistant","content":chunk})
+				chat.append({"role":"toolcall","content":tc.group(1).strip()})
+				last=tc.end()
+			chunk=c[last:].strip()
+			if chunk:chat.append({"role":"assistant","content":chunk})
+		else:
+			chat.append({"role":role,"content":c})
+	return {"chat":chat} if len(chat)>=2 else None
+
+def parse_python_codes(row):
+	instr=(row.get("instruction") or "").strip()
+	inp=(row.get("input") or "").strip()
+	out=(row.get("output") or "").strip()
+	if not instr or not out:return None
+	user=instr if not inp else f"{instr}\n{inp}"
+	return {"chat":[{"role":"user","content":user},{"role":"assistant","content":out}]}
+
+def parse_proofbench(row):
+	inf=(row.get("informal_statement") or "").strip()
+	frm=(row.get("formal_statement") or "").strip()
+	proof=(row.get("formal_proof") or row.get("proof") or "").strip()
+	topic=(row.get("topic") or "").strip()
+	tag=(row.get("tag") or "").strip()
+	if not inf and not frm:return None
+	user=inf if inf else "Formalize and prove the following in Lean 4."
+	ctx=" / ".join(p for p in(topic,tag) if p)
+	if ctx:user+=f"\n(Domain: {ctx})"
+	answer="\n".join(p for p in(frm,proof) if p) or inf
+	return {"chat":[
+		{"role":"user","content":user},
+		{"role":"assistant","content":answer}
+	]}
+
+def parse_multi_hop_websearch(row):
+	chat=[]
+	for msg in row.get("messages",[]):
+		if not isinstance(msg,dict):continue
+		role=msg.get("role")
+		content=(msg.get("content") or "").strip()
+		think=(msg.get("thinking") or "").strip()
+		if think:chat.append({"role":"think","content":think})
+		if role=="user":
+			if content:chat.append({"role":"user","content":content})
+		elif role=="assistant":
+			if content:chat.append({"role":"assistant","content":content})
+			for tc in(msg.get("tool_calls") or []):
+				if not isinstance(tc,dict):continue
+				name=tc.get("name","")
+				raw_args=tc.get("arguments","{}")
+				try:args=json.loads(raw_args) if isinstance(raw_args,str) else raw_args
+				except Exception:args=raw_args
+				chat.append({"role":"toolcall","content":json.dumps({"name":name,"input":args},ensure_ascii=False)})
+		elif role=="tool":
+			if content:chat.append({"role":"tool","content":content})
+	return {"chat":chat} if len(chat)>=2 else None
+
+def merge_adjacent(turns):
+	out=[]
+	for t in turns:
+		if out and out[-1]["role"]==t["role"]:
+			out[-1]["content"]+="\n"+t["content"]
+		else:
+			out.append(dict(t))
+	return out
+
+def parse_claude_events(rows):
+	sessions,order={},[]
+	cur,counter="__seed",0
+	for row in rows:
+		if not isinstance(row,dict):continue
+		t=row.get("type")
+		if t=="session":
+			counter+=1
+			cur=f"__pi{counter}"
+			continue
+		if t not in("user","assistant","message"):continue
+		msg=row.get("message")
+		if not isinstance(msg,dict):continue
+		sid=row.get("sessionId") or cur
+		raw_role=msg.get("role") or("assistant" if t=="assistant" else "user")
+		role={"toolResult":"tool","tool":"tool"}.get(raw_role,raw_role)
+		blocks=extract_blocks(msg.get("content"))
+		if not blocks:continue
+		if sid not in sessions:
+			sessions[sid]=[]
+			order.append(sid)
+		for kind,text in blocks:
+			text=(text or "").strip()
+			if not text:continue
+			r=("tool" if role=="tool" and kind=="text" else(BLOCK_ROLE[kind] or role))
+			sessions[sid].append({"role":r,"content":text})
+	chats=[]
+	for sid in order:
+		turns=merge_adjacent(sessions[sid])
+		has_tool=any(x["role"] in("toolcall","tool") for x in turns)
+		if len(turns)>=2 or(turns and has_tool):
+			chats.append({"chat":turns})
+	return chats
+
+ROW_PARSERS={
+	"hermes-function-calling.jsonl":parse_hermes,
+	"python-codes-25k.jsonl":parse_python_codes,
+	"ma-proofbench.jsonl":parse_proofbench,
+	"multi-hop-websearch.jsonl":parse_multi_hop_websearch
+}
+FILE_PARSERS={
+	"fable-5-claude-code.jsonl":parse_claude_events,
+	"minimax-m3-traces.jsonl":parse_claude_events,
+	"opus-4.8-pi-traces.jsonl":parse_claude_events
+}
+
+def iter_rows(path):
+	with open(path,"r",encoding="utf-8") as f:
+		for line in f:
+			line=line.strip()
+			if not line:continue
+			try:yield json.loads(line)
+			except Exception:continue
+
+def process_norm(path,filename):
+	os.makedirs(NORM,exist_ok=True)
+	out_path=os.path.join(NORM,filename)
+	count=0
+	with open(out_path,"w",encoding="utf-8") as fo:
+		if filename in FILE_PARSERS:
+			for chat in FILE_PARSERS[filename](list(iter_rows(path))):
+				fo.write(json.dumps(chat,ensure_ascii=False)+"\n")
+				count+=1
+		elif filename in ROW_PARSERS:
+			parser=ROW_PARSERS[filename]
+			for row in iter_rows(path):
+				parsed=parser(row)
+				if parsed:fo.write(json.dumps(parsed,ensure_ascii=False)+"\n")
+				count+=1
+		else:
+			print(f"  [SKIP] No parser mapped: {filename}")
+			return
+	print(f"  [OK] {filename:34s} → {count} chats")
+
+def step_normalize():
+	print("\n"+"="*72)
+	print(" 🔄 STEP 2/4 — NORMALIZATION raw/ → normalized/")
+	print("="*72)
+	files=sorted(f for f in os.listdir(RAW) if f.lower().endswith(".jsonl"))
+	for fn in files:process_norm(os.path.join(RAW,fn),fn)
+	print("\n[DONE] normalized/ directory ready.")
+
+# ═══════════════════════════════════════════════════════════════════════════
+#  STEP 3 — CALIBRATION
+# ═══════════════════════════════════════════════════════════════════════════
+CATEGORIES={
+	"Agentic":{"ratio":0.55,"files":[
+		"fable-5-claude-code.jsonl",
+		"minimax-m3-traces.jsonl",
+		"hermes-function-calling.jsonl",
+		"multi-hop-websearch.jsonl"
+	]},
+	"Frontier":{"ratio":0.10,"files":[
+		"opus-4.8-pi-traces.jsonl"
+	]},
+	"Logic":{"ratio":0.20,"files":[
+		"ma-proofbench.jsonl",
+		"python-codes-25k.jsonl"
+	]},
+	"Diversity":{"ratio":0.15,"raw":[
+		"calibration_data_v5_rc.txt"
+	]}
+}
+PRIORITY_SOURCES={"opus-4.8-pi-traces.jsonl","ma-proofbench.jsonl"}
+HANDICAP={
+	"hermes-function-calling.jsonl":0.6,
+	"python-codes-25k.jsonl":0.7,
+	"multi-hop-websearch.jsonl":0.8
+}
+USER_MAX=6000
+ASSISTANT_TRIM=5000
+TARGET_MB=5
+
+def load_source(fname):
+	path=os.path.join(NORM,fname)
+	blocks=[]
+	n_lines=n_drop=0
+	if not os.path.exists(path):
+		print(f"  [ERR] Not found: {path}")
+		return fname,blocks
+	priority=fname in PRIORITY_SOURCES
+	with open(path,"r",encoding="utf-8") as f:
+		for line in f:
+			n_lines+=1
+			try:chat=json.loads(line).get("chat",[])
+			except Exception:continue
+			if not priority and any(m.get("role")=="user" and len(m.get("content",""))>USER_MAX for m in chat):
+				n_drop+=1
+				continue
+			merged=[]
+			for m in chat:
+				role=m.get("role")
+				text=(m.get("content") or "").strip()
+				if not role or not text:continue
+				if role=="assistant" and not priority and len(text)>ASSISTANT_TRIM:
+					text=text[:ASSISTANT_TRIM]
+				text=re.sub(r"\n{3,}","\n",text).strip()
+				if not text:continue
+				if merged and merged[-1]["role"]==role:
+					merged[-1]["content"]+="\n"+text
+				else:
+					merged.append({"role":role,"content":text})
+			if not merged:continue
+			parts=[f"‗{m['role']}‗\n{re.sub(chr(13),'',m['content']).strip()}" for m in merged]
+			blocks.append("\n".join(parts))
+	if fname in HANDICAP:
+		cap=HANDICAP[fname]
+		before=len(blocks)
+		blocks=blocks[:int(before*cap)]
+		print(f"  [CAP]  {fname:32s} {before}→{len(blocks)} blocks (~{int(cap*100)}%)")
+	tag="★100%" if priority else "     "
+	print(f"  {tag} {fname:32s} {n_lines:6d} lines (rejected {n_drop}) → {len(blocks)} blocks")
+	return fname,blocks
+
+def load_raw_source(fname):
+	path=os.path.join(DATA,"raw",fname)
+	if not os.path.exists(path):
+		print(f"  [ERR] Not found: {path}")
+		return fname,[]
+	with open(path,"r",encoding="utf-8",errors="replace") as f:
+		text=f.read()
+	if "===========" in text:
+		parts=re.split(r"\n=+\n",text)
+	else:
+		parts=re.split(r"\n{2,}",text)
+	blocks=[p.strip() for p in parts if len(p.strip())>200]
+	print(f"  [RAW] {fname:32s} → {len(blocks)} raw blocks")
+	return fname,blocks
+
+def load_category(name,cfg):
+	if "raw" in cfg:
+		print(f"\n📂 [{name}] {len(cfg['raw'])} raw source(s)…")
+		blocks=[b for fn in cfg["raw"] for b in load_raw_source(fn)[1]]
+		mb=sum(len(b.encode("utf-8")) for b in blocks)/1024/1024
+		print(f"  → {name}: {mb:.1f} MB, {len(blocks)} blocks")
+		return name,blocks
+	print(f"\n📂 [{name}] {len(cfg['files'])} source(s)…")
+	with concurrent.futures.ThreadPoolExecutor() as ex:
+		results=list(ex.map(lambda fn:load_source(fn),cfg["files"]))
+	priority_bl=[b for fn,bl in results if fn in PRIORITY_SOURCES for b in bl]
+	rest=[bl for fn,bl in results if fn not in PRIORITY_SOURCES]
+	if not rest:inter=[]
+	elif len(rest)==1:inter=rest[0]
+	else:inter=[b for grp in itertools.zip_longest(*rest) for b in grp if b is not None]
+	combined=priority_bl+inter
+	mb=sum(len(b.encode("utf-8")) for b in combined)/1024/1024
+	print(f"  → {name}: {mb:.1f} MB, {len(combined)} blocks ({len(priority_bl)} priority)")
+	return name,combined
+
+def step_calibrate():
+	print("\n"+"="*72)
+	print(" 📊 STEP 3/4 — BUILDING experimental.txt")
+	print("="*72)
+	if os.path.exists(EXPERIMENTAL_CALIB):
+		print(f"[CALIB] Reusing existing {EXPERIMENTAL_CALIB}")
+		return {}
+	with concurrent.futures.ThreadPoolExecutor(max_workers=len(CATEGORIES)) as ex:
+		futures=[ex.submit(load_category,name,cfg) for name,cfg in CATEGORIES.items()]
+		results=[future.result() for future in futures]
+	avail={name:blocks for name,blocks in results}
+	sizes_av={n:sum(len(b.encode("utf-8")) for b in avail[n]) for n in CATEGORIES}
+	# Iterative saturation under global budget: exhaust small categories and reallocate remainder
+	targets={}
+	remaining={n:CATEGORIES[n]["ratio"] for n in CATEGORIES}
+	pool=dict(sizes_av)
+	budget_total=TARGET_MB*1024*1024
+	while remaining:
+		total_r=sum(remaining.values())
+		budget=min(sum(pool[n] for n in remaining),budget_total)
+		saturated=[n for n in remaining if pool[n]<budget*remaining[n]/total_r]
+		if not saturated:
+			for n in remaining:targets[n]=budget*remaining[n]/total_r
+			break
+		for n in saturated:
+			targets[n]=pool[n]
+			budget_total=max(0,budget_total-pool[n])
+			del remaining[n]
+			del pool[n]
+	print("\n"+"="*68)
+	print(" 📊 DIAGNOSTIC")
+	print("="*68)
+	for n in CATEGORIES:
+		t=targets.get(n,0)
+		flag=" ★saturated" if abs(t-sizes_av[n])<1 else ""
+		print(f"  {n:10s} {sizes_av[n]/1024/1024:7.2f} MB available ({len(avail[n]):5d} blocks) → target {t/1024/1024:6.2f} MB{flag}")
+	print(f"  Target corpus size: {sum(targets.values())/1024/1024:.2f} MB")
+	sizes={n:0 for n in CATEGORIES}
+	idx={n:0 for n in CATEGORIES}
+	contrib={}
+	out=[]
+	print("\n🔨 Packing blocks…")
+	while True:
+		deficit={n:targets[n]-sizes[n] for n in CATEGORIES}
+		cand=[n for n in CATEGORIES if idx[n]<len(avail[n]) and deficit[n]>0]
+		if not cand:break
+		pick=max(cand,key=lambda n:deficit[n])
+		blk=avail[pick][idx[pick]]
+		idx[pick]+=1
+		b=len(blk.encode("utf-8"))
+		sizes[pick]+=b
+		out.append(blk)
+		contrib[pick]=contrib.get(pick,0)+1
+	if not out:
+		print("\n  [ERR] No blocks collected — experimental.txt not written.")
+		return {}
+	with open(EXPERIMENTAL_CALIB,"w",encoding="utf-8",newline="\n") as f:
+		f.write("\n".join(out))
+	total=sum(sizes.values())
+	print("\n"+"="*68)
+	print(f" ✅ experimental.txt : {total/1024/1024:.2f} MB, {len(out)} blocks")
+	print("="*68)
+	stats={}
+	for n in CATEGORIES:
+		r=sizes[n]/total if total else 0
+		print(f"  {n:10s} {sizes[n]/1024/1024:6.2f} MB  actual {r:5.1%}  (target {CATEGORIES[n]['ratio']:.0%})  {contrib.get(n,0)} blocks")
+		stats[n]={"mb":round(sizes[n]/1024/1024,2),"ratio":round(r,4),"blocks":contrib.get(n,0)}
+	stats["total_mb"]=round(total/1024/1024,2)
+	stats["total_blocks"]=len(out)
+	return stats
+
+# ═══════════════════════════════════════════════════════════════════════════
+#  STEP 3b — STRIP MTP (GGUF copy without MTP heads for llama-imatrix)
+# ═══════════════════════════════════��═══════════════════════════════════════
+MTP_TENSOR_HINT=("mtp.","nextn.",".nextn_")
+MTP_KV_HINT=("nextn_predict_layers","mtp_num")
+
+def is_mtp_name(name):
+	low=name.lower()
+	return any(h in low for h in MTP_TENSOR_HINT)
+
+def gguf_analyze_mtp(path):
+	"""Analyze blk.N layers structurally to locate the MTP head.
+
+	Returns (mtp_layers, n_keep):
+		mtp_layers — set of blk.N indices forming the MTP head (empty set if the
+		             MTP lives only in name-matched tensors, None if no MTP found)
+		n_keep     — corrected block_count for the stripped file
+	"""
+	import gguf
+	from collections import Counter
+	try:reader=gguf.GGUFReader(path)
+	except Exception as e:
+		print(f"  [WARN] MTP scan failed ({e}) → using original GGUF directly")
+		return None,None
+	n_decl=None
+	mtp_kv=False
+	for field in reader.fields.values():
+		if field.name.endswith(".block_count"):
+			v=field.parts[field.data[0]]
+			n_decl=int(v.item() if hasattr(v,"item") else v)
+		if any(h in field.name.lower() for h in MTP_KV_HINT):mtp_kv=True
+	layers={}
+	named=False
+	named_layers=set()
+	for t in reader.tensors:
+		m=re.match(r"blk\.(\d+)\.(.+)$",t.name)
+		if m:
+			layers.setdefault(int(m.group(1)),set()).add(m.group(2))
+			if is_mtp_name(t.name):named_layers.add(int(m.group(1)))
+		elif is_mtp_name(t.name):
+			named=True
+	if not layers:
+		return(set() if(named or mtp_kv) else None),n_decl
+	idx=sorted(layers)
+	sig_count=Counter(frozenset(layers[i]) for i in idx)
+	legit={sig for sig,cnt in sig_count.items() if cnt>=2}
+	if not legit:
+		ref=max(sig_count,key=lambda s:len(s))
+		legit={ref}
+	mtp={i for i in idx if frozenset(layers[i]) not in legit}
+	if n_decl is not None:mtp|={i for i in idx if i>=n_decl}
+	mtp|=named_layers
+	if mtp and not named_layers:
+		has_eh=any("nextn.eh_proj" in t.name for t in reader.tensors)
+		if not has_eh and not mtp_kv:
+			print("  [MTP] Unique terminal block signature without nextn.eh_proj")
+			print("        → standard attention layer, strip not required")
+			return None,None
+	if not mtp and not named and not mtp_kv:return None,None
+	keep=[i for i in idx if i not in mtp]
+	n_keep=len(keep) if keep else n_decl
+	print(f"  [MTP] Layer analysis: {len(idx)} blk.N layers, {len(sig_count)} distinct signature(s)")
+	for sig,cnt in sorted(sig_count.items(),key=lambda x:-x[1]):
+		tag="legitimate" if sig in legit else "MTP HEAD"
+		print(f"        signature {len(sig)} tensor(s) × {cnt} layer(s) → {tag}")
+	for i in sorted(mtp):
+		print(f"        layer blk.{i} : {len(layers[i])} tensor(s) → removed MTP head")
+	return mtp,n_keep
+
+def strip_mtp_gguf(src,dst,mtp_layers,n_keep):
+	"""Copy a GGUF while removing whole MTP layers, name-matched MTP tensors and
+
+	their metadata keys. block_count is rewritten to n_keep."""
+	import gguf
+	reader=gguf.GGUFReader(src)
+	arch_field=reader.fields["general.architecture"]
+	arch=str(arch_field.parts[arch_field.data[0]],encoding="utf-8")
+	writer=gguf.GGUFWriter(dst,arch)
+	for field in reader.fields.values():
+		if field.name.startswith("GGUF.") or field.name=="general.architecture":continue
+		if any(h in field.name.lower() for h in MTP_KV_HINT):
+			print(f"    [KV-SKIP] {field.name}")
+			continue
+		if n_keep is not None and field.name.endswith(".block_count"):
+			v=field.parts[field.data[0]]
+			old=int(v.item() if hasattr(v,"item") else v)
+			if old!=n_keep:
+				print(f"    [KV-FIX] {field.name} : {old} → {n_keep}")
+				writer.add_key_value(field.name,n_keep,field.types[0])
+				continue
+		writer.add_key_value(field.name,field.contents(),field.types[0])
+	kept=dropped=0
+	for tensor in reader.tensors:
+		m=re.match(r"blk\.(\d+)\.",tensor.name)
+		if is_mtp_name(tensor.name) or(mtp_layers and m and int(m.group(1)) in mtp_layers):
+			dropped+=1
+			continue
+		writer.add_tensor(tensor.name,tensor.data,raw_shape=tensor.data.shape,raw_dtype=tensor.tensor_type)
+		kept+=1
+	writer.write_header_to_file()
+	writer.write_kv_data_to_file()
+	writer.write_tensors_to_file()
+	writer.close()
+	print(f"    [STRIP] {kept} tensor(s) kept, {dropped} MTP tensor(s) stripped (layers {sorted(mtp_layers) if mtp_layers else 'named'})")
+
+def step_strip_mtp():
+	"""Ensure a no-mtp GGUF exists for imatrix when the full model embeds MTP."""
+	global BF16
+	base_fn=os.path.basename(BF16)
+	if "-no-mtp" in base_fn or "no-mtp" in base_fn:return
+	dirname=os.path.dirname(BF16)
+	no_mtp_name=base_fn.replace("model-","model-no-mtp-") if base_fn.startswith("model-") else f"model-no-mtp-{base_fn}"
+	no_mtp=os.path.join(dirname,no_mtp_name)
+	legacy_no_mtp=os.path.join(dirname,base_fn.replace(".gguf","-no-mtp.gguf"))
+	if os.path.exists(no_mtp):
+		BF16=no_mtp
+		print(f"  [OK] Stripped variant already exists: {os.path.basename(no_mtp)}")
+		return
+	if os.path.exists(legacy_no_mtp):
+		BF16=legacy_no_mtp
+		print(f"  [OK] Stripped variant already exists: {os.path.basename(legacy_no_mtp)}")
+		return
+	mtp_layers,n_keep=gguf_analyze_mtp(BF16)
+	if mtp_layers is None:
+		print("  [OK] No MTP tensors detected → using full GGUF directly")
+		return
+	print(f"  [MTP] MTP head detected → generating {os.path.basename(no_mtp)}…")
+	try:
+		strip_mtp_gguf(BF16,no_mtp,mtp_layers,n_keep)
+		BF16=no_mtp
+	except Exception as e:
+		if os.path.exists(no_mtp):
+			try:os.remove(no_mtp)
+			except OSError:pass
+		sys.exit(f"❌ MTP strip failed: {e}")
+
+# ═══════════════════════════════════════════════════════════════════════════
+#  STEP 4 — IMATRIX
+# ═══════════════════════════════════════════════════════════════════════════
+RECURRENT_HINT=("delta","mamba","rwkv","lfm","gated","hybrid","recurrent","ssm","qwen3_next","qwen3.5","qwen35")
+PPL_CEILING=50.0
+
+def read_gguf_meta(path):
+	"""Read architecture and block_count via gguf-py (authoritative parser)."""
+	file_mb=os.path.getsize(path)/1024/1024
+	try:
+		import gguf
+		reader=gguf.GGUFReader(path)
+		arch=None
+		n_layers=0
+		af=reader.fields.get("general.architecture")
+		if af:arch=str(af.parts[af.data[0]],encoding="utf-8")
+		for field in reader.fields.values():
+			if field.name.endswith(".block_count"):
+				v=field.parts[field.data[0]]
+				n_layers=int(v.item() if hasattr(v,"item") else v)
+				break
+		if not(0<n_layers<10000):n_layers=0
+		return arch,n_layers,file_mb
+	except Exception as e:
+		print(f"  [GGUF] Metadata parse failed: {e}")
+		return None,0,file_mb
+
+def ensure_default_calibration():
+	if os.path.exists(DEFAULT_CALIB_PATH):
+		print(f"  [OK] Default calibration file present: {DEFAULT_CALIB_NAME}")
+		return DEFAULT_CALIB_PATH
+	print(f"\n[DL] Downloading default calibration dataset: {DEFAULT_CALIB_NAME}…")
+	os.makedirs(DATA,exist_ok=True)
+	url=DEFAULT_CALIB_URL.replace("/blob/","/resolve/")
+	try:
+		urllib.request.urlretrieve(url,DEFAULT_CALIB_PATH)
+		print(f"  [DONE] {DEFAULT_CALIB_NAME} ({os.path.getsize(DEFAULT_CALIB_PATH)/1024/1024:.2f} MB)")
+	except Exception as e:print(f"  [ERR] Download failed: {e}")
+	return DEFAULT_CALIB_PATH
+
+# Q8_0 by default: imatrix measures uncorrupted activations. Ladder extensible via IMATRIX_QUANT_LADDER
+QUANT_LADDER=tuple(
+	q.strip() for q in os.environ.get("IMATRIX_QUANT_LADDER","Q8_0").split(",") if q.strip()
+)
+QUANT_BPW_RATIO={"Q8_0":0.53,"Q6_K":0.41,"Q5_K_M":0.35}
+
+def ensure_gpu_sized_model(src,gpu_free,overhead,compute_mb):
+	"""Quantize the imatrix source down until it fits entirely into VRAM.
+
+	A partial -ngl split breaks fused GDN on hybrid archs, so a smaller
+	weight format preserves full GPU offload. Returns (path, created_this_run).
+	"""
+	budget=gpu_free-overhead-compute_mb
+	if budget<=0:return src,False
+	if os.path.getsize(src)/1024/1024<=budget:return src,False
+	quantize=os.path.join(LLAMA,"llama-quantize.exe")
+	if not os.path.exists(quantize):
+		print("  [QUANT] llama-quantize.exe missing → retaining source BF16")
+		return src,False
+	base=os.path.basename(src).replace(".gguf","")
+	for fmt in QUANT_LADDER:
+		dst=os.path.join(os.path.dirname(src),f"{base}-{fmt}.gguf")
+		if os.path.exists(dst):
+			mb=os.path.getsize(dst)/1024/1024
+			if mb<=budget:
+				print(f"  [QUANT] Reusing {os.path.basename(dst)} ({mb/1024:.1f} GB)")
+				return dst,False
+			continue
+		est=os.path.getsize(src)/1024/1024*QUANT_BPW_RATIO.get(fmt,0.45)
+		if est>budget:continue
+		print(f"  [QUANT] {fmt} estimated at {est/1024:.1f} GB ≤ budget {budget/1024:.1f} GB → converting…")
+		if fmt!="Q8_0":
+			print(f"  ⚠ [QUANT] {fmt} < Q8_0: activation statistics will be sampled over lower precision weights.")
+			print("    Use CPU mode (--cpu-only) when numerical fidelity takes precedence over runtime.")
+		r=subprocess.run([quantize,src,dst,fmt],capture_output=True,text=True)
+		if r.returncode==0 and os.path.exists(dst):
+			mb=os.path.getsize(dst)/1024/1024
+			print(f"  [QUANT] {os.path.basename(dst)} ready ({mb/1024:.1f} GB) → full GPU offload enabled")
+			return dst,True
+		if os.path.exists(dst):
+			try:os.remove(dst)
+			except OSError:pass
+		print(f"  [QUANT] {fmt} failed → trying next quantization format")
+	print("  [QUANT] No quantized intermediate fit in budget → retaining original model")
+	return src,False
+
+def run_imatrix_streaming(cmd):
+	"""Stream llama-imatrix with real-time progress, ETA, and stderr forwarding.
+
+	Returns (returncode, stdout_text, stderr_text).
+	"""
+	import threading
+	proc=subprocess.Popen(cmd,stdout=subprocess.PIPE,stderr=subprocess.PIPE)
+	out_parts=[];err_parts=[]
+	err_buf="";total=None;current=0;leftover=""
+	t0=time.perf_counter();last_disp=0.0
+	lock=threading.Lock();pending_stderr=[]
+	def on_stdout(text):
+		nonlocal current,leftover
+		buf=leftover+text
+		for m in re.finditer(r"\[(\d+)\]",buf):
+			n=int(m.group(1))
+			if n>current:current=n
+		leftover=buf[-8:]
+	def on_stderr(text):
+		nonlocal total,err_buf
+		err_buf+=text
+		if total is None:
+			m=re.search(r"computing over (\d+) chunks",err_buf)
+			if m:total=int(m.group(1))
+		while "\n" in err_buf:
+			line,err_buf=err_buf.split("\n",1)
+			line=line.strip()
+			if line:pending_stderr.append(line)
+	def drain(stream,bufs,cb=None):
+		while True:
+			try:chunk=stream.read1(128)
+			except Exception:break
+			if not chunk:break
+			text=chunk.decode("utf-8",errors="replace")
+			bufs.append(text)
+			if cb:cb(text)
+	th_out=threading.Thread(target=drain,args=(proc.stdout,out_parts,on_stdout),daemon=True)
+	th_err=threading.Thread(target=drain,args=(proc.stderr,err_parts,on_stderr),daemon=True)
+	th_out.start();th_err.start()
+	while proc.poll() is None:
+		time.sleep(1.0)
+		now=time.perf_counter()
+		with lock:
+			while pending_stderr:
+				sys.stdout.write("\r"+" "*100+"\r");sys.stdout.flush()
+				print(f"  {pending_stderr.pop(0)}")
+			if now-last_disp>=1.0:
+				last_disp=now
+				el=now-t0
+				if total and current>0:
+					pct=current/total*100
+					speed=current/el if el>0 else 0
+					rem=(total-current)/speed if speed>0 else 0
+					msg=f"  [{current}/{total}] {pct:5.1f}% · {el/60:.1f} min elapsed · ETA {rem/60:.1f} min   "
+				elif current>0:
+					msg=f"  [{current} chunks processed] · {el/60:.1f} min   "
+				else:
+					msg=f"  ⏳ Running... {el/60:.1f} min   "
+				sys.stdout.write("\r"+msg);sys.stdout.flush()
+	proc.wait()
+	th_out.join(timeout=5);th_err.join(timeout=5)
+	with lock:
+		while pending_stderr:
+			print(f"  {pending_stderr.pop(0)}")
+		sys.stdout.write("\r"+" "*100+"\r");sys.stdout.flush()
+	el=time.perf_counter()-t0
+	print(f"  Finished in {el/60:.1f} min")
+	return proc.returncode,"".join(out_parts),"".join(err_parts)
+
+def step_imatrix(calib_path):
+	print("\n"+"="*72)
+	print(" 🧮 STEP 4/4 — IMATRIX CALCULATION (imatrix.dat)")
+	print("="*72)
+	global BF16
+	print(f"  Calibration source: {calib_path}")
+	if not os.path.exists(calib_path) or os.path.getsize(calib_path)<10240:
+		sys.exit(f"❌ Calibration dataset missing or undersized: {calib_path}")
+	if not os.path.exists(BF16):
+		sys.exit("❌ model-BF16.gguf (or -F16) not found in gguf root directory.")
+	imatrix_exe=os.path.join(LLAMA,"llama-imatrix.exe")
+	if not os.path.exists(imatrix_exe):
+		sys.exit(f"❌ Binary not found: {imatrix_exe}")
+	if os.path.exists(IMATRIX):
+		print(f"[IMATRIX] Reusing existing {IMATRIX}")
+		return
+	gpu_total=gpu_used=0
+	try:
+		r=subprocess.run(["nvidia-smi","--query-gpu=memory.total,memory.used","--format=csv,noheader,nounits"],capture_output=True,text=True,timeout=5)
+		parts=r.stdout.strip().split("\n")[0].split(",")
+		gpu_total=int(parts[0].strip());gpu_used=int(parts[1].strip())
+	except Exception:pass
+	gpu_free=max(0,gpu_total-gpu_used)
+	ngl=0
+	arch,n_layers,file_mb=read_gguf_meta(BF16)
+	recurrent=bool(arch) and any(h in arch.lower() for h in RECURRENT_HINT)
+	sized_new=None
+	if recurrent and gpu_free:
+		sized,sized_created=ensure_gpu_sized_model(BF16,gpu_free,900,1024)
+		if sized!=BF16:
+			if sized_created:sized_new=sized
+			BF16=sized
+			arch,n_layers,file_mb=read_gguf_meta(BF16)
+	print(f"  Model: arch={arch or '?'}  layers={n_layers or '?'}  size={file_mb/1024:.1f} GB"+("  [recurrent/hybrid]" if recurrent else ""))
+	try:help_txt=subprocess.run([imatrix_exe,"-h"],capture_output=True,text=True,timeout=10).stdout
+	except Exception:help_txt=""
+	extra=[]
+	if "--flash-attn" in help_txt:extra+=["-fa","on"]
+	if "--process-output" in help_txt:extra+=["--process-output"]
+	if "--output-frequency" in help_txt or "-ofreq" in help_txt:extra+=["--output-frequency","100"]
+	extra_bench=list(extra)
+	if "--no-ppl" in help_txt:extra_bench+=["--no-ppl"]
+	OVERHEAD=900
+	def compute_est(ub):return max(384,ub)
+	candidates=[]
+	if gpu_free and n_layers:
+		headroom=gpu_free-file_mb-OVERHEAD
+		if headroom>0:
+			ngl=n_layers+1
+			ubs=[ub for ub in(2048,1024) if compute_est(ub)<=headroom] or [1024]
+			candidates+=[(ngl,ub) for ub in ubs]
+			for frac in(0.9,0.75,0.5):
+				lower=int(n_layers*frac)
+				if 0<lower<ngl:candidates.append((lower,1024))
+			print(f"  Free VRAM {gpu_free} MiB → FULL GPU offload ({ngl} layers), margin {headroom:.0f} MiB → candidate ubatch {ubs}")
+		else:
+			avail_mb=max(0,gpu_free-OVERHEAD-compute_est(1024))
+			mb_per_layer=(file_mb/n_layers) if n_layers else 380
+			ngl=int(avail_mb/mb_per_layer) if mb_per_layer>0 else 0
+			if n_layers:ngl=min(ngl,n_layers)
+			print(f"  Free VRAM {gpu_free} MiB → budget {avail_mb} MiB / {mb_per_layer:.0f} MiB per layer → max {ngl}/{n_layers or '?'} layers")
+			if ngl>0:
+				step=max(1,(ngl+5)//6)
+				for layers in range(ngl,0,-step):
+					ubs=(2048,1024) if layers==ngl else(1024,512)
+					for ub in ubs:candidates.append((layers,ub))
+			else:
+				print("  → Insufficient VRAM for GPU layers; defaulting to CPU mode")
+	else:
+		print("  VRAM unavailable → defaulting to CPU mode")
+	candidates.append((0,1024))
+	seen=set();candidates=[c for c in candidates if not(c in seen or seen.add(c))]
+	force_cpu=any(a in sys.argv[1:] for a in("--cpu-only","--no-hybrid-split"))
+	if recurrent and n_layers and any(0<l<n_layers for l,_ in candidates):
+		if force_cpu:
+			print("  ℹ --cpu-only: skipping GPU split; computing activation caches entirely on CPU")
+			candidates=[c for c in candidates if c[0]==0] or [(0,1024)]
+		else:
+			print(f"  ℹ Hybrid/recurrent (GDN): testing {ngl}/{n_layers} layer split; verifying PPL at completion")
+			print("    Automatic CPU fallback triggers if PPL exceeds threshold. Force CPU with --cpu-only")
+	def build_cmd(layers,ubatch,out,flags=None):
+		cmd=[imatrix_exe,"-m",BF16,"-f",calib_path,"-o",out,"-t","12","-c","512","-b",str(max(2048,ubatch)),"-ub",str(ubatch)]+(flags if flags is not None else extra)
+		if layers>0:cmd+=["-ngl",str(layers)]
+		return cmd
+	benchmarks=[]
+	failed=set()
+	best_time=None
+	best_profile=None
+	gpu_cands=[c for c in candidates if c[0]>0]
+	if not gpu_cands:
+		print("\nSkipping GPU autotune (no eligible GPU candidates).")
+	else:
+		print("\nAutotuning GPU parameters over 12 chunks…")
+	for layers,ubatch in gpu_cands:
+		bench_out=os.path.join(DATA,f"_bench_ngl{layers}_ub{ubatch}.dat")
+		started=time.perf_counter()
+		result=subprocess.run(build_cmd(layers,ubatch,bench_out,extra_bench)+["--chunks","12"],stdout=subprocess.DEVNULL,stderr=subprocess.DEVNULL)
+		elapsed=time.perf_counter()-started
+		if os.path.exists(bench_out):
+			try:os.remove(bench_out)
+			except OSError:pass
+		if result.returncode!=0:
+			failed.add((layers,ubatch))
+			print(f"    ngl={layers:2d} · ubatch={ubatch:4d} → FAILED (OOM/VRAM) — candidate discarded")
+			continue
+		benchmarks.append((elapsed,layers,ubatch))
+		if best_profile is None or elapsed<best_time:
+			best_time=elapsed
+			best_profile=(layers,ubatch)
+			print(f"    ngl={layers:2d} · ubatch={ubatch:4d} → {elapsed:.1f} s ★ best candidate")
+		else:
+			print(f"    ngl={layers:2d} · ubatch={ubatch:4d} → {elapsed:.1f} s")
+		if elapsed>best_time*1.02:
+			print(f"    ↑ Regression > 2% vs {best_time:.1f} s → Stopping autotune; selected: ngl={best_profile[0]} · ubatch={best_profile[1]}")
+			break
+	if recurrent and best_profile is not None and best_time is not None and n_layers:
+		full=[b for b in benchmarks if b[1]>n_layers]
+		if full and best_profile[0]<=n_layers and full[0][0]<=best_time*1.05:
+			best_profile=(full[0][1],full[0][2])
+			print(f"  ℹ  Preferring full offload ({full[0][0]:.1f} s ≈ best) — avoids GDN split overhead")
+	if best_profile is None:
+		best_profile=(0,1024)
+		print("  No candidate fits VRAM cleanly → using CPU mode (ngl=0)")
+	ngl,best_ubatch=best_profile
+	print(f"  Final profile: ngl={ngl} · batch={max(2048,best_ubatch)} · ubatch={best_ubatch}")
+	profiles=[best_profile]
+	for profile in candidates:
+		if profile not in profiles and profile not in failed:
+			profiles.append(profile)
+	for attempt,(layers,ubatch) in enumerate(profiles,1):
+		print(f"  Attempt {attempt}/{len(profiles)}: {layers} GPU layers, ubatch {ubatch}")
+		rc,stdout_text,stderr_text=run_imatrix_streaming(build_cmd(layers,ubatch,IMATRIX))
+		if rc==0:
+			m=re.search(r"Final estimate:\s*PPL\s*=\s*([0-9.]+)",stdout_text+"\n"+stderr_text,re.I)
+			ppl=float(m.group(1)) if m else None
+			if ppl is None:
+				print("  Final PPL: unreported (binary compiled without --ppl support)")
+			elif ppl<PPL_CEILING or layers==0:
+				print(f"  Final PPL: {ppl:.2f}  ✓ imatrix healthy")
+			else:
+				print(f"  Final PPL: {ppl:.2f}  ⚠ > {PPL_CEILING} → GDN split issue suspected, restarting on CPU")
+				if os.path.exists(IMATRIX):
+					try:os.remove(IMATRIX)
+					except OSError:pass
+				profiles.append((0,1024))
+				continue
+			if sized_new and os.path.exists(sized_new):
+				try:
+					os.remove(sized_new)
+					print(f"  🧹 Temporary intermediate removed: {os.path.basename(sized_new)}")
+				except OSError:pass
+			print(f"[OK] {IMATRIX}")
+			break
+		if os.path.exists(IMATRIX):
+			try:os.remove(IMATRIX)
+			except OSError:pass
+	else:
+		sys.exit("❌ llama-imatrix failed across all candidate profiles.")
+
+# ═══════════════════════════════════════════════════════════════════════════
+#  MAIN
+# ═══════════════════════════════════════════════════════════════════════════
+def main():
+	t0=time.perf_counter()
+	global BF16
+	print("="*72)
+	print(" 🚀 IMATRIX & CALIBRATION DATASET PIPELINE")
+	print("="*72)
+	force_rebuild=any(a in sys.argv[1:] for a in("--force-rebuild","--rebuild"))
+	explicit_dataset_only=any(a in sys.argv[1:] for a in("--dataset-only","--text-only","--build-dataset"))
+	use_experimental=any(a in sys.argv[1:] for a in("--experimental","--exp"))
+	calib_file=None
+	for arg in sys.argv[1:]:
+		if arg.lower().endswith(".gguf"):
+			if os.path.exists(arg):BF16=os.path.abspath(arg)
+			elif os.path.exists(os.path.join(ROOT,arg)):BF16=os.path.join(ROOT,arg)
+		elif arg.lower().endswith(".txt"):
+			for cand in(arg,os.path.join(DATA,arg),os.path.join(ROOT,arg)):
+				if os.path.exists(cand) and not force_rebuild:
+					calib_file=os.path.abspath(cand)
+					break
+	has_gguf=os.path.exists(BF16)
+	if use_experimental or(calib_file and os.path.abspath(calib_file)==os.path.abspath(EXPERIMENTAL_CALIB)):
+		if not os.path.exists(EXPERIMENTAL_CALIB) or force_rebuild:
+			if force_rebuild and os.path.exists(EXPERIMENTAL_CALIB):
+				try:os.remove(EXPERIMENTAL_CALIB)
+				except OSError:pass
+			step_download()
+			step_normalize()
+			step_calibrate()
+		if not calib_file:
+			calib_file=EXPERIMENTAL_CALIB
+	else:
+		ensure_default_calibration()
+		if not calib_file:
+			calib_file=DEFAULT_CALIB_PATH
+	if not has_gguf or explicit_dataset_only:
+		elapsed=time.perf_counter()-t0
+		print("\n"+"="*72)
+		print(" ✅ DATASET PREPARATION COMPLETE")
+		print("="*72)
+		print(f"  Total time:  {elapsed/60:.1f} min")
+		if os.path.exists(DEFAULT_CALIB_PATH):
+			print(f"  Standard:    {DEFAULT_CALIB_NAME} ({os.path.getsize(DEFAULT_CALIB_PATH)/1024/1024:.2f} MB)")
+		if os.path.exists(EXPERIMENTAL_CALIB):
+			print(f"  Expert:      experimental.txt ({os.path.getsize(EXPERIMENTAL_CALIB)/1024/1024:.2f} MB)")
+		print("="*72)
+		return
+	step_strip_mtp()
+	step_imatrix(calib_file)
+	elapsed=time.perf_counter()-t0
+	print("\n"+"="*72)
+	print(" ✅ PIPELINE COMPLETE — SUMMARY")
+	print("="*72)
+	print(f"  Total time:      {elapsed/60:.1f} min")
+	if os.path.exists(calib_file):
+		print(f"  Calib source:    {os.path.basename(calib_file)} ({os.path.getsize(calib_file)/1024/1024:.2f} MB)")
+	if os.path.exists(IMATRIX):
+		print(f"  imatrix.dat:     {os.path.getsize(IMATRIX)/1024/1024:.2f} MB")
+
+if __name__=="__main__":
+	main()

01b_BF16-GGUF-modules-fusion.py

@@ -0,0 +1,145 @@
+#!/usr/bin/env python
+r"""01b_BF16-GGUF-modules-fusion.py — Merge multiple GGUF files into one.
+
+Reads 2+ GGUF files (e.g. model + mmproj + mtp) via gguf-py, deduplicates
+tensor names and metadata keys (first file wins), and writes a single
+fused GGUF.
+
+Usage:
+	python 01b_BF16-GGUF-modules-fusion.py out.gguf main.gguf mmproj.gguf [extra.gguf ...]
+	# Or drag-and-drop 2+ .gguf files onto this script:
+	# -> writes fused-<first-file>.gguf next to the inputs.
+"""
+import os,re,shutil,sys
+
+SCRIPT_DIR=os.path.dirname(os.path.abspath(__file__))
+LLAMA_CPP=os.path.join(SCRIPT_DIR,"llama-cpp")
+sys.path.insert(0,os.path.join(LLAMA_CPP,"gguf-py"))
+import gguf
+
+def size_str(path):
+	mb=os.path.getsize(path)/(1024*1024)
+	return f"{mb/1024:.2f} GB" if mb>=1024 else f"{mb:.0f} MiB"
+
+def field_value(field):
+	if hasattr(field,"contents"):
+		return field.contents()
+	t=field.types[0]
+	if t==gguf.GGUFValueType.ARRAY:
+		sub=field.types[-1]
+		return [field.parts[i].tolist()[0] if sub!=gguf.GGUFValueType.STRING else bytes(field.parts[i].tolist()).decode() for i in field.data]
+	v=field.parts[-1].tolist()
+	if t==gguf.GGUFValueType.STRING:
+		return bytes(v).decode("utf-8")
+	return v[0] if isinstance(v,list) else v
+
+SCALAR_WRITERS={
+	gguf.GGUFValueType.UINT8:"add_uint8",gguf.GGUFValueType.INT8:"add_int8",
+	gguf.GGUFValueType.UINT16:"add_uint16",gguf.GGUFValueType.INT16:"add_int16",
+	gguf.GGUFValueType.UINT32:"add_uint32",gguf.GGUFValueType.INT32:"add_int32",
+	gguf.GGUFValueType.FLOAT32:"add_float32",gguf.GGUFValueType.UINT64:"add_uint64",
+	gguf.GGUFValueType.INT64:"add_int64",gguf.GGUFValueType.FLOAT64:"add_float64",
+	gguf.GGUFValueType.BOOL:"add_bool",gguf.GGUFValueType.STRING:"add_string",
+}
+
+def copy_field(writer,key,field):
+	t=field.types[0]
+	val=field_value(field)
+	if t==gguf.GGUFValueType.ARRAY:
+		# add_array rejects empty lists — skip rather than abort fusion
+		if not val:
+			print(f"  ! empty array skipped: {key}")
+			return
+		writer.add_array(key,val)
+	else:
+		getattr(writer,SCALAR_WRITERS[t])(key,val)
+
+def parse_args(argv):
+	if len(argv)>=2 and all(p.lower().endswith(".gguf") for p in argv):
+		first=os.path.abspath(argv[0])
+		out=os.path.join(os.path.dirname(first),"fused-"+os.path.basename(first))
+		return out,argv
+	if len(argv)>=3:
+		return argv[0],argv[1:]
+	return None,None
+
+def main():
+	out_arg,inputs=parse_args(sys.argv[1:])
+	if out_arg is None:
+		print("Usage: python 01b_BF16-GGUF-modules-fusion.py <out.gguf> <main.gguf> <extra.gguf> [...]")
+		print("   or: drag-and-drop 2+ .gguf files onto this script")
+		return 1
+	out_path=os.path.abspath(out_arg)
+	in_paths=[os.path.abspath(p) for p in inputs]
+	for p in in_paths:
+		if not os.path.isfile(p):
+			print(f"Error: file not found: {p}")
+			return 1
+	if out_path in in_paths:
+		print("Error: output must differ from inputs.")
+		return 1
+	print("="*64)
+	print("  GGUF fusion")
+	print("="*64)
+	for p in in_paths:
+		print(f" - {os.path.basename(p)} ({size_str(p)})")
+	readers=[]
+	for p in in_paths:
+		r=gguf.GGUFReader(p)
+		readers.append(r)
+		arch_field=r.fields.get("general.architecture")
+		print(f"    arch={field_value(arch_field) if arch_field else '?'}  "
+			f"tensors={len(r.tensors)}  metadata={len(r.fields)} keys")
+	arch_field=readers[0].fields.get("general.architecture")
+	arch=field_value(arch_field) if arch_field else "llama"
+	for p,r in zip(in_paths,readers):
+		af=r.fields.get("general.architecture")
+		a=field_value(af) if af else "?"
+		if a!=arch:print(f"  ! arch mismatch: {os.path.basename(p)} declares '{a}' (fusion base '{arch}')")
+	writer=gguf.GGUFWriter(None,arch)
+	WRITER_KEYS={"general.architecture","general.alignment"}
+	# Derive true layer count from union of blk.N indices to prevent truncating merged heads
+	blk_max=-1
+	for r in readers:
+		for t in r.tensors:
+			if(m:=re.match(r"blk\.(\d+)\.",t.name)):
+				blk_max=max(blk_max,int(m.group(1)))
+	seen_kv,kv_skipped=set(),0
+	for r in readers:
+		for key,field in r.fields.items():
+			if key in seen_kv or key in WRITER_KEYS or key.startswith("GGUF."):
+				kv_skipped+=1
+				continue
+			seen_kv.add(key)
+			if key.endswith(".block_count") and blk_max>=0:
+				declared=field_value(field)
+				if isinstance(declared,int) and declared<blk_max+1:
+					print(f"  ! block_count {declared} → {blk_max+1} (MTP head merged)")
+					writer.add_uint32(key,blk_max+1)
+					continue
+			copy_field(writer,key,field)
+	seen_t,t_skipped=set(),0
+	for r in readers:
+		for t in r.tensors:
+			if t.name in seen_t:
+				t_skipped+=1
+				print(f"  ! duplicate tensor skipped: {t.name}")
+				continue
+			seen_t.add(t.name)
+			writer.add_tensor(t.name,t.data,raw_dtype=t.tensor_type)
+	print(f"\n  Merging: {len(seen_t)} tensors, {len(seen_kv)} metadata keys")
+	if kv_skipped or t_skipped:
+		print(f"  Skipped duplicates: {kv_skipped} metadata, {t_skipped} tensors")
+	writer.write_header_to_file(path=out_path)
+	writer.write_kv_data_to_file()
+	writer.write_tensors_to_file(progress=True)
+	writer.close()
+	sidecar=next((os.path.splitext(p)[0]+".provenance.json" for p in in_paths if os.path.isfile(os.path.splitext(p)[0]+".provenance.json")),None)
+	if sidecar:shutil.copy2(sidecar,os.path.splitext(out_path)[0]+".provenance.json")
+	print(f"\n  ✓ {os.path.basename(out_path)} ({size_str(out_path)})")
+	print("  Tip: rename to model-<SUF>.gguf for auto-discovery by 01/02, or pass it as an argument.")
+	print("="*64)
+	return 0
+
+if __name__=="__main__":
+	raise SystemExit(main())

02_BF16-GGUF-to-ASHQ1.py

@@ -0,0 +1,206 @@
+#!/usr/bin/env python3
+r"""02_BF16-GGUF-to-ASHQ1.py — Automated ASHQ1 orchestrator.
+
+Execution order: modules (mmproj, MTP…) → tiers Mini → Quality → Nano.
+On AutoRound int4 lineage (provenance), Fidelity is skipped by default —
+information ceiling reached at Quality — and modules use Quality
+(override: ASHQ1_INCLUDE_FIDELITY=1).
+The COMPLETE model (including MTP head) is preferred over the no-mtp trunk:
+ASHQ1 keeps the nextn layer at Q8_0 (Q6_K on int4 lineage) and excludes it from the size budget.
+Final naming: model-AutoRound-ASHQ1-Compact-30pc.gguf (AutoRound lineage detected
+via step 00 sidecar), model-ASHQ1-…-NNpc.gguf otherwise; mmproj-ASHQ1-Balanced-NNpc.gguf
+(pct relative to source mmproj).
+Lineage override: ASHQ1_LINEAGE=autoround|plain.
+"""
+import os,re,sys,subprocess
+
+SCRIPT_DIR=os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0,SCRIPT_DIR)
+sys.path.insert(0,os.path.join(SCRIPT_DIR,"llama-cpp","gguf-py"))
+from ASHQ1 import ALL_RATIOS,int4_lineage_of,lineage_tag,tier_label
+
+MAIN_TIERS=["mini","compact","quality","fidelity"]
+# Longest running and least used: executed last
+LAST_TIER="nano"
+MODULE_PROFILES={"mtp":"fidelity","dspark":"fidelity"}
+INT4_MODULE_PROFILES={"mtp":"quality","dspark":"quality"}
+
+def find_file_case_insensitive(directory,filename):
+	for f in os.listdir(directory):
+		if f.lower()==filename.lower():return os.path.join(directory,f)
+	return None
+
+def _file_mib(path):
+	return os.path.getsize(path)/1024/1024
+
+def _pick_main(base_dir):
+	for name in("model-BF16.gguf","model-F16.gguf","model-no-mtp-BF16.gguf","model-BF16-no-mtp.gguf","model-no-mtp-F16.gguf","model-F16-no-mtp.gguf"):
+		hit=find_file_case_insensitive(base_dir,name)
+		if hit:return hit
+	return None
+
+def _gguf_has_nextn(path):
+	try:
+		import gguf
+		return any("nextn" in t.name or "eh_proj" in t.name for t in gguf.GGUFReader(path).tensors)
+	except Exception:
+		return False
+
+def _pick_imatrices(base_dir):
+	# All .dat/.imatrix files are merged via max reduction (cHunter789 recipe: mixing mradermacher+ubergarm > bartowski alone). imatrix.dat takes precedence; _bench drafts are excluded
+	out=[]
+	primary=find_file_case_insensitive(base_dir,"imatrix.dat")
+	if primary:out.append(primary)
+	for f in sorted(os.listdir(base_dir)):
+		fl=f.lower()
+		if fl.startswith("_bench") or not fl.endswith((".dat",".imatrix")):continue
+		p=os.path.join(base_dir,f)
+		if p not in out:out.append(p)
+	return out
+
+def _clean_base(basename):
+	clean=basename
+	for s in("-no-mtp-BF16.gguf","-no-mtp-F16.gguf","-BF16-no-mtp.gguf","-F16-no-mtp.gguf","-BF16.gguf","-F16.gguf","-bf16.gguf","-f16.gguf",".gguf"):
+		if clean.lower().endswith(s.lower()):
+			clean=clean[:-len(s)]
+			break
+	return clean
+
+def process_model(base_dir,ashq1_script,imatrix,model_path,tiers_list):
+	ok=True
+	basename=os.path.basename(model_path)
+	clean_base=_clean_base(basename)
+	lineage=os.environ.get("ASHQ1_LINEAGE","auto")
+	tag=lineage_tag(model_path,lineage)
+	print(f"\n{'='*60}")
+	print(f" Processing: {basename}  [{tag}]")
+	print(f"{'='*60}")
+	for tier in tiers_list:
+		label=tier_label(tier)
+		pct=round(ALL_RATIOS.get(tier.lower(),0)*100)
+		new_name=f"{clean_base}-{tag}-{label}-{pct}pc.gguf"
+		new_file=os.path.join(base_dir,new_name)
+		if os.path.isfile(new_file):
+			print(f"  -> Already exists, skipping: {new_name}")
+			continue
+		cmd=[sys.executable,ashq1_script,"--model",model_path,"--tier",tier.lower(),"--output-dir",base_dir,"--run","--lineage","autoround" if tag=="AutoRound-ASHQ1" else "plain"]
+		for p in imatrix or []:cmd+=["--imatrix",p]
+		if subprocess.run(cmd,cwd=base_dir).returncode or not os.path.isfile(new_file):
+			print(f"  -> Tier {label} failed")
+			ok=False
+			continue
+		print(f"  -> Ready: {new_name}")
+	return ok
+
+def process_optional_modules(base_dir,ashq1_script,imatrix,main_basename,main_has_nextn,profiles=None):
+	if main_has_nextn:
+		print("\n  [MTP] nextn head already embedded in the main model — separate quantization not needed.")
+		return
+	for opt_name,profile in(profiles or MODULE_PROFILES).items():
+		opt_file=None
+		for f in sorted(os.listdir(base_dir)):
+			fl=f.lower()
+			if fl==main_basename or "ashq1" in fl:continue
+			if opt_name in fl and "no-mtp" not in fl and ("bf16" in fl or "f16" in fl) and fl.endswith(".gguf"):
+				opt_file=os.path.join(base_dir,f)
+				break
+		if opt_file:process_model(base_dir,ashq1_script,imatrix,opt_file,[profile])
+
+def process_mmproj(base_dir):
+	src=None
+	for name in("mmproj-BF16.gguf","mmproj-F16.gguf","mmproj-bf16.gguf","mmproj-f16.gguf"):
+		hit=find_file_case_insensitive(base_dir,name)
+		if hit:src=hit;break
+	if not src:
+		cands=[]
+		for f in os.listdir(base_dir):
+			fl=f.lower()
+			if "mmproj" not in fl or not fl.endswith(".gguf"):continue
+			if "ashq1" in fl or "-to-" in fl:continue
+			cands.append(f)
+		if cands:
+			cands.sort()
+			src=os.path.join(base_dir,cands[0])
+	if not src:return False
+	f=os.path.basename(src)
+	script=os.path.join(base_dir,"ASHQ1-mmproj.py")
+	if not os.path.isfile(script):script=os.path.join(base_dir,"ASHQ1-MMPROJ.py")
+	if not os.path.isfile(script):
+		print(f"\n  [INFO] ASHQ1-mmproj.py not found — skipping {f}.")
+		return False
+	src_mib=_file_mib(src)
+	dry=subprocess.run([sys.executable,script,"--model",src,"--profile","balanced","--dry-run"],capture_output=True,text=True,cwd=base_dir)
+	m=re.search(r"(?:Target|Cible)\s*(?:\(tensors\)|\(tenseurs\))?\s*:\s*([0-9.]+)\s*MiB",dry.stdout,re.I)
+	dst_mib=float(m.group(1)) if m else src_mib*0.72
+	pct=round(dst_mib/src_mib*100) if src_mib>0 else 100
+	# The vision tower stays outside the AutoRound grid (quant_nontext_module=False): its tag follows its own sidecar, never the global text model override
+	tag=lineage_tag(src,"auto")
+	# Final naming template: mmproj-ASHQ1-Balanced-72pc.gguf (percentage relative to source mmproj)
+	out=os.path.join(base_dir,f"mmproj-{tag}-Balanced-{pct}pc.gguf")
+	if os.path.isfile(out):
+		print(f"\n  -> Already exists, skipping: {os.path.basename(out)}")
+		return True
+	print(f"\n{'='*60}")
+	print(f" Processing mmproj: {f}  [{tag}]")
+	print(f"{'='*60}")
+	if subprocess.run([sys.executable,script,"--model",src,"--profile","balanced","--output",out],cwd=base_dir).returncode==0:
+		print(f"  -> mmproj quantized: {os.path.basename(out)}")
+		return True
+	return False
+
+def main():
+	base_dir=SCRIPT_DIR
+	ashq1_script=os.path.join(base_dir,"ASHQ1.py")
+	if not os.path.isfile(ashq1_script):
+		print("Error: ASHQ1.py not found in the current directory.")
+		sys.exit(1)
+	if len(sys.argv)>1 and sys.argv[1].lower().endswith(".gguf"):
+		main_model=os.path.abspath(sys.argv[1])
+	else:
+		main_model=_pick_main(base_dir)
+	has_main_model=main_model and os.path.isfile(main_model)
+	if has_main_model:
+		from ASHQ1 import _find_binary
+		if not _find_binary("llama-quantize"):
+			print("Error: llama-quantize binary not found.")
+			sys.exit(1)
+	imatrix=_pick_imatrices(base_dir)
+	if has_main_model and not imatrix:
+		print("No imatrix (.dat) found. Run 01_create-calibration-dataset-and-imatrix.py first.")
+		sys.exit(1)
+	if len(imatrix)>1:
+		print(f"  ℹ  {len(imatrix)} imatrix file(s) merged (max method): {', '.join(os.path.basename(p) for p in imatrix)}")
+
+	int4_lineage=int4_lineage_of(main_model) if has_main_model else False
+	if int4_lineage and os.environ.get("ASHQ1_INCLUDE_FIDELITY")!="1":
+		main_tiers=[t for t in MAIN_TIERS if t!="fidelity"]
+		module_profiles=INT4_MODULE_PROFILES
+		print("\n  ℹ  AutoRound int4 lineage detected — Fidelity skipped (information ceiling reached), modules set to Quality. Set ASHQ1_INCLUDE_FIDELITY=1 to override.")
+	else:
+		main_tiers=MAIN_TIERS
+		module_profiles=MODULE_PROFILES
+	# 1) Modules first: mmproj, then standalone MTP/dspark heads
+	mmproj_processed=process_mmproj(base_dir)
+	main_has_nextn=_gguf_has_nextn(main_model) if has_main_model else False
+	success=True
+	if has_main_model:
+		process_optional_modules(base_dir,ashq1_script,imatrix,os.path.basename(main_model).lower(),main_has_nextn,module_profiles)
+		if not process_model(base_dir,ashq1_script,imatrix,main_model,main_tiers):success=False
+		if not process_model(base_dir,ashq1_script,imatrix,main_model,[LAST_TIER]):success=False
+
+	print("\n"+"="*60)
+	if has_main_model:
+		print(" ASHQ1 pipeline completed "+("successfully!" if success else "with ERRORS (see tier logs above).")+" "+("(exit 2)" if not success else ""))
+		if success:
+			print("  ℹ  Recommended runtime settings: --cache-type-k q4_0 --cache-type-v q4_0 maximizes context length efficiency (cHunter789 recipe)")
+		if not success:sys.exit(2)
+	elif mmproj_processed:
+		print(" ASHQ1 mmproj generated.")
+	else:
+		print(" No model or mmproj found in current folder.")
+		print("="*60)
+		sys.exit(1)
+	print("="*60)
+
+if __name__=="__main__":
+	main()

ASHQ1-mmproj.py

@@ -0,0 +1,273 @@
+#!/usr/bin/env python3
+"""ASHQ1-MMPROJ — Non-uniform quantization for CLIP/mmproj GGUF files."""
+import argparse,os,sys
+import numpy as np
+import gguf
+from gguf.constants import GGMLQuantizationType as QT
+
+BLOCK_ALIGN={
+	QT.Q4_K:256,QT.Q5_K:256,QT.Q6_K:256,
+	QT.Q8_0:32,QT.Q5_0:32,QT.Q4_0:32,
+	QT.F16:1,QT.F32:1,QT.BF16:1,
+}
+
+QT_BLOCK={
+	QT.Q4_K:(256,144),QT.Q5_K:(256,176),QT.Q6_K:(256,210),
+	QT.Q8_0:(32,34),QT.Q5_0:(32,22),QT.Q4_0:(32,18),
+}
+
+TIER_TO_QT={
+	"F32":QT.F32,"F16":QT.F16,"BF16":QT.BF16,
+	"Q8_0":QT.Q8_0,"Q6_K":QT.Q6_K,"Q5_K":QT.Q5_K,"Q4_K":QT.Q4_K,
+}
+
+BPW={
+	"F32":32.0,"F16":16.0,"BF16":16.0,
+	"Q8_0":8.5,"Q6_K":6.5625,"Q5_K":5.5,"Q4_K":4.5,
+}
+
+CRITICAL=(
+	"patch_embd","position_embd","mm.0","mm.1","mm.2",
+	"pre_ln","post_ln","ln1","ln2","ln_q","norm",
+)
+
+PROFILES={
+	"balanced":{
+		"attn_qkv":"Q6_K","attn_out":"Q6_K",
+		"ffn_up":"Q6_K","ffn_down":"Q6_K",
+		"critical":"F32","default":"Q8_0",
+	},
+	"compact":{
+		"attn_qkv":"Q5_K","attn_out":"Q5_K",
+		"ffn_up":"Q5_K","ffn_down":"Q5_K",
+		"critical":"F32","default":"Q8_0",
+	},
+	"fidelity":{
+		"attn_qkv":"Q8_0","attn_out":"Q8_0",
+		"ffn_up":"Q8_0","ffn_down":"Q8_0",
+		"critical":"F32","default":"F16",
+	},
+}
+
+UPGRADE_CHAIN={"Q4_K":"Q5_K","Q5_K":"Q6_K","Q6_K":"Q8_0","Q8_0":"F16"}
+
+FILE_TYPE_NAME={
+	"F32":"ALL_F32","F16":"MOSTLY_F16","BF16":"MOSTLY_BF16",
+	"Q8_0":"MOSTLY_Q8_0","Q6_K":"MOSTLY_Q6_K","Q5_K":"MOSTLY_Q5_K_M","Q4_K":"MOSTLY_Q4_K_M",
+}
+
+def is_critical(name:str)->bool:
+	low=name.lower()
+	return any(c in low for c in CRITICAL)
+
+def tensor_role(name:str)->str:
+	parts=name.split(".")
+	if len(parts)>=4 and parts[0]=="v" and parts[1]=="blk":
+		return parts[3]
+	return name
+
+def block_index(name:str):
+	parts=name.split(".")
+	if len(parts)>=3 and parts[0]=="v" and parts[1]=="blk":
+		try:return int(parts[2])
+		except ValueError:return None
+	return None
+
+def row_length(shape)->int:
+	return int(shape[0]) if len(shape)>0 else 1
+
+def best_quant_fit(shape,tier:str)->str:
+	cur=tier
+	seen=set()
+	while cur not in seen:
+		seen.add(cur)
+		if fits_alignment(shape,cur):return cur
+		nxt=UPGRADE_CHAIN.get(cur)
+		if nxt is None:break
+		cur=nxt
+	return "F16"
+
+def fits_alignment(shape,tier:str)->bool:
+	qt=TIER_TO_QT[tier]
+	align=BLOCK_ALIGN.get(qt,1)
+	if align<=1:return True
+	return row_length(shape) % align==0
+
+def pick_tier(name:str,shape,n_blocks:int,profile:dict,deep_boost:int)->str:
+	if is_critical(name):return profile["critical"]
+	# Keep 1D vectors in F32 (layer scale, bias)
+	if len(shape)<2 or int(np.prod(shape))<4096:return "F32"
+	role=tensor_role(name)
+	tier=profile.get(role,profile["default"])
+	idx=block_index(name)
+	if idx is not None and deep_boost>0 and idx>=n_blocks-deep_boost:
+		tier=UPGRADE_CHAIN.get(tier,tier)
+	tier=best_quant_fit(shape,tier)
+	return "F16" if tier=="BF16" else tier
+
+def _decode(t)->np.ndarray:
+	raw=np.asarray(t.data)
+	name=t.tensor_type.name
+	nshape=tuple(int(d) for d in reversed(t.shape))
+	flat=raw.reshape(-1)
+	if name=="BF16":
+		u=flat.view(np.uint16).astype(np.uint32)<<16
+		return u.view(np.float32).reshape(nshape)
+	if name=="F16":
+		return flat.view(np.float16).astype(np.float32).reshape(nshape)
+	if name=="F32":
+		return flat.view(np.float32).reshape(nshape)
+	return gguf.quants.dequantize(raw,t.tensor_type).astype(np.float32).reshape(nshape)
+
+def quantize_mmproj(src:str,dst:str,profile_name:str,deep_boost:int,dry_run:bool)->bool:
+	profile=PROFILES[profile_name]
+	reader=gguf.GGUFReader(src)
+	arch=None
+	for key,field in reader.fields.items():
+		if key=="general.architecture":
+			arch=str(bytes(field.parts[field.data[0]]),"utf-8")
+			break
+	if arch!="clip":
+		print(f"  [WARN] architecture='{arch}' (clip expected)")
+	n_blocks=0
+	for t in reader.tensors:
+		idx=block_index(t.name)
+		if idx is not None:n_blocks=max(n_blocks,idx+1)
+	print(f"  ViT blocks detected: {n_blocks}")
+	plan=[]
+	src_bits=0.0
+	dst_bits=0.0
+	for t in reader.tensors:
+		shape=list(t.shape)
+		n_el=int(np.prod(shape))
+		tier=pick_tier(t.name,shape,n_blocks,profile,deep_boost)
+		cur_name=t.tensor_type.name
+		if cur_name in BPW and BPW[cur_name]<BPW[tier]:
+			tier=cur_name
+		if cur_name=="BF16" and tier=="BF16":
+			tier="F16"
+		plan.append((t,tier,n_el))
+		src_bits+=n_el*BPW.get(cur_name,32.0)
+		dst_bits+=n_el*BPW[tier]
+	src_mib=src_bits/8/1024/1024
+	dst_mib=dst_bits/8/1024/1024
+	by_tier={}
+	for _,tier,n_el in plan:
+		e=by_tier.setdefault(tier,[0,0.0])
+		e[0]+=1
+		e[1]+=n_el*BPW[tier]/8/1024/1024
+	print("\n  Tier distribution:")
+	for tier in sorted(by_tier,key=lambda x:-BPW[x]):
+		cnt,mib=by_tier[tier]
+		print(f"   {tier:<5}: {cnt:>4} tensor(s) ({mib:>8.1f} MiB)")
+	print(f"\n  Source (tensors) : {src_mib:>8.1f} MiB")
+	print(f"  Target (tensors) : {dst_mib:>8.1f} MiB")
+	print(f"  Reduction        : {(1-dst_mib/src_mib)*100:>7.1f}%")
+	heavy=[(t.name,tier,n*BPW[tier]/8/1024/1024,list(t.shape)) for t,tier,n in plan if BPW[tier]>=16.0 and n*BPW[tier]/8/1024/1024>1.0]
+	if heavy:
+		heavy.sort(key=lambda x:-x[2])
+		print(f"\n  High-precision tensors kept in 16/32-bit ({len(heavy)}):")
+		for name,tier,mib,shape in heavy[:20]:
+			print(f"   {name[:46]:46s} {tier:<5} {mib:>7.1f} MiB shape={shape}")
+	if dry_run:
+		print("\n  Dry run complete — no file written.")
+		return True
+	writer=gguf.GGUFWriter(dst,arch or "clip")
+	skip={"GGUF.version","GGUF.tensor_count","GGUF.kv_count","general.architecture","general.quantization_version","general.file_type"}
+	for key,field in reader.fields.items():
+		if key in skip:continue
+		try:_copy_field(writer,key,field)
+		except Exception as e:print(f"  [WARN] KV '{key}' omitted: {e}")
+	writer.add_quantization_version(2)
+	dominant_tier=max(by_tier,key=lambda t:by_tier[t][1])
+	dominant_name=FILE_TYPE_NAME.get(dominant_tier,"MOSTLY_Q8_0")
+	writer.add_file_type(getattr(gguf.LlamaFileType,dominant_name))
+	for t,tier,_ in plan:
+		data=_decode(t)
+		qt=TIER_TO_QT[tier]
+		if tier=="F32":
+			out=np.ascontiguousarray(data.astype(np.float32))
+			writer.add_tensor(t.name,out)
+			continue
+		if tier=="F16":
+			out=np.ascontiguousarray(data.astype(np.float16))
+			writer.add_tensor(t.name,out)
+			continue
+		if tier=="BF16":
+			out=data.astype(np.float16)
+			writer.add_tensor(t.name,out,raw_dtype=QT.F16)
+			continue
+		try:
+			out=gguf.quants.quantize(data.astype(np.float32),qt)
+		except NotImplementedError:
+			qt=TIER_TO_QT["Q8_0"]
+			out=gguf.quants.quantize(data.astype(np.float32),qt)
+		blk,bsz=QT_BLOCK[qt]
+		nshape=list(data.shape)
+		nshape[-1]=(nshape[-1]//blk)*bsz
+		writer.add_tensor(t.name,out,raw_dtype=qt,raw_shape=nshape)
+	writer.write_header_to_file()
+	writer.write_kv_data_to_file()
+	writer.write_tensors_to_file()
+	writer.close()
+	real=os.path.getsize(dst)/1024/1024
+	print(f"\n  Output: {dst}")
+	print(f"  Actual size: {real:.1f} MiB")
+	drift=real/dst_mib if dst_mib>0 else 0
+	if drift>1.05:
+		print(f"  ⚠  Size divergence ×{drift:.2f}")
+	else:
+		print(f"  ✓ Size matches plan (×{drift:.2f})")
+	return True
+
+def _copy_field(writer,key:str,field):
+	from gguf.constants import GGUFValueType as VT
+	vtype=field.types[0]
+	if vtype==VT.ARRAY:
+		itype=field.types[1]
+		if itype==VT.STRING:
+			vals=[str(bytes(field.parts[i]),"utf-8") for i in field.data]
+		else:
+			vals=[field.parts[i].tolist()[0] for i in field.data]
+		writer.add_array(key,vals)
+		return
+	if vtype==VT.STRING:
+		writer.add_string(key,str(bytes(field.parts[field.data[0]]),"utf-8"))
+		return
+	val=field.parts[field.data[0]].tolist()[0]
+	emit={
+		VT.UINT8:writer.add_uint8,VT.INT8:writer.add_int8,
+		VT.UINT16:writer.add_uint16,VT.INT16:writer.add_int16,
+		VT.UINT32:writer.add_uint32,VT.INT32:writer.add_int32,
+		VT.UINT64:writer.add_uint64,VT.INT64:writer.add_int64,
+		VT.FLOAT32:writer.add_float32,VT.FLOAT64:writer.add_float64,
+		VT.BOOL:writer.add_bool,
+	}
+	fn=emit.get(vtype)
+	if fn is None:raise ValueError(f"Unhandled value type {vtype}")
+	fn(key,val)
+
+def main(args_list=None):
+	p=argparse.ArgumentParser(description="ASHQ1-MMPROJ — Non-uniform quantization for mmproj/CLIP")
+	p.add_argument("--model",required=True,help="Source mmproj GGUF (BF16/F16)")
+	p.add_argument("--output",default=None,help="Output path")
+	p.add_argument("--profile",choices=list(PROFILES),default="balanced")
+	p.add_argument("--deep-boost",type=int,default=3,help="Number of trailing blocks boosted one tier")
+	p.add_argument("--dry-run",action="store_true",help="Show quantization plan without writing")
+	a=p.parse_args(args_list)
+	if not os.path.isfile(a.model):
+		print(f"ERROR: file not found: {a.model}")
+		return 1
+	if not a.output:
+		base=os.path.splitext(os.path.basename(a.model))[0]
+		mm_suffix="F16" if "-F16" in base or "-f16" in base else "BF16"
+		a.output=f"mmproj-{mm_suffix}-to-ASHQ1-{a.profile.capitalize()}.gguf"
+	print("=== ASHQ1-MMPROJ ===")
+	print(f"Source  : {a.model}")
+	print(f"Profile : {a.profile} (deep-boost={a.deep_boost})")
+	print(f"Output  : {a.output}\n")
+	ok=quantize_mmproj(a.model,a.output,a.profile,a.deep_boost,a.dry_run)
+	return 0 if ok else 1
+
+if __name__=="__main__":
+	sys.exit(main())

ASHQ1.py

@@ -0,0 +1,1580 @@
+#!/usr/bin/env python3
+"""ASHQ1 — All-in-One Imatrix-Driven Hybrid Quantization Engine."""
+import argparse,heapq,json,math,os,re,subprocess,sys,warnings
+from bisect import bisect_left
+from collections import defaultdict
+from dataclasses import dataclass,field
+from functools import lru_cache
+from typing import Any,Dict,List,Set,Tuple
+import gguf
+import numpy as np
+
+# ═══════════════════════════════════════════════════════════════════════════
+# 1. CONSTANTS & TENSOR CLASSIFICATION HELPERS
+# ═══════════════════════════════════════════════════════════════════════════
+
+GGUF_TYPE_NAMES={
+	0:"F32",
+	1:"F16",
+	2:"Q4_0",3:"Q4_1",6:"Q5_0",7:"Q5_1",
+	8:"Q8_0",
+	10:"Q2_K",11:"Q3_K",12:"Q4_K",13:"Q5_K",14:"Q6_K",
+	15:"Q8_K",16:"IQ2_XXS",
+	20:"IQ3_XXS",
+	24:"IQ2_XXS",
+	26:"IQ2_XS",
+	28:"IQ2_S",
+	30:"IQ1_S",
+}
+
+GGUF_TYPE_NAMES_INV={v:k for k,v in GGUF_TYPE_NAMES.items()}
+
+# Ordered from lowest to highest precision
+TIER_ORDER=[
+	"IQ1_S","IQ2_XXS","IQ2_XS","IQ2_S",
+	"IQ3_XXS","Q3_K","IQ3_S",
+	"IQ4_XS","IQ4_NL","Q4_K","Q5_K","Q6_K","Q8_0","F16",
+]
+
+# Exact bits per weight from ggml block structs (ggml_type_sizef * 8)
+TIER_BPW={
+	"IQ1_S":1.5625,
+	"IQ2_XXS":2.0625,
+	"IQ2_XS":2.3125,
+	"IQ2_S":2.5,
+	"IQ3_XXS":3.0625,
+	"Q3_K":3.4375,
+	"IQ3_S":3.44,
+	"IQ4_XS":4.25,
+	"IQ4_NL":4.5,
+	"Q4_K":4.5,
+	"Q5_K":5.5,
+	"Q6_K":6.5625,
+	"Q8_0":8.5,
+	"F16":16.0,
+}
+
+OVERHEAD_CACHE="ashq1-overhead.json"
+
+def _overhead_cache_path(model_path:str)->str:
+	return os.path.join(os.path.dirname(os.path.abspath(model_path)),OVERHEAD_CACHE)
+
+def load_overhead_factor(model_path:str)->float:
+	p=_overhead_cache_path(model_path)
+	if os.path.isfile(p):
+		try:
+			with open(p,"r",encoding="utf-8") as f:
+				v=float(json.load(f).get(os.path.basename(model_path),1.0))
+			if 0.9<=v<=1.1:return v
+		except Exception:pass
+	return 1.0
+
+def save_overhead_factor(model_path:str,factor:float):
+	if not(0.9<=factor<=1.1):return
+	p=_overhead_cache_path(model_path)
+	data={}
+	if os.path.isfile(p):
+		try:
+			with open(p,"r",encoding="utf-8") as f:data=json.load(f)
+		except Exception:data={}
+	data[os.path.basename(model_path)]=round(factor,4)
+	try:
+		with open(p,"w",encoding="utf-8") as f:json.dump(data,f,indent=2)
+	except Exception as e:
+		print(f"  [WARN] Overhead cache write failed: {e}")
+
+GGUF_OVERHEAD_FACTOR=1.000
+
+QUANT_RANK={tier:i for i,tier in enumerate(TIER_ORDER)}
+
+# Hard floors per tensor class to guarantee stability across long context
+CLASS_HARD_FLOORS={
+	"gate":"Q5_K",
+	"attn_proj":"IQ3_S",
+	"ffn_gate_up":"IQ2_XXS",
+	"ffn_down":"IQ3_S",
+	"norms":"F16",
+	"ssm_params":"F16",
+	# Recurrent memory state requires Q8_0 to prevent state collapse in long contexts
+	"gdn_state":"Q8_0",
+	"mtp":"Q5_K",
+	"embd":"IQ4_XS",
+	"shexp":"Q4_K",
+}
+
+CLASS_MAX_TIER={
+	"gate":"F16",
+	"attn_proj":"Q8_0",
+	"ffn_gate_up":"F16",
+	"ffn_down":"F16",
+	"norms":"F16",
+	"ssm_params":"F16",
+	"gdn_state":"F16",
+	"mtp":"F16",
+	"embd":"F16",
+	"shexp":"F16",
+}
+
+CAN_Q3={"ffn_gate","ffn_up","ffn_down","attn_output","ssm_out"}
+ALLOW_LOWER_FLOOR="IQ2_XXS"
+DEFAULT_FLOOR="Q4_K"
+
+TIER_FLOORS={
+	"nano":{
+		"gate":"Q6_K",
+		"attn_proj":"IQ3_S",
+		"ffn_gate_up":"IQ2_XXS",
+		"ffn_down":"IQ2_S",
+		"norms":"F16",
+		"ssm_params":"F16",
+		"gdn_state":"Q8_0",
+		"mtp":"IQ4_XS",
+		"embd":"IQ4_XS",
+		"shexp":"Q4_K",
+		"unknown":"IQ3_XXS",
+	},
+	"mini":{
+		"gate":"Q6_K",
+		"attn_proj":"IQ4_XS",
+		"ffn_gate_up":"IQ3_S",
+		"ffn_down":"IQ4_XS",
+		"norms":"F16",
+		"ssm_params":"F16",
+		"gdn_state":"Q8_0",
+		"mtp":"Q5_K",
+		"embd":"IQ4_XS",
+		"shexp":"Q5_K",
+		"unknown":"IQ4_XS",
+	},
+	"compact":{
+		"gate":"Q6_K",
+		"attn_proj":"IQ4_XS",
+		"ffn_gate_up":"IQ3_S",
+		"ffn_down":"IQ4_XS",
+		"norms":"F16",
+		"ssm_params":"F16",
+		"gdn_state":"Q8_0",
+		"mtp":"Q8_0",
+		"embd":"IQ4_XS",
+		"shexp":"Q5_K",
+		"unknown":"Q4_K",
+	},
+	"quality":{
+		"gate":"Q6_K",
+		"attn_proj":"Q4_K",
+		"ffn_gate_up":"Q4_K",
+		"ffn_down":"Q4_K",
+		"norms":"F16",
+		"ssm_params":"F16",
+		"gdn_state":"Q8_0",
+		"mtp":"Q8_0",
+		"embd":"Q5_K",
+		"shexp":"Q5_K",
+		"unknown":"Q4_K",
+	},
+	"fidelity":{
+		"gate":"Q8_0",
+		"attn_proj":"Q5_K",
+		"ffn_gate_up":"Q5_K",
+		"ffn_down":"Q5_K",
+		"norms":"F16",
+		"ssm_params":"F16",
+		"gdn_state":"Q8_0",
+		"mtp":"Q8_0",
+		"embd":"Q5_K",
+		"shexp":"Q6_K",
+		"unknown":"Q5_K",
+	}
+}
+
+# Monotonic tier progression for the speculative draft head
+PROFILE_MTP_TIER={"nano":"Q5_K","mini":"Q6_K","compact":"Q8_0"}
+MTP_DEPLOY_TIER="Q8_0"
+
+# Ceilings applied when weights originate from an AutoRound int4 optimization
+INT4_LINEAGE_CAP="Q5_K"
+INT4_MTP_CAP="Q6_K"
+INT4_GDN_CAP="Q8_0"
+INT4_CAP_CLASSES={"attn_proj","ffn_gate_up","ffn_down","shexp"}
+
+TENSOR_CLASS={
+	"attn_gate":"gate",
+	"ssm_alpha":"gdn_state",
+	"ssm_beta":"gdn_state",
+	"ssm_beta_alpha":"gdn_state",
+	"ssm_ba":"gdn_state",
+	"attn_q":"attn_proj",
+	"attn_k":"attn_proj",
+	"attn_v":"attn_proj",
+	"attn_qkv":"attn_proj",
+	"attn_output":"attn_proj",
+	"attn_out":"attn_proj",
+	"ffn_gate":"ffn_gate_up",
+	"ffn_up":"ffn_gate_up",
+	"ffn_down":"ffn_down",
+	"ssm_in":"attn_proj",
+	"ssm_out":"attn_proj",
+	"ssm_d":"ssm_params",
+	"ssm_norm":"norms",
+	"ssm_conv1d":"norms",
+	"router":"norms",
+	"ssm_dt":"ssm_params",
+	"ssm_a":"ssm_params",
+	"nextn":"mtp",
+	"ffn_gate_exps":"ffn_gate_up",
+	"ffn_up_exps":"ffn_gate_up",
+	"ffn_down_exps":"ffn_down",
+	"ffn_gate_inp":"norms",
+	"vocoder":"norms",
+	"decoder_wave":"norms",
+	"codec_decoder":"norms",
+	"patch_embd":"norms",
+	"patch_embedding":"norms",
+	"position_embd":"norms",
+	"post_ln":"norms",
+	"pre_ln":"norms",
+	"ln1":"norms",
+	"ln2":"norms",
+	"ln_q":"norms",
+	"mm_input_norm":"norms",
+	"mm_soft_emb_norm":"norms",
+	"mm_0":"embd",
+	"mm_1":"embd",
+	"mm_2":"embd",
+	"0":"embd",
+	"1":"embd",
+	"2":"embd",
+	"mm_proj":"embd",
+	"v_enc_embd":"norms",
+	"q_proj":"attn_proj",
+	"k_proj":"attn_proj",
+	"v_proj":"attn_proj",
+	"o_proj":"attn_proj",
+	"in_proj_a":"gdn_state",
+	"in_proj_b":"gdn_state",
+	"in_proj_qkv":"attn_proj",
+	"in_proj_z":"attn_proj",
+	"out_proj":"attn_proj",
+	"gate_proj":"ffn_gate_up",
+	"up_proj":"ffn_gate_up",
+	"down_proj":"ffn_down",
+	"attn_sinks":"norms",
+	"ffn_exp_probs_b":"norms",
+	"exp_probs_b":"norms",
+	"per_layer_token_embd":"embd",
+	"ffn_gate_shexp":"shexp",
+	"ffn_up_shexp":"shexp",
+	"ffn_down_shexp":"shexp",
+	"ffn_gate_inp_shexp":"norms",
+}
+
+ARCH_FEATURES={
+	"qwen35":{
+		"has_qkv":True,"has_ssm":True,"has_mtp":True,"has_moe":False,
+		"is_qat":False,"prefix":"blk","n_layers":32,
+	},
+	"mellum2":{
+		"has_qkv":False,"has_ssm":False,"has_mtp":False,"has_moe":True,
+		"is_qat":False,"prefix":"blk","n_layers":28,
+	},
+	"gemma4":{
+		"has_qkv":False,"has_ssm":False,"has_mtp":False,"has_moe":False,
+		"is_qat":True,"prefix":"blk","n_layers":48,
+	},
+	"dense":{
+		"has_qkv":False,"has_ssm":False,"has_mtp":False,"has_moe":False,
+		"is_qat":False,"prefix":"blk","n_layers":32,
+	},
+}
+
+def strip_weight(name:str)->str:
+	return name.lstrip(".").removesuffix(".weight").removesuffix(".bias")
+
+def get_tensor_type(name:str)->str:
+	parts=strip_weight(name).split(".")
+	if len(parts)>=3 and parts[0] in("v","a") and parts[1] in("blk","BLK"):
+		return parts[3] if len(parts)>=4 else "unknown"
+	if len(parts)>=2 and parts[0] in("blk","BLK"):
+		return parts[2] if len(parts)>=3 else "unknown"
+	if "token_embd" in name:
+		return "token_embd"
+	if name.startswith("output") and "norm" not in name:
+		return "output"
+	return name
+
+def get_tensor_class(ttype:str)->str:
+	if ttype in TENSOR_CLASS:
+		return TENSOR_CLASS[ttype]
+	if "." in ttype:
+		tail=ttype.split(".")[-1]
+		if tail in TENSOR_CLASS:
+			return TENSOR_CLASS[tail]
+		for part in reversed(ttype.split(".")):
+			if part in TENSOR_CLASS:
+				return TENSOR_CLASS[part]
+	if "norm" in ttype or "scale" in ttype or ttype.startswith(("ln","pre_ln","post_ln")):
+		return "norms"
+	if ttype.startswith("ssm_"):
+		return "ssm_params"
+	if ttype in("token_embd","output","embed_tokens","lm_head","vision_embedder","audio_embedder"):
+		return "embd"
+	return "unknown"
+
+def is_mtp_tensor(name:str,n_layers:int=32,mtp_layers:set | None=None)->bool:
+	if "nextn" in name or name.startswith("mtp."):
+		return True
+	if mtp_layers is not None:
+		return get_layer_number(name) in mtp_layers
+	layer=get_layer_number(name)
+	return layer is not None and layer>=n_layers
+
+def get_layer_number(name:str)->int | None:
+	parts=strip_weight(name).split(".")
+	if len(parts)>=3 and parts[0] in("v","a") and parts[1] in("blk","BLK"):
+		try:return int(parts[2])
+		except ValueError:return None
+	if len(parts)>=2 and parts[0] in("blk","BLK"):
+		try:return int(parts[1])
+		except ValueError:return None
+	return None
+
+# ═══════════════════════════════════════════════════════════════════════════
+# 2. UTILITY FUNCTIONS
+# ═══════════════════════════════════════════════════════════════════════════
+
+def type_name(type_id:int)->str:
+	return GGUF_TYPE_NAMES.get(type_id,f"UNKNOWN({type_id})")
+
+def type_id(name:str)->int:
+	return GGUF_TYPE_NAMES_INV.get(name,-1)
+
+def parse_size_line(line:str)->float | None:
+	m=re.search(r"quant size\s*=\s*([0-9.]+)\s*MiB",line)
+	if m:return float(m.group(1))
+	m=re.search(r"model size\s*=\s*([0-9.]+)\s*MiB",line)
+	if m:return float(m.group(1))
+	return None
+
+def parse_quant_size(output:str)->float | None:
+	m=re.search(r"quant size\s*=\s*([0-9.]+)\s*MiB",output)
+	if m:return float(m.group(1))
+	m=re.search(r"model size\s*=\s*([0-9.]+)\s*MiB",output)
+	if m:return float(m.group(1))
+	return None
+
+def parse_fallback_warnings(output:str)->int:
+	return len(re.findall(r"converting to\s+(q[0-9]_[0-9KMS]|iq[0-9])",output))
+
+def format_size(mib:float)->str:
+	if mib>=1024:return f"{mib/1024:.2f} GB"
+	return f"{mib:.0f} MiB"
+
+# ═══════════════════════════════════════════════════════════════════════════
+# 3. MODEL READER
+# ═══════════════════════════════════════════════════════════════════════════
+
+def detect_architecture(tensors:dict)->str:
+	names=list(tensors.keys())
+	has_ssm=any("ssm_" in n for n in names)
+	has_qkv=any("attn_qkv" in n for n in names)
+	has_moe=any("exps" in n for n in names)
+	has_gemma_specific=any(t in n for t in("layer_output_scale","post_attention_norm","post_ffw_norm") for n in names)
+	if has_ssm and has_qkv:return "qwen35"
+	if has_moe:return "mellum2"
+	if has_gemma_specific:return "gemma4"
+	return "dense"
+
+def _detect_prefix(tensors:dict)->str:
+	for name in tensors:
+		if name.startswith("BLK."):return "BLK"
+	return "blk"
+
+def _estimate_layers(tensors:dict)->int:
+	max_layer=-1
+	for name in tensors:
+		parts=name.split(".")
+		if len(parts)>=3 and parts[0] in("v","a") and parts[1] in("blk","BLK"):
+			parts=parts[1:]
+		if len(parts)>=2 and parts[0] in("blk","BLK"):
+			try:
+				layer=int(parts[1])
+				if layer>max_layer:max_layer=layer
+			except ValueError:pass
+	return max_layer+1 if max_layer>=0 else 0
+
+def read_model(path:str)->dict:
+	r=gguf.GGUFReader(path)
+	tensors={}
+	meta={}
+	for k,v in r.fields.items():
+		try:
+			data=v.data
+			if isinstance(data,np.ndarray):data=data.tolist()
+			elif isinstance(data,(np.generic,)):data=data.item()
+			meta[k]=data
+		except Exception:meta[k]=str(v)
+	for t in r.tensors:
+		shape=list(t.shape)
+		name=t.name
+		n_elements=int(np.prod(shape))
+		tensors[name]={"shape":shape,"n_elements":n_elements,"size_mib":n_elements*2/1024/1024}
+	arch=detect_architecture(tensors)
+	arch_features=ARCH_FEATURES.get(arch,{}).copy()
+	prefix=_detect_prefix(tensors)
+	n_layers=_estimate_layers(tensors)
+	NEXTN_HINT=("nextn","eh_proj","mtp.fc")
+	has_nextn=any(any(h in n for h in NEXTN_HINT) for n in tensors)
+	BODY=("attn_qkv","attn_q","attn_k","attn_v","attn_output","ssm_","ffn_","eh_proj","exps")
+	last=n_layers-1
+	last_names=[n for n in tensors if n.startswith(f"blk.{last}.") or n.startswith(f"BLK.{last}.")]
+	last_has_body=any(any(h in n for h in BODY) for n in last_names)
+	last_has_nextn=any(any(h in n for h in NEXTN_HINT) for n in last_names)
+	has_blk_mtp=bool(last_names) and last_has_body and last_has_nextn
+	mtp_layers=[last] if has_blk_mtp else []
+	has_mtp=has_nextn and(has_blk_mtp or any("nextn" in n for n in tensors))
+	has_moe=any("exps" in n for n in tensors)
+	if last_names and not last_has_body:
+		print(f"  [WARN] blk.{last} contains only {len(last_names)} norm tensor(s) — truncated MTP head ignored")
+		n_layers-=1
+	elif has_blk_mtp:
+		n_layers-=1
+	if arch=="mellum2" and arch_features.get("moe_intermediate_size",0)==0:
+		arch_features["moe_intermediate_size"]=896
+	arch_features["prefix"]=prefix
+	if n_layers>0:arch_features["n_layers"]=n_layers
+	if has_moe:arch_features["has_moe"]=True
+	arch_features["has_mtp"]=has_mtp
+	arch_features["mtp_layers"]=mtp_layers
+	return{
+		"path":path,
+		"architecture":arch,
+		"features":arch_features,
+		"tensors":tensors,
+		"n_tensors":len(tensors),
+		"meta":meta,
+	}
+
+# ═══════════════════════════════════════════════════════════════════════════
+# 4. IMATRIX READER
+# ═══════════════════════════════════════════════════════════════════════════
+
+def read_imatrix(path:str)->dict:
+	r=gguf.GGUFReader(path)
+	raw={}
+	meta={}
+	for k,v in r.fields.items():
+		try:meta[k]=v.data
+		except Exception:meta[k]=str(v)
+	for t in r.tensors:
+		name=t.name
+		arr=np.array(t.data,dtype=np.float64)
+		if name.endswith(".in_sum2"):
+			base=name[:-8]
+			if base not in raw:raw[base]={}
+			raw[base]["in_sum2"]=arr
+			if base+".in_sum" in {t2.name for t2 in r.tensors}:
+				for t2 in r.tensors:
+					if t2.name==base+".in_sum":
+						raw[base]["in_sum"]=np.array(t2.data,dtype=np.float64)
+						break
+		elif name.endswith(".counts"):
+			base=name[:-7]
+			if base not in raw:raw[base]={}
+			raw[base]["counts"]=float(np.mean(arr))
+	result={}
+	for base,data in raw.items():
+		if "in_sum2" not in data:continue
+		arr=data["in_sum2"]
+		n=arr.size
+		imp_mean=float(np.mean(arr))
+		outlier_ratio=None
+		if "in_sum" in data and imp_mean>0:
+			in_sum_arr=data["in_sum"]
+			total_sum=float(np.sum(in_sum_arr))
+			if total_sum>0 and n>0:
+				total_sum2=float(np.sum(arr**2))
+				mean_sq=total_sum2/n
+				mean_x=total_sum/n
+				if mean_x>0:
+					outlier_ratio=math.sqrt(mean_sq /(mean_x**2)-1)
+		result[base]={
+			"importance_mean":imp_mean,
+			"importance_sum":float(np.sum(arr)),
+			"importance_max":float(np.max(arr)),
+			"importance_min":float(np.min(arr)),
+			"n_elements":n,
+			"in_sum2_raw":arr,
+			"outlier_ratio":outlier_ratio,
+		}
+	return{
+		"path":path,
+		"tensors":result,
+		"n_tensors":len(result),
+		"meta":meta,
+	}
+
+def combine_imatrix(imatrix_list:List[dict],method:str="max")->dict:
+	if not imatrix_list:return{"path":"","tensors":{},"n_tensors":0,"meta":{}}
+	if len(imatrix_list)==1:return imatrix_list[0]
+	all_names=set()
+	for im in imatrix_list:all_names.update(im["tensors"].keys())
+	combined_tensors={}
+	for name in all_names:
+		vals=[]
+		in_sum2_raw=None
+		n_elements=0
+		for im in imatrix_list:
+			if name in im["tensors"]:
+				t=im["tensors"][name]
+				vals.append(t["importance_mean"])
+				if in_sum2_raw is None and "in_sum2_raw" in t:in_sum2_raw=t["in_sum2_raw"]
+				n_elements=max(n_elements,t["n_elements"])
+		if not vals:continue
+		if method=="max":imp_mean=max(vals)
+		elif method in("mean","weighted_mean"):imp_mean=sum(vals)/len(vals)
+		else:imp_mean=max(vals)
+		combined_tensors[name]={
+			"importance_mean":imp_mean,
+			"importance_sum":imp_mean*n_elements,
+			"importance_max":max(v.get("importance_max",0) for im in imatrix_list if name in im["tensors"] for v in[im["tensors"][name]]),
+			"importance_min":min(v.get("importance_min",float('inf')) for im in imatrix_list if name in im["tensors"] for v in[im["tensors"][name]]),
+			"n_elements":n_elements,
+			"in_sum2_raw":in_sum2_raw,
+			"outlier_ratio":max((t.get("outlier_ratio") for im in imatrix_list if name in im["tensors"] for t in[im["tensors"][name]] if t.get("outlier_ratio") is not None),default=None),
+		}
+	combined_meta={}
+	for im in imatrix_list:
+		for k,v in im["meta"].items():
+			if k not in combined_meta:combined_meta[k]=v
+	return{
+		"path":"+".join(im["path"] for im in imatrix_list),
+		"tensors":combined_tensors,
+		"n_tensors":len(combined_tensors),
+		"meta":combined_meta,
+	}
+
+def detect_tied_groups(imatrix:dict,atol:float=1e-5)->list:
+	coarse={}
+	no_raw=[]
+	for name in sorted(imatrix["tensors"].keys()):
+		arr=imatrix["tensors"][name].get("in_sum2_raw")
+		if arr is None:
+			no_raw.append(name)
+			continue
+		key=(arr.shape,hash(np.round(arr/atol).astype(np.int64).tobytes()))
+		coarse.setdefault(key,[]).append(name)
+	buckets={}
+	for key,names in coarse.items():
+		if len(names)==1:
+			buckets[key]=names
+			continue
+		n=len(names)
+		groups=list(range(n))
+		def find(x):
+			while groups[x]!=x:
+				groups[x]=groups[groups[x]]
+				x=groups[x]
+			return x
+		def union(a,b):
+			ra,rb=find(a),find(b)
+			if ra!=rb:groups[ra]=rb
+		arrs=[imatrix["tensors"][n]["in_sum2_raw"] for n in names]
+		for i in range(n):
+			for j in range(i+1,n):
+				a,b=arrs[i],arrs[j]
+				if a.shape!=b.shape:continue
+				if np.allclose(a,b,rtol=1e-5,atol=1e-6):union(i,j)
+		comps=defaultdict(list)
+		for i,name in enumerate(names):comps[find(i)].append(name)
+		for comp in comps.values():buckets.setdefault(key +(id(comp),),[]).extend(comp)
+	tied_groups=list(buckets.values())
+	tied_groups.extend([[n] for n in no_raw])
+	return tied_groups
+
+def _imatrix_type(name:str)->str:
+	parts=name.split(".")
+	if len(parts)>=3 and parts[0]=="blk":return parts[2]
+	return name
+
+def build_importance_table(imatrix:dict,model:dict)->dict:
+	table={}
+	for tname,info in imatrix["tensors"].items():
+		ttype=_imatrix_type(tname)
+		table[tname]={
+			"importance_mean":info["importance_mean"],
+			"importance_sum":info["importance_sum"],
+			"importance_max":info["importance_max"],
+			"importance_min":info["importance_min"],
+			"n_elements":info["n_elements"],
+			"type":ttype,
+		}
+	for tname,info in list(table.items()):
+		if tname.endswith("."):
+			alt=tname.rstrip(".")
+			table[alt]=info
+	return table
+
+# ═══════════════════════════════════════════════════════════════════════════
+# 5. CLASSIFIER & OPTIMIZER
+# ═══════════════════════════════════════════════════════════════════════════
+
+BITS_IN_MIB=8*1024*1024.0
+
+TIER_SIZE_MULTIPLIER={
+	tier:(bpw/BITS_IN_MIB)*GGUF_OVERHEAD_FACTOR
+	for tier,bpw in TIER_BPW.items()
+}
+
+def apply_overhead_factor(factor:float):
+	TIER_SIZE_MULTIPLIER.update({t:(b/BITS_IN_MIB)*factor for t,b in TIER_BPW.items()})
+
+K_QUANTS={"Q3_K","Q4_K","Q5_K","Q6_K"}
+MOE_PAD_TYPES={"ffn_gate_exps","ffn_up_exps","ffn_down_exps","ffn_down"}
+MSE_BPW=dict(TIER_BPW)
+
+def _percentile_rank(values:Dict[str,float])->Dict[str,float]:
+	if not values:return{}
+	sorted_vals=sorted(values.values())
+	n=len(sorted_vals)
+	return{name:bisect_left(sorted_vals,raw)/n for name,raw in values.items()}
+
+def _normalize_by_class(
+	tensor_importance:Dict[str,float],
+	importance_table:Dict[str,Any],
+)->Dict[str,float]:
+	class_groups:Dict[str,Dict[str,float]]={}
+	for name,raw_imp in tensor_importance.items():
+		rep_info=importance_table.get(name,{})
+		ttype=rep_info.get("type",get_tensor_type(name))
+		cls=get_tensor_class(ttype)
+		class_groups.setdefault(cls,{})[name]=raw_imp
+	normalized={}
+	for cls,group_vals in class_groups.items():
+		pct=_percentile_rank(group_vals)
+		normalized.update(pct)
+	for name in tensor_importance:
+		if name not in normalized:normalized[name]=0.5
+	return normalized
+
+@dataclass(order=True,slots=True)
+class TierMove:
+	neg_utility:float
+	group_id:int=field(compare=False)
+	target_tier:str=field(compare=False)
+	size_delta:float=field(compare=False)
+	is_downgrade:bool=field(compare=False,default=False)
+	from_tier:str=field(compare=False,default="")
+
+def _tier_index(tier:str)->int:
+	if tier not in TIER_ORDER:raise ValueError(f"Unknown tier: {tier}")
+	return TIER_ORDER.index(tier)
+
+def _tier_at(idx:int)->str:
+	if not(0<=idx<len(TIER_ORDER)):raise IndexError(f"Tier index {idx} out of range")
+	return TIER_ORDER[idx]
+
+def _size_mib(tier:str,n_elements:int)->float:
+	if n_elements<=0:return 0.0
+	return n_elements*TIER_SIZE_MULTIPLIER.get(tier,0.0)
+
+FREE_EMBD_TIER="Q8_0"
+
+TIER_BLOCK_ALIGN={
+	"IQ1_S":256,"IQ2_XXS":256,"IQ2_XS":256,"IQ2_S":256,
+	"IQ3_XXS":256,"Q3_K":256,"IQ3_S":256,
+	"IQ4_XS":256,"Q4_K":256,"Q5_K":256,"Q6_K":256,
+	"IQ4_NL":32,"Q8_0":32,
+	"F16":1,
+}
+
+def _row_len(shape)->int:
+	return int(shape[0]) if shape else 1
+
+def tier_fits(shape,tier:str)->bool:
+	return _row_len(shape) % TIER_BLOCK_ALIGN.get(tier,1)==0
+
+def highest_fitting_tier(shape,tier:str)->str:
+	idx=_tier_index(tier)
+	while idx<len(TIER_ORDER):
+		if tier_fits(shape,TIER_ORDER[idx]):return TIER_ORDER[idx]
+		idx+=1
+	return "F16"
+
+def _free_embd_assignments(model:dict,all_names:set,enabled:bool,embd_cap:str | None=None)->dict:
+	# Host CPU token embeddings live outside VRAM allocations unless tied to lm_head
+	if not enabled:return {}
+	types={get_tensor_type(n):n for n in all_names}
+	tok,out=types.get("token_embd"),types.get("output")
+	if not(tok and out):return {}
+	tier=FREE_EMBD_TIER
+	if embd_cap and _tier_index(embd_cap)<_tier_index(tier):tier=embd_cap
+	return {tok:tier}
+
+def embd_int4_cap(model_path:str)->str | None:
+	globals_=provenance(model_path).get("int4_globals") or []
+	return INT4_LINEAGE_CAP if any("embed" in g or "token_embd" in g for g in globals_) else None
+
+def _pinned_f32_names(model:dict)->set:
+	# Keep 1-D tensors and rows unaligned with ggml block boundaries in F32
+	out=set()
+	for n,info in model.get("tensors",{}).items():
+		sh=[int(d) for d in info.get("shape",[])]
+		if len([d for d in sh if d>1])<2 or _row_len(sh)%32!=0:
+			out.add(n)
+	return out
+
+def _shape_map(model:dict)->dict:
+	return {n:[int(d) for d in i.get("shape",[])] for n,i in model.get("tensors",{}).items()}
+
+def _clamp_to_alignment(assignments:dict,shape_map:dict)->int:
+	fixed=0
+	for name,tier in list(assignments.items()):
+		sh=shape_map.get(name)
+		if not sh or tier_fits(sh,tier):continue
+		assignments[name]=highest_fitting_tier(sh,tier)
+		fixed+=1
+	return fixed
+
+# Relative efficiency bonus for learned codebook representations
+FAMILY_EFF_BITS={
+	"IQ4_XS":0.45,"IQ4_NL":0.30,
+	"IQ3_S":0.40,"IQ3_XXS":0.35,
+	"IQ2_S":0.30,"IQ2_XS":0.25,"IQ2_XXS":0.20,
+	"IQ1_S":0.15,
+}
+
+def _eff_bpw(tier:str)->float:
+	return MSE_BPW[tier]+FAMILY_EFF_BITS.get(tier,0.0)
+
+@lru_cache(maxsize=256)
+def _mse_delta(cur_tier:str,next_tier:str)->float:
+	return(2**(-2*_eff_bpw(cur_tier))) -(2**(-2*_eff_bpw(next_tier)))
+
+def _group_size(group_registry:Dict[int,Tuple[List[str],int,int]],group_id:int,tier:str)->float:
+	g_names,g_elements,g_elements_padded=group_registry[group_id]
+	elements=g_elements_padded if tier in K_QUANTS else g_elements
+	return _size_mib(tier,elements)
+
+def _push_upgrade(group_id:int,group_registry:Dict[int,Tuple[List[str],int,int]],assignments:Dict[str,str],tensor_importance:Dict[str,float],upgrade_queue:List[TierMove],importance_table:Dict[str,Any],cap_table:dict | None=None):
+	g_names,_,_=group_registry[group_id]
+	rep_name=g_names[0]
+	cur_tier=assignments[rep_name]
+	cur_idx=_tier_index(cur_tier)
+	rep_info=importance_table.get(rep_name,{})
+	ttype=rep_info["type"] if "type" in rep_info else get_tensor_type(rep_name)
+	cls=get_tensor_class(ttype)
+	max_tier=CLASS_MAX_TIER.get(cls,"Q8_0")
+	if cap_table and cls in cap_table and _tier_index(cap_table[cls])<_tier_index(max_tier):
+		max_tier=cap_table[cls]
+	if cur_idx>=_tier_index(max_tier) or cur_idx>=len(TIER_ORDER)-1:
+		return
+	next_idx=cur_idx+1
+	max_idx=min(_tier_index(max_tier),len(TIER_ORDER)-1)
+	next_tier,cost_delta,quality_delta=None,0.0,0.0
+	while next_idx<=max_idx:
+		next_tier=_tier_at(next_idx)
+		cost_delta=_group_size(group_registry,group_id,next_tier)-_group_size(group_registry,group_id,cur_tier)
+		quality_delta=_mse_delta(cur_tier,next_tier)
+		if quality_delta>0:break
+		next_idx+=1
+	if next_tier is None or next_idx>max_idx or quality_delta<=0 or cost_delta<0:
+		return
+	if cost_delta==0:
+		utility_per_mb=float('inf')
+	else:
+		total_g_imp=sum(tensor_importance.get(n,0) for n in g_names)
+		utility_per_mb=(total_g_imp*quality_delta)/cost_delta
+	heapq.heappush(upgrade_queue,TierMove(-utility_per_mb,group_id,next_tier,cost_delta,from_tier=cur_tier))
+
+def _push_downgrade(group_id:int,group_registry:Dict[int,Tuple[List[str],int,int]],assignments:Dict[str,str],tensor_importance:Dict[str,float],downgrade_queue:List[TierMove],importance_table:Dict[str,Any],floor_table:Dict[str,str]):
+	g_names,_,_=group_registry[group_id]
+	rep_name=g_names[0]
+	cur_tier=assignments[rep_name]
+	cur_idx=_tier_index(cur_tier)
+	rep_info=importance_table.get(rep_name,{})
+	ttype=rep_info["type"] if "type" in rep_info else get_tensor_type(rep_name)
+	cls=get_tensor_class(ttype)
+	floor=floor_table.get(cls,"Q4_K")
+	if cur_idx<=_tier_index(floor) or cur_idx<=0:
+		return
+	next_tier=_tier_at(cur_idx-1)
+	saved=_group_size(group_registry,group_id,cur_tier)-_group_size(group_registry,group_id,next_tier)
+	quality_loss=_mse_delta(next_tier,cur_tier)
+	if saved<=0 or quality_loss<=0:
+		return
+	total_g_imp=sum(tensor_importance.get(n,0) for n in g_names)
+	loss_per_mb=(total_g_imp*quality_loss)/saved
+	heapq.heappush(downgrade_queue,TierMove(loss_per_mb,group_id,next_tier,-saved,True,from_tier=cur_tier))
+
+def converge_to_target(importance_table:dict,tied_groups:list,model:dict,target_size_mib:float,allow_q3:bool=False,tolerance_pct:float=2.0,max_iterations:int=5,profile:str="quality",int4_lineage:bool=False,free_embd:bool=True,embd_cap:str | None=None)->Tuple[dict,dict]:
+	effective_target=target_size_mib
+	ne_map={k:v["n_elements"] for k,v in model.get("tensors",{}).items()}
+	if not ne_map:
+		ne_map={k:v["n_elements"] for k,v in importance_table.items()}
+	f32_names=_pinned_f32_names(model)
+	best=None
+	best_diff=float("inf")
+	seen_targets=set()
+	for iteration in range(max(max_iterations,1)):
+		assignments,padded_ne_map=optimal_classify(importance_table,tied_groups,model,target_size_mib=effective_target,allow_q3=allow_q3,profile=profile,int4_lineage=int4_lineage,free_embd=free_embd,embd_cap=embd_cap)
+		current_size=compute_stats(assignments,ne_map,padded_ne_map,f32_names)["total_mib"]
+		diff_pct=abs(current_size-target_size_mib)/target_size_mib*100
+		if diff_pct<best_diff:
+			best_diff=diff_pct
+			best=(dict(assignments),dict(padded_ne_map),current_size)
+		if diff_pct<=tolerance_pct:
+			print(f"  [converge] iter {iteration+1}: {current_size:.0f} MiB (diff {diff_pct:.2f}%) — within tolerance {tolerance_pct}%")
+			return assignments,padded_ne_map
+		print(f"  [converge] iter {iteration+1}: {current_size:.0f} MiB (diff {diff_pct:.2f}%) — adjusting effective budget…")
+		if current_size<=0:break
+		correction=target_size_mib/current_size
+		effective_target=min(max(effective_target*correction,target_size_mib*0.95),target_size_mib*1.05)
+		key=round(effective_target,1)
+		if key in seen_targets:
+			print("  [converge] Effective budget stationary — keeping best result")
+			break
+		seen_targets.add(key)
+	print(f"  [converge] Selected best result: {best[2]:.0f} MiB (diff {best_diff:.2f}%)")
+	return best[0],best[1]
+
+def compute_mtp_assignments_check(non_mtp_names,mtp_names,importance_table,allow_q3,is_qat,profile,int4_lineage):
+	has_im=any("importance_mean" in importance_table.get(n,{}) for n in mtp_names)
+	mtp_tier=PROFILE_MTP_TIER.get(profile,MTP_DEPLOY_TIER) if has_im else CLASS_HARD_FLOORS["mtp"]
+	if int4_lineage and _tier_index(mtp_tier)>_tier_index(INT4_MTP_CAP):
+		mtp_tier=INT4_MTP_CAP
+	assignments={n:mtp_tier for n in mtp_names}
+	floors=TIER_FLOORS.get(profile,TIER_FLOORS["quality"])
+	for name in non_mtp_names:
+		rep_info=importance_table.get(name,{})
+		has_im="importance_mean" in rep_info
+		ttype=rep_info.get("type",get_tensor_type(name))
+		cls=get_tensor_class(ttype)
+		tier=floors.get(cls,floors.get("unknown",DEFAULT_FLOOR))
+		hard_floor=CLASS_HARD_FLOORS.get(cls)
+		if hard_floor and _tier_index(tier)<_tier_index(hard_floor) and not(allow_q3 and cls in CAN_Q3):
+			tier=hard_floor
+		if is_qat and cls not in("norms","ssm_params","gdn_state"):
+			cap="Q4_K" if cls=="attn_proj" else "IQ4_XS"
+			if _tier_index(cap)<_tier_index(tier):tier=cap
+		if int4_lineage and cls in INT4_CAP_CLASSES and _tier_index(tier)>_tier_index(INT4_LINEAGE_CAP):
+			tier=INT4_LINEAGE_CAP
+		if allow_q3 and cls in CAN_Q3 and has_im:
+			tier=ALLOW_LOWER_FLOOR
+		assignments[name]=tier
+	return assignments
+
+def compute_initial_assignments(non_mtp_names:Set[str],mtp_names:Set[str],importance_table:Dict,allow_q3:bool,is_qat:bool=False,profile:str="quality",int4_lineage:bool=False)->Dict[str,str]:
+	return compute_mtp_assignments_check(non_mtp_names,mtp_names,importance_table,allow_q3,is_qat,profile,int4_lineage)
+
+def _tie_family(name:str,importance_table:Dict)->str:
+	ttype=importance_table.get(name,{}).get("type",get_tensor_type(name))
+	if ttype in("ffn_gate","ffn_up"):return "ffn_gate_up"
+	return ttype
+
+def build_groups(tied_groups:List[List[str]],non_mtp_names:Set[str],ne_map:Dict[str,int],padded_ne_map:Dict[str,int],importance_table:Dict)->Dict[int,Tuple[List[str],int,int]]:
+	group_registry={}
+	assigned_tensors=set()
+	next_group_id=0
+	for tied_group in tied_groups:
+		families={}
+		for name in tied_group:
+			if name in non_mtp_names:
+				families.setdefault(_tie_family(name,importance_table),[]).append(name)
+		for names in families.values():
+			group_registry[next_group_id]=(names,sum(ne_map.get(name,0) for name in names),sum(padded_ne_map.get(name,0) for name in names))
+			assigned_tensors.update(names)
+			next_group_id+=1
+	for name in sorted(non_mtp_names-assigned_tensors):
+		group_registry[next_group_id]=([name],ne_map.get(name,0),padded_ne_map.get(name,0))
+		next_group_id+=1
+	return group_registry
+
+def optimal_classify(importance_table:dict,tied_groups:list,model:dict,target_size_mib:float,allow_q3:bool=False,profile:str="quality",int4_lineage:bool=False,free_embd:bool=True,embd_cap:str | None=None)->Tuple[dict,dict]:
+	if target_size_mib<=0:raise ValueError("target_size_mib must be positive")
+	cap_table=None
+	if int4_lineage:
+		cap_table={cls:INT4_LINEAGE_CAP for cls in INT4_CAP_CLASSES}
+		cap_table["gdn_state"]=INT4_GDN_CAP
+	features=model.get("features",{})
+	has_mtp=features.get("has_mtp",False)
+	n_layers=features.get("n_layers",31)
+	is_qat=features.get("is_qat",False)
+	model_tensors=model.get("tensors",{})
+	ne_map={k:v["n_elements"] for k,v in model_tensors.items()}
+	if not model_tensors:
+		for tname,info in importance_table.items():
+			ne_map[tname]=info["n_elements"]
+	moe_d_ff=features.get("moe_intermediate_size",0)
+	padded_ne_map=dict(ne_map)
+	if moe_d_ff>0 and moe_d_ff % 256!=0:
+		aligned_d_ff=((moe_d_ff+255) // 256)*256
+		for name,n_el in ne_map.items():
+			ttype=importance_table.get(name,{}).get("type",get_tensor_type(name))
+			if ttype in MOE_PAD_TYPES:
+				padded_ne_map[name]=(n_el // moe_d_ff)*aligned_d_ff
+	all_names=set(ne_map.keys())
+	mtp_layer_set=set(features.get("mtp_layers",[]))
+	mtp_names={n for n in all_names if is_mtp_tensor(n,n_layers,mtp_layer_set)} if has_mtp else set()
+	f32_names=_pinned_f32_names(model)
+	free_map=_free_embd_assignments(model,all_names,free_embd,embd_cap)
+	non_mtp_names=all_names-mtp_names-f32_names-set(free_map)
+	tensor_importance={}
+	for name in non_mtp_names:
+		info=importance_table.get(name,{})
+		tensor_importance[name]=info.get("importance_mean",0.0)
+	tensor_importance=_normalize_by_class(tensor_importance,importance_table)
+	for name in tensor_importance:
+		tensor_importance[name]*=max(ne_map.get(name,1),1)
+	assignments=compute_mtp_assignments_check(non_mtp_names,mtp_names,importance_table,allow_q3,is_qat,profile,int4_lineage)
+	assignments.update(free_map)
+	group_registry=build_groups(tied_groups,non_mtp_names,ne_map,padded_ne_map,importance_table)
+	profile_floors=TIER_FLOORS.get(profile,{})
+	floor_table={}
+	for cls in set(list(CLASS_HARD_FLOORS)+list(profile_floors)):
+		soft=profile_floors.get(cls,CLASS_HARD_FLOORS.get(cls,"Q4_K"))
+		hard=CLASS_HARD_FLOORS.get(cls,"IQ1_S")
+		floor_table[cls]=soft if _tier_index(soft)>=_tier_index(hard) else hard
+	if profile in("mini","compact","quality"):
+		if _tier_index(floor_table.get("embd","Q4_K"))>_tier_index("IQ4_XS"):
+			floor_table["embd"]="IQ4_XS"
+	mtp_cost=sum(_size_mib(assignments[n],ne_map.get(n,0)) for n in mtp_names)
+	pinned_cost=sum(ne_map.get(n,0)*32.0/BITS_IN_MIB for n in f32_names)
+	effective_target=target_size_mib-mtp_cost-pinned_cost
+	current_size=sum(
+		_size_mib(assignments[n],padded_ne_map.get(n,ne_map.get(n,0)) if assignments[n] in K_QUANTS else ne_map.get(n,0))
+		for n in non_mtp_names
+	)
+	if current_size>effective_target:
+		downgrade_queue=[]
+		for g_id in group_registry:
+			_push_downgrade(g_id,group_registry,assignments,tensor_importance,downgrade_queue,importance_table,floor_table)
+		while downgrade_queue and current_size>effective_target:
+			item=heapq.heappop(downgrade_queue)
+			if assignments[group_registry[item.group_id][0][0]]!=item.from_tier:
+				continue
+			for n in group_registry[item.group_id][0]:
+				assignments[n]=item.target_tier
+			current_size+=item.size_delta
+			_push_downgrade(item.group_id,group_registry,assignments,tensor_importance,downgrade_queue,importance_table,floor_table)
+		if current_size>effective_target:
+			warnings.warn(
+				f"Cannot reach target: floors hold size at {current_size:.1f} MiB vs target {effective_target:.1f} MiB. "
+				"Use --allow-q3-or-lower or increase --size.",RuntimeWarning)
+	has_signal=any("importance_mean" in importance_table.get(n,{}) for n in non_mtp_names)
+	upgrade_queue=[]
+	if has_signal:
+		for g_id in group_registry:
+			_push_upgrade(g_id,group_registry,assignments,tensor_importance,upgrade_queue,importance_table,cap_table)
+	while upgrade_queue:
+		item=heapq.heappop(upgrade_queue)
+		if assignments[group_registry[item.group_id][0][0]]!=item.from_tier:
+			continue
+		if item.size_delta>0 and current_size+item.size_delta>effective_target:
+			break
+		for n in group_registry[item.group_id][0]:
+			assignments[n]=item.target_tier
+		current_size+=item.size_delta
+		_push_upgrade(item.group_id,group_registry,assignments,tensor_importance,upgrade_queue,importance_table,cap_table)
+	fixed=_clamp_to_alignment(assignments,_shape_map(model))
+	if fixed:print(f"  ℹ  {fixed} tensor(s) promoted to closest aligned tier (ggml block)")
+	return assignments,padded_ne_map
+
+def compute_stats(assignments:dict,ne_map:dict=None,padded_ne_map:dict=None,f32_names:set=None)->dict:
+	stats={"by_tier_count":{},"by_tier_mib":{},"total_mib":0.0,"tensor_count":0}
+	for name,tier in assignments.items():
+		if not isinstance(tier,str):continue
+		stats["tensor_count"]+=1
+		stats["by_tier_count"][tier]=stats["by_tier_count"].get(tier,0)+1
+		if ne_map:
+			if padded_ne_map and tier in K_QUANTS:
+				elements=padded_ne_map.get(name,ne_map.get(name,0))
+			else:
+				elements=ne_map.get(name,0)
+			size=_size_mib(tier,elements)
+			stats["by_tier_mib"][tier]=stats["by_tier_mib"].get(tier,0.0)+size
+			stats["total_mib"]+=size
+	if ne_map and f32_names:
+		for name in f32_names:
+			size=ne_map.get(name,0)*32.0/BITS_IN_MIB
+			stats["tensor_count"]+=1
+			stats["by_tier_count"]["F32"]=stats["by_tier_count"].get("F32",0)+1
+			stats["by_tier_mib"]["F32"]=stats["by_tier_mib"].get("F32",0.0)+size
+			stats["total_mib"]+=size
+	return stats
+
+# ═══════════════════════════════════════════════════════════════════════════
+# 6. CONFIG GENERATOR
+# ═══════════════════════════════════════════════════════════════════════════
+
+def get_regex_priority(regex:str)->int:
+	score=0
+	if "nextn" in regex:score+=200
+	if re.search(r"(blk|BLK)\\.3[0-2]\\.",regex):score+=100
+	if re.search(r"(blk|BLK)\\.0\\.",regex):score+=90
+	if re.search(r"(blk|BLK)\\.31\\.",regex):score+=80
+	if r"(blk|BLK)\.(" in regex:score+=50
+	elif r"(blk|BLK)\.\d" in regex:score+=30
+	if regex.startswith(".*"):score-=50
+	if regex.endswith(r"\.weight"):score+=10
+	return score
+
+def _is_contiguous(lst,low,high):
+	if not lst:return False
+	return len(lst)==(high-low+1)
+
+def _group_ranges(lst):
+	if not lst:return
+	start=lst[0]
+	end=lst[0]
+	for i in range(1,len(lst)):
+		if lst[i]==end+1:
+			end=lst[i]
+		else:
+			yield(start,end)
+			start=end=lst[i]
+	yield(start,end)
+
+def _range_to_regex(start:int,end:int)->str:
+	if start==end:return str(start)
+	if end<=9:return f"[{start}-{end}]"
+	alt="|".join(str(i) for i in range(start,end+1))
+	return f"(?:{alt})"
+
+def generate_flags(assignments:dict,model:dict,base_type:str,target_size_mib:float=None)->dict:
+	is_qat=model.get("features",{}).get("is_qat",False)
+	output_type="Q5_K"
+	token_embd_type="Q4_K" if is_qat else "Q5_K"
+	for tname,tier in assignments.items():
+		ttype=get_tensor_type(tname)
+		if ttype=="output":output_type=tier
+		elif ttype=="token_embd":token_embd_type=tier
+	max_layer=model.get("features",{}).get("n_layers",31)
+	rules=[]
+	type_tier_layers={}
+	max_layer_seen=-1
+	for tname,tier in assignments.items():
+		parts=tname.split(".")
+		tower=""
+		if len(parts)>=4 and parts[0] in("v","a") and parts[1] in("blk","BLK"):
+			tower=parts[0]+"."
+			parts=parts[1:]
+		if len(parts)>=3 and parts[0] in("blk","BLK"):
+			try:layer=int(parts[1])
+			except ValueError:continue
+			ttype=parts[2]
+			key=(tower,ttype,tier)
+			if key not in type_tier_layers:type_tier_layers[key]=[]
+			type_tier_layers[key].append(layer)
+			max_layer_seen=max(max_layer_seen,layer)
+	max_layer=max_layer_seen if max_layer_seen>=0 else max_layer
+	for(tower,ttype,tier),layers in sorted(type_tier_layers.items(),key=lambda x:-QUANT_RANK.get(x[0][2],0)):
+		layers=sorted(set(layers))
+		if len(layers)>=8 and _is_contiguous(layers,0,max_layer):
+			pattern=f"{tower}(blk|BLK)\\.\\d+\\.{ttype}\\.weight={tier}"
+		else:
+			parts=[]
+			for start,end in _group_ranges(layers):
+				if start==end:parts.append(str(start))
+				else:parts.append(_range_to_regex(start,end))
+			desc="|".join(parts)
+			pattern=f"{tower}(blk|BLK)\\.({desc})\\.{ttype}\\.weight={tier}"
+		prio=get_regex_priority(pattern) +(10 if tier=="Q8_0" else 5 if tier=="Q6_K" else 0) +(5 if len(layers)==1 else 0) +(3 if "ffn_down" in ttype else 0)
+		rules.append((pattern,prio))
+	prefix=model.get("features",{}).get("prefix","blk")
+	for tname,tier in sorted(assignments.items(),key=lambda kv:-QUANT_RANK.get(kv[1],0)):
+		parts=tname.split(".")
+		if len(parts)>=2 and parts[0].lower()==prefix.lower():continue
+		if len(parts)>=4 and parts[0] in("v","a") and parts[1] in("blk","BLK"):continue
+		ttype=get_tensor_type(tname)
+		if ttype==tname:ttype=tname.removesuffix(".weight").removesuffix(".bias")
+		if ttype in("token_embd","output"):continue
+		ttype=re.sub(r"\.(?:weight|bias)\.\d+$","",ttype)
+		body=f".*{re.escape(ttype)}\\.weight"
+		pattern=f"{body}={tier}"
+		prio=get_regex_priority(pattern) +(5 if tier=="Q8_0" else 0)
+		if not any(p.rsplit("=",1)[0]==body for p,_ in rules):rules.append((pattern,prio))
+	rules.sort(key=lambda x:-x[1])
+	has_output=any(get_tensor_type(t)=="output" for t in assignments)
+	has_embd=any(get_tensor_type(t)=="token_embd" for t in assignments)
+	flags={
+		"imatrix":None,
+		"output_tensor_type":output_type if has_output else None,
+		"token_embedding_type":token_embd_type if has_embd else None,
+		"tensor_type_rules":[r[0] for r in rules],
+		"base_type":base_type,
+		"target_size_mib":target_size_mib,
+	}
+	return flags
+
+def format_flags(flags:dict)->str:
+	lines=[]
+	if flags.get("output_tensor_type"):lines.append("  --output-tensor-type "+flags["output_tensor_type"])
+	if flags.get("token_embedding_type"):lines.append("  --token-embedding-type "+flags["token_embedding_type"])
+	for pattern in flags["tensor_type_rules"]:lines.append(f'  --tensor-type "{pattern}"')
+	return "\n".join(lines)
+
+# ═══════════════════════════════════════════════════════════════════════════
+# 7. QUANTIZER EXECUTOR
+# ═══════════════════════════════════════════════════════════════════════════
+
+def _find_binary(name:str)->str:
+	exe=name +(".exe" if sys.platform=="win32" else "")
+	env_var=f"LLAMA_{name.upper().replace('-','_')}_PATH"
+	env_path=os.environ.get(env_var)
+	if env_path:
+		if os.path.isfile(env_path):return env_path
+		cand=os.path.join(env_path,exe)
+		if os.path.isfile(cand):return cand
+	script_dir=os.path.dirname(os.path.abspath(__file__))
+	roots=[]
+	env_root=os.environ.get("LLAMA_CPP_DIR")
+	if env_root:roots.append(env_root)
+	for base in(script_dir,os.getcwd()):
+		roots.append(base)
+		roots.append(os.path.normpath(os.path.join(base,"llama-cpp")))
+		roots.append(os.path.normpath(os.path.join(base,"..","llama-cpp")))
+		roots.append(os.path.normpath(os.path.join(base,"..","..","llama-cpp")))
+	subdirs=("","bin",os.path.join("build","bin"),os.path.join("build","bin","Release"),os.path.join("build","Release"),"build")
+	seen=set()
+	for root in roots:
+		for sub in subdirs:
+			p=os.path.normpath(os.path.join(root,sub,exe))
+			if p in seen:continue
+			seen.add(p)
+			if os.path.isfile(p):return p
+	from shutil import which
+	found=which(name) or which(exe)
+	if found:return found
+	return ""
+
+def _build_cmd(flags:dict,model_in:str,model_out:str,dry_run:bool=False)->list:
+	cmd=[_find_binary("llama-quantize")]
+	if dry_run:cmd.append("--dry-run")
+	if flags.get("imatrix"):
+		imatrix=flags["imatrix"]
+		if isinstance(imatrix,list):imatrix=imatrix[0]
+		cmd.extend(["--imatrix",imatrix])
+	if flags.get("output_tensor_type"):cmd.extend(["--output-tensor-type",flags["output_tensor_type"]])
+	if flags.get("token_embedding_type"):cmd.extend(["--token-embedding-type",flags["token_embedding_type"]])
+	for pattern in flags["tensor_type_rules"]:cmd.extend(["--tensor-type",pattern])
+	cmd.append(model_in)
+	cmd.append(model_out)
+	cmd.append(flags["base_type"])
+	return cmd
+
+def _missing_binary_msg(name:str):
+	exe=name +(".exe" if sys.platform=="win32" else "")
+	print(f"  ⚠  Binary '{exe}' not found.")
+	print(f"      Set LLAMA_CPP_DIR to your llama.cpp folder,")
+	print(f"      or set LLAMA_{name.upper().replace('-','_')}_PATH to the exact path,")
+	print(f"      or place '{exe}' next to this script.")
+
+def run_dry_run(flags:dict,model_in:str)->float | None:
+	binary=_find_binary("llama-quantize")
+	if not binary:
+		_missing_binary_msg("llama-quantize")
+		return None
+	cmd=_build_cmd(flags,model_in,os.devnull,dry_run=True)
+	try:result=subprocess.run(cmd,capture_output=True,text=True,timeout=600)
+	except FileNotFoundError:
+		_missing_binary_msg("llama-quantize")
+		return None
+	except subprocess.TimeoutExpired:
+		print("  ⚠  Dry run timed out after 600 s")
+		return None
+	output=(result.stdout or "") +(result.stderr or "")
+	size=parse_quant_size(output)
+	if size is not None:return size
+	m=re.search(r"unsupported model architecture:'([^']+)'",output)
+	if m:
+		print(f"  ⚠  llama-quantize rejected architecture '{m.group(1)}' — quantization aborted.")
+		return None
+	print("STDERR:",(result.stderr or "")[:2000])
+	return None
+
+def run_quantization(flags:dict,model_in:str,model_out:str)->bool:
+	binary=_find_binary("llama-quantize")
+	if not binary:
+		_missing_binary_msg("llama-quantize")
+		return False
+	cmd=_build_cmd(flags,model_in,model_out)
+	print("Running:"," ".join(cmd[:6])+" ...")
+	try:result=subprocess.run(cmd)
+	except FileNotFoundError:
+		_missing_binary_msg("llama-quantize")
+		return False
+	success=result.returncode==0
+	if success and os.path.isfile(model_out):
+		size_mib=os.path.getsize(model_out)/1024/1024
+		print(f"Done: {model_out} ({size_mib:.0f} MiB)")
+	return success
+
+# ═══════════════════════════════════════════════════════════════════════════
+# 8. MAIN SHQ ENGINE (SINGLE TARGET RUNNER)
+# ═══════════════════════════════════════════════════════════════════════════
+
+def _get_base_type(model:dict,profile:str="quality")->str:
+	if model.get("features",{}).get("is_qat",False):return "IQ4_XS"
+	return{
+		"nano":"IQ3_XXS","mini":"IQ4_XS","compact":"IQ4_XS","quality":"Q5_K_M",
+		"fidelity":"Q6_K",
+	}.get(profile,"Q5_K_M")
+
+def run_main_cli(args_list=None)->int:
+	parser=argparse.ArgumentParser(description="ASHQ1: AutoRound-infused imatrix hybrid quantization")
+	parser.add_argument("--model",help="BF16 GGUF model path")
+	parser.add_argument("--imatrix",action="append",default=[],help="Imatrix GGUF path (can be specified multiple times)")
+	parser.add_argument("--imatrix-method",choices=["max","mean"],default="max",help="How to combine multiple imatrices: max or mean")
+	parser.add_argument("--size",type=float,default=6800,help="Target file size in MiB")
+	parser.add_argument("--profile",choices=["nano","mini","compact","quality","fidelity"],default="quality",help="Quantization profile")
+	parser.add_argument("--lineage",choices=["auto","autoround","plain"],default="auto",help="Force output name lineage tag")
+	parser.add_argument("--output",default=None,help="Output GGUF path")
+	parser.add_argument("--run",action="store_true",help="Execute quantization")
+	parser.add_argument("--show-config",action="store_true",help="Print config and exit")
+	parser.add_argument("--verbose",action="store_true",help="Detailed output")
+	parser.add_argument("--allow-q3-or-lower",action="store_true",help="Allow starting tiers down to IQ2_XXS")
+	parser.add_argument("--no-free-embd",action="store_true",help="Keep token_embd inside the size budget (tied lm_head or strict file-size target)")
+	parser.add_argument("--aggro",type=float,default=None,help="[deprecated] Use --size instead")
+	parser.add_argument("--target-size",action="store_true",help="Iteratively converge to --size")
+	parser.add_argument("--show-floors",action="store_true",help="Print class hard floors and exit")
+	try:args=parser.parse_args(args_list)
+	except SystemExit as e:return e.code if isinstance(e.code,int) else 1
+	if args.show_floors:
+		_show_floors()
+		return 0
+	if not args.model:
+		parser.print_usage()
+		print("main: error: --model is required")
+		return 1
+	if not args.imatrix:
+		print("Note: no --imatrix provided, using profile defaults only.")
+	target_mib=args.size
+	print("=== ASHQ1 (AutoRound-infused) ===")
+	print(f"Model: {args.model}")
+	if not args.imatrix:
+		print("Imatrix: none (floor-driven profile)")
+	elif len(args.imatrix)==1:
+		print(f"Imatrix: {args.imatrix[0]}")
+	else:
+		print(f"Imatrix: {len(args.imatrix)} files ({args.imatrix_method})")
+		for p in args.imatrix:print(f" - {p}")
+	print(f"Target: {target_mib:.0f} MiB ({target_mib/1024:.2f} GB)")
+	int4_lineage=int4_lineage_of(args.model)
+	if int4_lineage:
+		print(f"  Lineage: int4 AutoRound source — weight upgrades capped at {INT4_LINEAGE_CAP}, MTP at {INT4_MTP_CAP}")
+	_ov=load_overhead_factor(args.model)
+	if abs(_ov-1.0)>1e-4:
+		apply_overhead_factor(_ov)
+		print(f"  Calibrated overhead (previous run): ×{_ov:.4f}")
+	if args.allow_q3_or_lower:
+		print("  --allow-q3-or-lower: low-importance tensors may go to Q3_K")
+	print()
+	print("[1/4] Reading model...")
+	model=read_model(args.model)
+	if not args.no_free_embd:
+		_free=_free_embd_assignments(model,set(model.get("tensors",{})),True)
+		_mib=sum(_size_mib(t,model["tensors"].get(n,{}).get("n_elements",0)) for n,t in _free.items())
+		if _mib>max(target_mib*0.15,128):
+			print(f"  ⚠  Embedding {_mib:.0f} MiB > 15% of target — disabling free-embd to preserve accurate tier ratios")
+			args.no_free_embd=True
+	no_free=args.no_free_embd
+	print(f"  Architecture: {model['architecture']}")
+	print(f"  Tensors: {model['n_tensors']}")
+	print(f"  Features: {json.dumps(model['features'],indent=2)}")
+	print("\n[2/4] Reading imatrix...")
+	imatrix_list=[read_imatrix(p) for p in args.imatrix]
+	for im in imatrix_list:
+		print(f"  {im['path']}: {im['n_tensors']} tensors, datasets={im['meta'].get('imatrix.datasets','?')}")
+	imatrix=combine_imatrix(imatrix_list,method=args.imatrix_method)
+	if imatrix_list:print(f"  Combined: {imatrix['n_tensors']} tensors")
+	else:print("  Skipped: profile floors drive every assignment")
+	print("\n[3/4] Detecting tied groups...")
+	imp_table=build_importance_table(imatrix,model)
+	tied_groups=detect_tied_groups(imatrix)
+	print(f"  Found {len(tied_groups)} tied groups:")
+	for g in tied_groups:
+		if len(g)<2:continue
+		fam={}
+		for n in g:fam.setdefault(_tie_family(n,imp_table),[]).append(n)
+		for names in fam.values():
+			if len(names)<2:continue
+			print(f"    TIED({len(names)}): {names[0].replace('.weight','')} = {names[1].replace('.weight','')}")
+	print("\n[4/4] Classifying tensors (greedy imatrix-driven)...")
+	embd_cap=embd_int4_cap(args.model) if int4_lineage else None
+	if embd_cap:
+		print(f"  Embeddings covered by int4 grid → host bump capped at {embd_cap}")
+	if args.target_size:
+		assignments,padded_ne_map=converge_to_target(
+			imp_table,tied_groups,model,
+			target_size_mib=target_mib,
+			allow_q3=args.allow_q3_or_lower,
+			profile=args.profile,
+			int4_lineage=int4_lineage,
+			free_embd=not no_free,
+			embd_cap=embd_cap,
+		)
+	else:
+		assignments,padded_ne_map=optimal_classify(
+			imp_table,tied_groups,model,
+			target_size_mib=target_mib,
+			allow_q3=args.allow_q3_or_lower,
+			profile=args.profile,
+			int4_lineage=int4_lineage,
+			free_embd=not no_free,
+			embd_cap=embd_cap,
+		)
+	ne_map={k:v["n_elements"] for k,v in model.get("tensors",{}).items()}
+	if not ne_map:ne_map={k:v["n_elements"] for k,v in imp_table.items()}
+	free_mib=sum(_size_mib(t,ne_map.get(n,0)) for n,t in _free_embd_assignments(model,set(ne_map),not no_free,embd_cap).items())
+	if free_mib:print(f"  Host-side embedding bump: {free_mib:.0f} MiB outside VRAM budget")
+	_show_tier_summary(assignments,imp_table,ne_map,padded_ne_map,_pinned_f32_names(model))
+	base_type=_get_base_type(model,args.profile)
+	flags=generate_flags(assignments,model,base_type,target_mib)
+	flags["imatrix"]=args.imatrix
+	print(f"\nConfig (base={flags['base_type']}):")
+	print(format_flags(flags))
+	if args.show_config:return 0
+	print("\n--- Dry Run ---")
+	estimated=compute_stats(assignments,ne_map,padded_ne_map,_pinned_f32_names(model))["total_mib"]
+	dry_size=run_dry_run(flags,args.model)
+	if dry_size and estimated>0:
+		ratio=dry_size/estimated
+		save_overhead_factor(args.model,_ov*ratio)
+		if abs(ratio-1.0)>0.02:
+			print(f"  Calibration: actual/estimated overhead ×{ratio:.4f} — saved for subsequent runs")
+	_show_size_result(dry_size,target_mib+free_mib)
+	if not args.run:
+		print("\nDry run only. Use --run to execute quantization.")
+		return 0
+	if not args.output:
+		base=clean_name(args.model)
+		pct=round(ALL_RATIOS.get(args.profile,0.39)*100)
+		args.output=f"{base}-{lineage_tag(args.model,args.lineage)}-{tier_label(args.profile)}-{pct}pc.gguf"
+	print(f"\n--- Running quantization: {args.output} ---")
+	success=run_quantization(flags,args.model,args.output)
+	if success:
+		print("Done!")
+		return 0
+	else:
+		print("Failed!")
+		return 1
+
+def _show_tier_summary(assignments,imp_table,ne_map,padded_ne_map=None,f32_names=None):
+	stats=compute_stats(assignments,ne_map,padded_ne_map,f32_names)
+	print("\n  Tier distribution:")
+	for tier in sorted(stats["by_tier_count"].keys()):
+		count=stats["by_tier_count"][tier]
+		mib=stats["by_tier_mib"].get(tier,0.0)
+		print(f"   {tier}: {count} tensors ({mib:.1f} MiB)")
+	print(f"  Total estimated size: {stats['total_mib']:.1f} MiB")
+	unknown=[n for n in assignments if get_tensor_class(get_tensor_type(n))=="unknown"]
+	if unknown:
+		print(f"\n  Unclassified tensors (floor-driven, {len(unknown)}) — extend TENSOR_CLASS if sensitive:")
+		for n in unknown[:8]:print(f"   {n}")
+		if len(unknown)>8:print(f"   … +{len(unknown)-8} more")
+	ranked=sorted([(n,v) for n,v in imp_table.items()],key=lambda x:-x[1]["importance_mean"])
+	print("\n  Top 10 by importance:")
+	for n,v in ranked[:10]:
+		tier=assignments.get(n,"base")
+		display=n.replace(".weight","").replace(".bias","")
+		print(f"   {display[:52]:52s} imp={v['importance_mean']:10.0f} tier={tier}")
+
+# Metadata overhead (header + vocab) not tracked by tensor arrays
+META_OVERHEAD_MIB=12.0
+
+def _show_size_result(dry_size,target_mib):
+	if dry_size:
+		on_disk=dry_size+META_OVERHEAD_MIB
+		print(f"  Estimated size: {dry_size:.0f} MiB ({dry_size/1024:.2f} GB)")
+		print(f"  Estimated on disk: {on_disk:.0f} MiB (+{META_OVERHEAD_MIB:.0f} MiB metadata)")
+		diff=on_disk-target_mib
+		if diff>0:print(f"  ⚠  Over target by {diff:.0f} MiB")
+		else:print(f"  ✓ Under target by {-diff:.0f} MiB")
+	else:
+		print("  ⚠  Could not parse size from dry-run output")
+
+def _show_floors():
+	print("  Class hard floors (never below without --allow-q3-or-lower):\n")
+	max_n=max(len(c) for c in CLASS_HARD_FLOORS)
+	for cls,floor in sorted(CLASS_HARD_FLOORS.items()):
+		print(f"   {cls:<{max_n}}  → {floor}")
+	print(f"\n  Default floor (unknown class): Q4_K")
+	print(f"  --allow-q3-or-lower enables IQ2_XXS start for: {','.join(sorted(CAN_Q3))}")
+
+# ═══════════════════════════════════════════════════════════════════════════
+# 9. TIERS RUNNER & CLI ENTRYPOINT
+# ════════════════════════════════════════════════════���══════════════════════
+
+TIER_RATIOS={
+	"nano":0.21,
+	"mini":0.27,
+	"compact":0.30,
+	"quality":0.39,
+	"fidelity":0.48,
+}
+
+ALL_RATIOS=dict(TIER_RATIOS)
+TIER_DISPLAY={"nano":"Nano"}
+
+def tier_label(tier:str)->str:
+	return TIER_DISPLAY.get(tier.lower(),tier.capitalize())
+
+def file_size_mib(path:str)->float:
+	return os.path.getsize(path)/1024/1024
+
+def clean_name(path:str)->str:
+	base=os.path.splitext(os.path.basename(path))[0]
+	for suffix in("-no-mtp-BF16","-no-mtp-F16","-BF16-no-mtp","-F16-no-mtp","-BF16","-F16","-bf16","-f16"):
+		if base.endswith(suffix):
+			base=base[:-len(suffix)]
+			break
+	return base
+
+PROVENANCE_MAP="quant-provenance.json"
+
+def provenance(model_path:str)->dict:
+	sidecar=os.path.splitext(model_path)[0]+".provenance.json"
+	if os.path.isfile(sidecar):
+		try:
+			with open(sidecar,"r",encoding="utf-8") as f:return json.load(f)
+		except Exception:pass
+	fmap=os.path.join(os.path.dirname(os.path.abspath(model_path)),PROVENANCE_MAP)
+	if os.path.isfile(fmap):
+		try:
+			with open(fmap,"r",encoding="utf-8") as f:return json.load(f).get(os.path.basename(model_path),{})
+		except Exception:pass
+	return {}
+
+def lineage_tag(model_path:str,override:str="auto")->str:
+	if override=="autoround":return "AutoRound-ASHQ1"
+	if override=="plain":return "ASHQ1"
+	return "AutoRound-ASHQ1" if provenance(model_path).get("autoround") else "ASHQ1"
+
+def int4_lineage_of(model_path:str)->bool:
+	prov=provenance(model_path)
+	try:bits=int(prov.get("bits",16) or 16)
+	except (TypeError,ValueError):bits=16
+	return bool(prov.get("autoround")) and bits<=4
+
+def gen_imatrix(model:str,data:str,output:str,chunks:int)->bool:
+	bin_path=_find_binary("llama-imatrix")
+	if not bin_path:
+		_missing_binary_msg("llama-imatrix")
+		return False
+	cmd=[bin_path,"-m",model,"-f",data,"-o",output,"--chunks",str(chunks)]
+	print("Running:"," ".join(cmd[:4])+" ...")
+	try:result=subprocess.run(cmd)
+	except FileNotFoundError:
+		_missing_binary_msg("llama-imatrix")
+		return False
+	return result.returncode==0
+
+def print_tier_table(bf16_mib:float,model_name:str):
+	print(f"\n  Model: {model_name}")
+	print(f"  BF16 source: {bf16_mib:.0f} MiB ({bf16_mib/1024:.2f} GB)\n")
+	print(f" {'Tier':<12}{'Ratio':>6}{'Target(MiB)':>14}{'Target(GB)':>12}")
+	print(f" {'-'*12}{'-'*6}{'-'*14}{'-'*12}")
+	for tier,ratio in ALL_RATIOS.items():
+		target=bf16_mib*ratio
+		print(f" {tier_label(tier):<12}{ratio*100:>5.0f}%{target:>13.0f}{target/1024:>11.2f}")
+	print()
+
+def run_tier(model:str,imatrix_paths:list,tier:str,target_mib:float,output_dir:str,run:bool,extra_args:list,lineage:str="auto")->bool:
+	name=clean_name(model)
+	pct=round(ALL_RATIOS.get(tier,0)*100)
+	output=os.path.join(output_dir,f"{name}-{lineage_tag(model,lineage)}-{tier_label(tier)}-{pct}pc.gguf")
+	cmd_args=[
+		"--model",model,
+		"--size",f"{target_mib:.0f}",
+		"--output",output,
+		"--profile",tier,
+	]
+	for im in imatrix_paths:cmd_args.extend(["--imatrix",im])
+	cmd_args.extend(extra_args)
+	if run:cmd_args.append("--run")
+	print(f"\n{'='*60}")
+	print(f" [{tier.upper()}] Target: {target_mib:.0f} MiB ({target_mib/1024:.2f} GB)")
+	print(f"  Output: {output}")
+	print(f"{'='*60}\n")
+	return run_main_cli(cmd_args)==0
+
+def tiers_main(args_list=None):
+	parser=argparse.ArgumentParser(
+		description="ASHQ1 Tier Runner — standardized quantization tiers",
+		formatter_class=argparse.RawDescriptionHelpFormatter
+	)
+	parser.add_argument("--model",help="BF16/F16 GGUF model path")
+	parser.add_argument("--imatrix",action="append",default=[],help="Imatrix file path")
+	parser.add_argument("--tier",choices=list(TIER_RATIOS.keys())+["all"],default="all",help="Which tier to run")
+	parser.add_argument("--lineage",choices=["auto","autoround","plain"],default="auto",help="Force output name lineage tag")
+	parser.add_argument("--output-dir",default=None,help="Output directory")
+	parser.add_argument("--run",action="store_true",help="Execute quantization")
+	parser.add_argument("--show-sizes",action="store_true",help="Only print size table and exit")
+	parser.add_argument("--allow-q3-or-lower",action="store_true",help="Allow Q3 or lower")
+	parser.add_argument("--imatrix-method",choices=["max","mean"],default="max",help="Imatrix combination method")
+	parser.add_argument("--verbose",action="store_true",help="Detailed output")
+	parser.add_argument("--gen-imatrix",action="store_true",help="Generate imatrix before quantization")
+	parser.add_argument("--data",help="Calibration data file for imatrix")
+	parser.add_argument("--chunks",type=int,default=100,help="Number of chunks for imatrix")
+	args,remaining=parser.parse_known_args(args_list)
+	if not args.model:
+		parser.print_usage()
+		print("ashq1: error: --model is required")
+		sys.exit(1)
+	if not os.path.isfile(args.model):
+		print(f"ERROR: Model not found: {args.model}")
+		sys.exit(1)
+	bf16_mib=file_size_mib(args.model)
+	model_name=clean_name(args.model)
+	output_dir=args.output_dir or os.path.dirname(os.path.abspath(args.model))
+	os.makedirs(output_dir,exist_ok=True)
+	print("=== ASHQ1 Tier Runner ===")
+	print_tier_table(bf16_mib,model_name)
+	if args.show_sizes:return
+	imatrix_paths=list(args.imatrix)
+	if args.gen_imatrix:
+		if not args.data:
+			print("ERROR: --data required for --gen-imatrix")
+			sys.exit(1)
+		imatrix_path=os.path.join(output_dir,f"{model_name}.imatrix.dat")
+		print(f"\n--- Generating imatrix: {imatrix_path} ---")
+		if not gen_imatrix(args.model,args.data,imatrix_path,args.chunks):
+			print("ERROR: Imatrix generation failed!")
+			sys.exit(1)
+		imatrix_paths.insert(0,imatrix_path)
+	if not imatrix_paths:
+		print("ERROR: --imatrix required (or use --gen-imatrix with --data)")
+		sys.exit(1)
+	for im in imatrix_paths:
+		if not os.path.isfile(im):
+			print(f"ERROR: Imatrix not found: {im}")
+			sys.exit(1)
+	tiers=["mini","compact","quality","fidelity","nano"] if args.tier=="all" else[args.tier]
+	if args.tier=="all" and int4_lineage_of(args.model) and os.environ.get("ASHQ1_INCLUDE_FIDELITY")!="1":
+		tiers.remove("fidelity")
+		print(f"  ℹ  AutoRound int4 lineage detected — Fidelity skipped (e₂ ≪ e₁ beyond {INT4_LINEAGE_CAP} on int4 classes). Set ASHQ1_INCLUDE_FIDELITY=1 to override.")
+	extra_args=[]
+	if args.allow_q3_or_lower:extra_args.append("--allow-q3-or-lower")
+	extra_args.extend(["--imatrix-method",args.imatrix_method,"--lineage",args.lineage])
+	if args.verbose:extra_args.append("--verbose")
+	results={}
+	for tier in tiers:
+		target=bf16_mib*ALL_RATIOS[tier]
+		success=run_tier(args.model,imatrix_paths,tier,target,output_dir,args.run,extra_args,args.lineage)
+		results[tier]=success
+	print(f"\n{'='*60}")
+	print("  SUMMARY")
+	print(f"{'='*60}")
+	mode="quantized" if args.run else "dry-run"
+	for tier,success in results.items():
+		target=bf16_mib*ALL_RATIOS[tier]
+		status="✓ Done" if success else "✗ Failed"
+		print(f" {tier_label(tier):<12}{target:>7.0f} MiB {status} ({mode})")
+	print()
+
+if __name__=="__main__":
+	raw_args=sys.argv[1:]
+	if any(arg in raw_args for arg in("--profile","--show-config","--show-floors","--size")) and "--tier" not in raw_args:
+		sys.exit(run_main_cli(raw_args))
+	else:
+		tiers_main(raw_args)

CHARTER.md

@@ -0,0 +1,65 @@
+# ASHQ1 Technical Charter & Precision Guarantees
+
+This document establishes the architectural principles, mathematical formulation, and invariant guarantees governing the AutoRound + ASHQ1 quantization suite.
+
+---
+
+## 📐 1. Architectural Principles
+
+### 1.1 Dual-Stage Optimization Model
+The suite operates on a two-stage sequential precision boundary:
+1. **Weight-Space Reconditioning (AutoRound)**:
+   Minimizes local layer reconstruction error over calibration activations:
+   $$\min_{\mathbf{W}_q} \|\mathbf{W}\mathbf{X} - \mathbf{W}_q\mathbf{X}\|_F^2 + \lambda \mathcal{R}(\mathbf{W}_q)$$
+   where $\mathbf{W}_q$ represents the discrete integer matrix with continuous scale and zero adjustments.
+2. **Activation-Space Precision Allocation (ASHQ1)**:
+   Given an empirical Fisher Information Proxy $\mathbf{F} = \text{diag}(\mathbf{H})$ derived from activation variances in `imatrix.dat`, ASHQ1 solves a constrained knapsack problem:
+   $$\max_{\{t_i\}} \sum_{i} \mathbf{F}_i \cdot \Delta \mathcal{Q}(t_i) \quad \text{subject to} \quad \sum_{i} \text{Size}(t_i, \text{params}_i) \le \text{Budget}_{\text{VRAM}}$$
+   where $t_i \in \text{TIER\_ORDER}$ and $\Delta \mathcal{Q}(t_i) = 2^{-2 \cdot \text{eff\_bpw}(t_i)}$.
+
+---
+
+## 🛡️ 2. Invariant Precision Guarantees
+
+To prevent numerical drift and safeguard autoregressive context integrity, ASHQ1 enforces absolute tensor classification floors:
+
+```
+┌──────────────────────────────┬───────────────┬────────────────────────────────────────────┐
+│ Tensor Class                 │ Minimum Floor │ Rationale                                  │
+├──────────────────────────────┼───────────────┼────────────────────────────────────────────┤
+│ Norms & Scales (ln, rms)     │ F16 / F32     │ Preserves dynamic scale variance           │
+│ Attention Gates (gate_proj)  │ Q6_K          │ Prevents non-linear token routing collapse │
+│ Recurrent State (ssm_alpha)  │ Q8_0          │ Guarantees stable hidden state accumulation│
+│ Speculative Heads (MTP/NextN)│ Q6_K / Q8_0   │ Maximizes draft token acceptance rate      │
+│ Vision Projectors (mmproj)   │ F32 (critical)│ Protects high-resolution visual grounding  │
+└──────────────────────────────┴───────────────┴────────────────────────────────────────────┘
+```
+
+### 2.1 Pinned Structural Layers
+* **1D Vectors & Bias Tensors**: All vectors with fewer than 4096 elements or non-matrix shapes remain strictly in `F32` or `F16`.
+* **Block Alignment Rules**: Tensors must adhere to integer multiples of the GGML block size (32 or 256 elements). Unaligned shapes are automatically promoted to the nearest valid container (`F16`/`Q8_0`).
+
+### 2.2 Tied-Weight Group Preservation
+When tied layers are detected (such as shared input/output embeddings or symmetric MoE gates), ASHQ1 binds the corresponding parameters into unified equivalence sets. The optimizer updates their quantization tiers simultaneously to prevent directional divergence.
+
+---
+
+## 🔬 3. AutoRound Lineage & Saturation Bounds
+
+When weights are derived from an AutoRound W4A16 source (recorded via `.provenance.json` sidecars):
+* **Information Saturation**: Because the underlying weights have been pre-conditioned for 4-bit representations, assigning container formats above `Q5_K` yields negligible signal recovery ($\Delta \mathcal{Q} \to 0$).
+* **Automated Capping**: The ASHQ1 optimizer caps attention and FFN blocks at `Q5_K`, reallocating spare bit-budget toward recurrent memory states, routing gates, and structural normalization.
+* **Tier Pruning**: On AutoRound int4 lineage, generation of the 48% `Fidelity` tier is skipped by default, focusing compute resources on optimal `Quality` (39%), `Compact` (30%), `Mini` (27%), and `Nano` (21%) variants.
+
+---
+
+## 📈 4. Calibration Dataset Standard
+
+Calibration quality directly determines activation matrix fidelity. The suite implements an exact multi-domain quota:
+
+* **55% Agentic Execution**: Tool-use traces, JSON schema parameters, and multi-turn function call loops.
+* **20% Formal Logic & Code**: Formal mathematical proofs (Lean 4), algorithmic Python implementations, and syntactic structures.
+* **15% Semantic Diversity**: Multilingual sequences, encyclopedic knowledge, and conversational discourse.
+* **10% Frontier Reasoning**: Extended thinking traces and complex reasoning chains.
+
+All samples undergo token-count round-trip verification to ensure consistent sequence boundaries during `llama-imatrix` evaluation.

README.md

@@ -1,3 +1,128 @@
 ---
 license: apache-2.0
+tags:
+- quantization
+- gguf
+- autoround
+- imatrix
+- hybrid-quantization
+- llama.cpp
+- text-generation
 ---
+
+# AutoRound + ASHQ1 Double-Quantization Suite
+
+The **AutoRound + ASHQ1 Suite** delivers a complete pipeline for creating ultra-high-fidelity GGUF models. By combining gradient-guided weight reorganization (**AutoRound W4A16**) with fine-grained activation-aware tensor assignment (**ASHQ1 Imatrix Engine**), this suite establishes a new standard for low-bit LLM compression.
+
+---
+
+## 🌟 Key Architecture & Highlights
+
+```
+┌─────────────────────────┐
+│ Safetensors (Raw / BF16)│
+└────────────┬────────────┘
+             │ 00_SAFETENSORS-to-AutoRound-BF16-GGUF.py
+             ▼
+┌─────────────────────────┐
+│ AutoRound Optimization  │ ──► Iterative sign-rounding & Hessian estimation
+└────────────┬────────────┘
+             │ Streaming dequantization + GGUF encapsulation
+             ▼
+┌─────────────────────────┐
+│ AutoRound-Infused BF16  │ ──► Lineage recorded in sidecar metadata
+└────────────┬────────────┘
+             │ 01_create-calibration-dataset-and-imatrix.py
+             ▼
+┌─────────────────────────┐
+│ Multi-Source Imatrix    │ ──► Agentic, Frontier, Logic & Diversity corpus
+└────────────┬────────────┘
+             │ 02_BF16-GGUF-to-ASHQ1.py (ASHQ1 Engine)
+             ▼
+┌─────────────────────────────────────────────────────────────┐
+│ Standardized ASHQ1 Tiers: Nano • Mini • Compact • Quality   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 1. Dual-Phase Quantization Synergy
+* **Phase 1 (AutoRound W4A16)**: Reconditions original full-precision matrices via small-sample Hessian compensation. The optimized rounding directions remain intact when converted into BF16 GGUF containers.
+* **Phase 2 (ASHQ1 Engine)**: Dissects individual layer activations using multi-source importance matrices (`imatrix.dat`). Assigns precision tiers (`IQ2_XXS` through `Q8_0` and `F32`) dynamically based on layer sensitivity and tensor class.
+
+### 2. Comprehensive Model Architecture Support
+* **Dense & MoE Transformers**: Precise expert protection with token-routing stabilization.
+* **Recurrent & Hybrid Models (GDN / Mamba / RWKV / Qwen3.5)**: Guaranteed `Q8_0` memory state retention to ensure long-context recurrence stability.
+* **Multimodal Towers (CLIP / Vision Encoders)**: Dedicated `ASHQ1-mmproj.py` engine preserving spatial embeddings and layer-normalization vectors in `F32`/`F16`.
+* **Multi-Token Prediction (MTP / NextN)**: Automatic extraction, isolation, and high-precision encoding (`Q6_K`/`Q8_0`) of speculative decoding heads.
+
+---
+
+## 📊 Standardized ASHQ1 Tiers
+
+All tiers maintain strict byte-budget percentages relative to the original unquantized BF16 model:
+
+| Tier | File Ratio | Base Type | Typical Use Case | Target Preservation |
+| :--- | :---: | :---: | :--- | :--- |
+| **Nano** | **21%** | `IQ3_XXS` | Maximum compression, edge & mobile VRAM | Core gates `Q6_K`, Down-proj `IQ2_S` |
+| **Mini** | **27%** | `IQ4_XS` | Efficient high-throughput serving | Balanced `IQ4_XS`/`IQ3_S` distribution |
+| **Compact** | **30%** | `IQ4_XS` | Balanced daily-driver footprint | Down-proj `IQ4_XS`, Gate/Up `IQ3_S` |
+| **Quality** | **39%** | `Q5_K_M` | Near-lossless general deployment | Full `Q4_K`/`Q5_K` attention coverage |
+| **Fidelity** | **48%** | `Q6_K` | Maximum analytical precision (raw BF16 lineage) | High-precision `Q5_K`/`Q6_K`/`Q8_0` mix |
+
+*Note: Models originating from an AutoRound int4 lineage cap their weight allocations at the Quality tier (`Q5_K`/`Q4_K` mix), as theoretical information saturation is fully realized.*
+
+---
+
+## 🛠️ Suite Components
+
+| Script | Purpose |
+| :--- | :--- |
+| `00_SAFETENSORS-to-AutoRound-BF16-GGUF.py` | AutoRound tuner & streaming GGUF builder. Emits lineage provenance sidecars. |
+| `00b_BF16-GGUF-MTP-extract.py` | Standalone speculative draft extractor for Multi-Token Prediction layers. |
+| `01_create-calibration-dataset-and-imatrix.py` | End-to-end dataset builder (Agentic/Frontier/Logic) and GPU-autotuned `llama-imatrix` runner. |
+| `01b_BF16-GGUF-modules-fusion.py` | Lossless merger combining base models, vision projectors (`mmproj`), and MTP heads. |
+| `02_BF16-GGUF-to-ASHQ1.py` | Automated orchestrator executing batch quantization across all target tiers. |
+| `ASHQ1.py` | Core hybrid quantization optimizer with greedy knapsack utility scheduling and tied-weight detection. |
+| `ASHQ1-mmproj.py` | Vision projector quantizer applying selective deep-block boosting and critical layer pinning. |
+
+---
+
+## ⚡ Quick Start
+
+### 1. Requirements
+Ensure CUDA, PyTorch, and `auto-round` are installed:
+```bash
+pip install auto-round torchvision safetensors gguf numpy huggingface_hub
+```
+
+### 2. End-to-End Workflow
+```bash
+# Step 0: Optimize safetensors and produce pristine AutoRound BF16 GGUF
+python 00_SAFETENSORS-to-AutoRound-BF16-GGUF.py ./safetensors/
+
+# Step 1: Compute calibration activation statistics (imatrix)
+python 01_create-calibration-dataset-and-imatrix.py
+
+# Step 2: Generate all ASHQ1 standardized tiers
+python 02_BF16-GGUF-to-ASHQ1.py
+```
+
+### 3. Recommended Inference Parameters
+When serving ASHQ1 quantized models with `llama.cpp`, enable 4-bit KV cache quantization for optimal memory efficiency across extended context lengths:
+```bash
+llama-server -m model-AutoRound-ASHQ1-Quality-39pc.gguf -c 32768 --cache-type-k q4_0 --cache-type-v q4_0 -ngl 99
+```
+
+---
+
+## 📜 Citation & Credits
+
+The AutoRound + ASHQ1 suite builds directly upon fundamental research and tooling across the open-source ecosystem:
+
+* **ASHQ1 (Autonomous Selective Hybrid Quantization)** by **[wepiqx](https://huggingface.co/wepiqx/ASHQ1)**:
+  Original mathematical formulation of the priority-queue-driven knapsack optimizer, tied-group detection using numerical activation hashes, and theoretical MSE reduction scheduling.
+* **Intel AutoRound**:
+  Sign-gradient-based optimization framework for low-bit weight reorganization with Hessian compensation.
+* **llama.cpp** by **[Georgi Gerganov & ggml contributors](https://github.com/ggml-org/llama.cpp)**:
+  Core GGML/GGUF format definitions, runtime execution kernels, and quantization tools (`llama-quantize`, `llama-imatrix`).
+* **Calibration Methodology & Recipes**:
+  Activation corpus curation inspired by **[Bartowski](https://huggingface.co/bartowski)** and multi-matrix combination techniques by **cHunter789**.