zeroquantz 0.1.0__py3-none-any.whl

zeroquantz/quantization/base.py

@@ -0,0 +1,136 @@
+"""The quantization backend protocol and its result types.
+
+Every quantization implementation — the built-in bitsandbytes/TorchAO backends
+and any third-party plugin — implements :class:`QuantizationBackend`. Core code
+only ever talks to this interface, so there is never an ``if method == "awq"``
+ladder anywhere in ZeroQuantz; new methods arrive by registering a backend.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+from pydantic import BaseModel
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from zeroquantz.core.exceptions import ZeroQuantzError
+    from zeroquantz.hardware.capabilities import HardwareProfile
+    from zeroquantz.models.metadata import ModelProfile
+    from zeroquantz.optimization.constraints import OptimizationGoal
+    from zeroquantz.quantization.config import QuantizationConfig
+
+ProgressCallback = "Callable[[str, float], None]"
+
+
+class MemoryEstimate(BaseModel):
+    """Structured, clearly-*estimated* memory footprint for a config."""
+
+    weight_gb: float
+    vram_gb: float
+    measured: bool = False
+
+    def __float__(self) -> float:  # keeps the spec's "returns a float" contract usable
+        return self.vram_gb
+
+
+@dataclass
+class QuantizationResult:
+    """Outcome of a :meth:`QuantizationBackend.quantize` call.
+
+    ``model`` holds the live quantized module (not serializable) so it can be
+    benchmarked/verified/exported without a round-trip to disk.
+    """
+
+    backend: str
+    method: str
+    config: QuantizationConfig
+    model: Any = None
+    elapsed_s: float = 0.0
+    original_size_gb: float | None = None
+    quantized_size_gb: float | None = None
+    output_dir: str | None = None
+    warnings: list[str] = field(default_factory=list)
+
+
+class QuantizationBackend(ABC):
+    """Abstract base every quantization backend implements."""
+
+    #: Stable identifier used in configs and the registry (e.g. ``"bitsandbytes"``).
+    name: str = "base"
+    #: Human-facing description.
+    description: str = ""
+    #: Method identifiers this backend can produce (values of :class:`QuantMethod`).
+    methods: tuple[str, ...] = ()
+
+    # ---- availability -------------------------------------------------------
+
+    @abstractmethod
+    def is_available(self) -> bool:
+        """True if this backend's dependencies are importable on this machine."""
+
+    def availability_error(self) -> ZeroQuantzError | None:
+        """An actionable error explaining why the backend is unavailable, or None."""
+        return None
+
+    # ---- capability queries -------------------------------------------------
+
+    @abstractmethod
+    def supports(
+        self,
+        model: ModelProfile,
+        hardware: HardwareProfile,
+        runtime: str | None = None,
+        config: QuantizationConfig | None = None,
+    ) -> bool:
+        """Whether this backend can quantize ``model`` on ``hardware`` for ``runtime``."""
+
+    @abstractmethod
+    def default_config(
+        self,
+        method: str,
+        model: ModelProfile,
+        hardware: HardwareProfile,
+        goal: OptimizationGoal | None = None,
+    ) -> QuantizationConfig:
+        """Build a sensible :class:`QuantizationConfig` for ``method``."""
+
+    @abstractmethod
+    def estimate_memory(
+        self, model: ModelProfile, config: QuantizationConfig
+    ) -> MemoryEstimate:
+        """Estimate the post-quantization footprint (weights + runtime VRAM)."""
+
+    # ---- execution ----------------------------------------------------------
+
+    @abstractmethod
+    def quantize(
+        self,
+        model: str | Any,
+        config: QuantizationConfig,
+        *,
+        progress: Callable[[str, float], None] | None = None,
+    ) -> QuantizationResult:
+        """Quantize a model.
+
+        ``model`` may be a Hub id / local path (the backend loads it) or an
+        already-loaded module. Heavy dependencies are imported lazily here so that
+        importing the backend never pulls in torch/transformers.
+        """
+
+    @abstractmethod
+    def export(self, result: QuantizationResult, output_dir: str) -> str:
+        """Write a quantized model to ``output_dir``; return the path written."""
+
+    # ---- introspection ------------------------------------------------------
+
+    def describe(self) -> dict[str, Any]:
+        return {
+            "name": self.name,
+            "description": self.description,
+            "methods": list(self.methods),
+            "available": self.is_available(),
+        }

zeroquantz/quantization/catalog.py

@@ -0,0 +1,321 @@
+"""The ZeroQuantz quantization *format* catalog.
+
+A single, data-only source of truth describing every quantization method/format
+ZeroQuantz knows about: its effective bits-per-weight, the tool that produces it,
+the runtimes that can run it, whether it needs calibration, and how ZeroQuantz can
+execute it (in the main env, in an isolated env, or not yet).
+
+Numbers are drawn from published sources (llama.cpp quantize docs, method papers,
+library docs). GGUF bits-per-weight are whole-tensor averages for an ~8B model.
+Everything here is a heuristic *estimate* used for planning — never a measurement.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+
+
+class Execution(str, Enum):
+    """How ZeroQuantz can run a format."""
+
+    IN_ENV = "in_env"          # runs in the main environment (deps light/compatible)
+    ISOLATED = "isolated"      # run its toolchain in a dedicated sub-environment
+    EXTERNAL = "external"      # produced by an external binary/flow (e.g. llama.cpp)
+    PLANNED = "planned"        # catalogued/estimable, execution not wired in v0.1
+
+
+@dataclass(frozen=True)
+class QuantFormat:
+    """Static description of one quantization format."""
+
+    id: str
+    label: str
+    family: str
+    bits_per_weight: float
+    produced_by: str                       # pip package or tool that creates it
+    runtimes: tuple[str, ...]              # runtimes that can serve it
+    execution: Execution
+    weight_only: bool = True
+    activation_bits: int = 16
+    calibration: str = "none"             # none | optional | required
+    requires_precision: str | None = None  # hardware precision needed to RUN, or None (CPU ok)
+    variable_bpw: bool = False
+    #: True if bits_per_weight is a *whole-model* average (embeddings included), as
+    #: for GGUF; False if it applies only to quantized linear layers (embeddings kept
+    #: at compute precision), as for AWQ/GPTQ/bitsandbytes/TorchAO.
+    whole_model: bool = False
+    #: For IN_ENV formats: the registered backend name + method that executes it.
+    backend: str | None = None
+    method: str | None = None
+    quality_tier: int = 3                  # 1 (poor) .. 5 (near-lossless), rough prior
+    speed_tier: int = 3                    # 1 (slow) .. 5 (fast) on a consumer GPU, rough prior
+    note: str = ""
+    pip: tuple[str, ...] = field(default_factory=tuple)  # deps for an isolated env
+
+    @property
+    def bytes_per_weight(self) -> float:
+        return self.bits_per_weight / 8.0
+
+    @property
+    def needs_isolation(self) -> bool:
+        return self.execution is Execution.ISOLATED
+
+    @property
+    def executable(self) -> bool:
+        return self.execution in (Execution.IN_ENV, Execution.ISOLATED)
+
+
+# Runtime short-names used across the catalog.
+RUNTIMES = (
+    "transformers", "vllm", "sglang", "llamacpp", "exllamav2",
+    "tensorrt_llm", "mlx", "bitnet_cpp", "ollama",
+)
+
+_C = "compatible"
+
+# --- the catalog -------------------------------------------------------------
+
+CATALOG: tuple[QuantFormat, ...] = (
+    # ---- bitsandbytes (in-env) ----
+    QuantFormat("bnb_int8", "bitsandbytes INT8", "bitsandbytes", 8.0, "bitsandbytes",
+                ("transformers", "vllm"), Execution.IN_ENV, calibration="none",
+                requires_precision="int8", quality_tier=5, speed_tier=2,
+                backend="bitsandbytes", method="int8_bnb",
+                note="LLM.int8() outlier-aware; robust, slower kernels.",
+                pip=("bitsandbytes", "transformers", "accelerate")),
+    QuantFormat("nf4", "bitsandbytes NF4", "bitsandbytes", 4.13, "bitsandbytes",
+                ("transformers",), Execution.IN_ENV, calibration="none",
+                requires_precision="int4", quality_tier=3, speed_tier=3,
+                backend="bitsandbytes", method="nf4",
+                note="Best 4-bit dtype for QLoRA finetuning; not a fast-serving format.",
+                pip=("bitsandbytes", "transformers", "accelerate")),
+    QuantFormat("fp4", "bitsandbytes FP4", "bitsandbytes", 4.13, "bitsandbytes",
+                ("transformers",), Execution.IN_ENV, calibration="none",
+                requires_precision="int4", quality_tier=3, speed_tier=3,
+                note="Slightly below NF4 quality.",
+                pip=("bitsandbytes", "transformers", "accelerate")),
+
+    # ---- TorchAO (in-env) ----
+    QuantFormat("torchao_int8", "TorchAO INT8", "torchao", 8.0, "torchao",
+                ("transformers", "vllm"), Execution.IN_ENV, calibration="none",
+                requires_precision="int8", quality_tier=5, speed_tier=4,
+                backend="torchao", method="int8_torchao",
+                note="PyTorch-native int8 weight-only.", pip=("torchao", "transformers")),
+    QuantFormat("torchao_int4", "TorchAO INT4 W4A16", "torchao", 4.25, "torchao",
+                ("transformers", "vllm"), Execution.IN_ENV, calibration="none",
+                requires_precision="int4", quality_tier=3, speed_tier=4,
+                backend="torchao", method="int4_torchao",
+                note="tinygemm int4, group 128; good CUDA speed.", pip=("torchao", "transformers")),
+    QuantFormat("torchao_fp8", "TorchAO FP8", "torchao", 8.0, "torchao",
+                ("transformers", "vllm", "sglang"), Execution.PLANNED, weight_only=False,
+                activation_bits=8, calibration="optional", requires_precision="fp8",
+                quality_tier=5, speed_tier=5, note="Needs FP8 tensor cores (Hopper/Blackwell).",
+                pip=("torchao", "transformers")),
+
+    # ---- ZeroQuantz mixed precision (planning strategy) ----
+    QuantFormat("mixed", "Mixed INT4/INT8", "mixed", 5.0, "zeroquantz planner",
+                ("transformers", "vllm"), Execution.PLANNED, calibration="none",
+                requires_precision="int4", quality_tier=4, speed_tier=3,
+                note="Per-layer plan: sensitive layers INT8, the rest INT4 (see /plan).",
+                pip=()),
+
+    # ---- AWQ / GPTQ / AutoRound (isolated) ----
+    QuantFormat("awq", "AWQ W4A16", "awq", 4.15, "autoawq",
+                ("transformers", "vllm", "sglang", "tensorrt_llm"), Execution.ISOLATED,
+                calibration="required", requires_precision="int4", quality_tier=4, speed_tier=5,
+                note="Activation-aware; fast Marlin kernels; strong 4-bit quality.",
+                pip=("autoawq", "transformers", "accelerate")),
+    QuantFormat("gptq", "GPTQ W4A16", "gptq", 4.15, "gptqmodel",
+                ("transformers", "vllm", "sglang", "exllamav2", "tensorrt_llm"), Execution.ISOLATED,
+                calibration="required", requires_precision="int4", quality_tier=4, speed_tier=5,
+                note="Hessian-based; GPTQModel is the maintained producer.",
+                pip=("gptqmodel", "transformers", "accelerate")),
+    QuantFormat("gptq_3bit", "GPTQ 3-bit", "gptq", 3.25, "gptqmodel",
+                ("transformers", "vllm"), Execution.ISOLATED, calibration="required",
+                requires_precision="int4", quality_tier=2, speed_tier=4,
+                note="Aggressive; noticeable quality drop.", pip=("gptqmodel", "transformers")),
+    QuantFormat("autoround", "AutoRound W4A16", "autoround", 4.15, "auto-round",
+                ("transformers", "vllm", "sglang"), Execution.ISOLATED, calibration="required",
+                requires_precision="int4", quality_tier=5, speed_tier=5,
+                note="Sign-gradient rounding; near-lossless 4-bit; exports GPTQ/AWQ/GGUF.",
+                pip=("auto-round", "transformers", "accelerate")),
+    QuantFormat("autoround_2bit", "AutoRound 2-bit", "autoround", 2.3, "auto-round",
+                ("transformers",), Execution.ISOLATED, calibration="required",
+                requires_precision="int4", quality_tier=2, speed_tier=4,
+                note="SOTA-ish at 2-bit but still lossy.", pip=("auto-round", "transformers")),
+
+    # ---- HQQ (isolated; no calibration) ----
+    QuantFormat("hqq_4bit", "HQQ 4-bit", "hqq", 4.5, "hqq",
+                ("transformers",), Execution.ISOLATED, calibration="none",
+                requires_precision="int4", quality_tier=3, speed_tier=3,
+                note="Calibration-free optimization; very fast to quantize.",
+                pip=("hqq", "transformers", "accelerate")),
+    QuantFormat("hqq_2bit", "HQQ 2-bit", "hqq", 2.5, "hqq",
+                ("transformers",), Execution.ISOLATED, calibration="none",
+                requires_precision="int4", quality_tier=1, speed_tier=3,
+                note="Low-bit; pair with HQQ+ LoRA to recover quality.",
+                pip=("hqq", "transformers", "accelerate")),
+
+    # ---- sub-3-bit specialists (isolated / heavy) ----
+    QuantFormat("aqlm", "AQLM 2-bit", "aqlm", 2.0, "aqlm",
+                ("transformers", "vllm"), Execution.ISOLATED, calibration="required",
+                requires_precision="int4", quality_tier=3, speed_tier=2,
+                note="Best accuracy <3bpw; very expensive to produce.",
+                pip=("aqlm[gpu]", "transformers", "accelerate")),
+    QuantFormat("quip", "QuIP# 2-bit", "quip", 2.0, "quip-sharp",
+                ("transformers",), Execution.PLANNED, calibration="required",
+                requires_precision="int4", quality_tier=3, speed_tier=2,
+                note="E8 lattice + incoherence; near-AQLM at 2-bit; hard to deploy.",
+                pip=("quip-sharp",)),
+    QuantFormat("spinquant", "SpinQuant W4A8", "spinquant", 4.1, "SpinQuant",
+                ("executorch", "transformers"), Execution.PLANNED, weight_only=False,
+                activation_bits=8, calibration="required", requires_precision="int4",
+                quality_tier=4, speed_tier=4, note="Learned rotations; used in official Llama 3.2.",
+                pip=()),
+
+    # ---- ExLlamaV2 EXL2 (isolated; Linux-friendly) ----
+    QuantFormat("exl2_4.0", "EXL2 4.0 bpw", "exl2", 4.0, "exllamav2",
+                ("exllamav2",), Execution.ISOLATED, calibration="required",
+                requires_precision="int4", variable_bpw=True, quality_tier=4, speed_tier=5,
+                note="Mixed per-layer bits; excellent single-GPU speed/quality.",
+                pip=("exllamav2",)),
+    QuantFormat("exl2_5.0", "EXL2 5.0 bpw", "exl2", 5.0, "exllamav2",
+                ("exllamav2",), Execution.ISOLATED, calibration="required",
+                requires_precision="int4", variable_bpw=True, quality_tier=5, speed_tier=5,
+                note="Near-lossless on a single consumer GPU.", pip=("exllamav2",)),
+    QuantFormat("exl2_2.5", "EXL2 2.5 bpw", "exl2", 2.5, "exllamav2",
+                ("exllamav2",), Execution.ISOLATED, calibration="required",
+                requires_precision="int4", variable_bpw=True, quality_tier=2, speed_tier=5,
+                note="Fits big models on small VRAM; graceful degradation.", pip=("exllamav2",)),
+
+    # ---- compressed-tensors via llmcompressor (isolated) ----
+    QuantFormat("ct_fp8", "compressed-tensors FP8 W8A8", "compressed_tensors", 8.0, "llmcompressor",
+                ("vllm", "sglang", "tensorrt_llm"), Execution.ISOLATED, weight_only=False,
+                activation_bits=8, calibration="optional", requires_precision="fp8",
+                quality_tier=5, speed_tier=5, note="Near-lossless on FP8 hardware; fastest 8-bit.",
+                pip=("llmcompressor", "transformers")),
+    QuantFormat("ct_int8", "compressed-tensors INT8 W8A8", "compressed_tensors", 8.0, "llmcompressor",
+                ("vllm", "sglang"), Execution.ISOLATED, weight_only=False, activation_bits=8,
+                calibration="required", requires_precision="int8", quality_tier=4, speed_tier=4,
+                note="SmoothQuant-style W8A8 for Ampere-class GPUs.",
+                pip=("llmcompressor", "transformers")),
+    QuantFormat("ct_int4", "compressed-tensors INT4 W4A16", "compressed_tensors", 4.15, "llmcompressor",
+                ("vllm", "sglang"), Execution.ISOLATED, calibration="required",
+                requires_precision="int4", quality_tier=4, speed_tier=5,
+                note="GPTQ/AWQ-Marlin family with native vLLM serialization.",
+                pip=("llmcompressor", "transformers")),
+    QuantFormat("mxfp4", "MXFP4", "mxfp4", 4.25, "llmcompressor",
+                ("vllm", "sglang", "tensorrt_llm"), Execution.PLANNED, calibration="optional",
+                requires_precision="fp8", quality_tier=4, speed_tier=5,
+                note="OCP microscaling FP4 (blk32); Blackwell/MI355; used for gpt-oss.",
+                pip=("llmcompressor",)),
+    QuantFormat("nvfp4", "NVFP4 W4A4", "nvfp4", 4.5, "modelopt",
+                ("tensorrt_llm", "vllm"), Execution.PLANNED, weight_only=False, activation_bits=4,
+                calibration="required", requires_precision="fp8", quality_tier=4, speed_tier=5,
+                note="NVIDIA FP4 (blk16); Blackwell only; better than MXFP4 at 4-bit.",
+                pip=("nvidia-modelopt",)),
+
+    # ---- Unsloth Dynamic ----
+    QuantFormat("unsloth_dynamic_4bit", "Unsloth Dynamic 4-bit", "unsloth", 4.8, "unsloth",
+                ("transformers",), Execution.ISOLATED, calibration="none",
+                requires_precision="int4", quality_tier=4, speed_tier=3,
+                note="NF4 that skips outlier-sensitive modules; QLoRA-focused (<10% extra VRAM).",
+                pip=("unsloth", "bitsandbytes", "transformers")),
+    QuantFormat("unsloth_ud_q4_k_xl", "Unsloth UD-Q4_K_XL (GGUF)", "unsloth", 5.1, "llama.cpp+imatrix",
+                ("llamacpp", "ollama"), Execution.EXTERNAL, calibration="required",
+                quality_tier=5, speed_tier=4, whole_model=True,
+                note="Dynamic K-quant with curated imatrix; strong at low-bit & MoE.",
+                pip=("gguf",)),
+    QuantFormat("unsloth_ud_q2_k_xl", "Unsloth UD-Q2_K_XL (GGUF)", "unsloth", 2.6, "llama.cpp+imatrix",
+                ("llamacpp", "ollama"), Execution.EXTERNAL, calibration="required",
+                quality_tier=3, speed_tier=4, whole_model=True,
+                note="Dynamic 2-bit; usable quality for its size.", pip=("gguf",)),
+
+    # ---- BitNet 1.58 (ternary, training-time) ----
+    QuantFormat("bitnet_b158", "BitNet b1.58 (ternary)", "bitnet", 1.58, "native-training",
+                ("bitnet_cpp", "llamacpp"), Execution.EXTERNAL, weight_only=False,
+                activation_bits=8, calibration="none", quality_tier=3, speed_tier=5,
+                whole_model=True,
+                note="Ternary {-1,0,1}; requires native ternary training, not post-hoc PTQ.",
+                pip=()),
+
+    # ---- FP8 (generic) ----
+    QuantFormat("fp8", "FP8 (E4M3)", "fp8", 8.0, "llmcompressor/torchao",
+                ("vllm", "sglang", "tensorrt_llm", "transformers"), Execution.ISOLATED,
+                weight_only=False, activation_bits=8, calibration="optional",
+                requires_precision="fp8", quality_tier=5, speed_tier=5,
+                note="Near-lossless 8-bit on FP8 hardware.", pip=("llmcompressor", "transformers")),
+)
+
+# ---- GGUF family (llama.cpp), generated compactly (external, CPU-capable) ----
+# (id_suffix, label, bpw, quality_tier, calibration, note)
+_GGUF: tuple[tuple[str, str, float, int, str, str], ...] = (
+    ("q8_0", "GGUF Q8_0", 8.50, 5, "none", "Effectively lossless; large."),
+    ("q6_k", "GGUF Q6_K", 6.56, 5, "none", "Near-lossless."),
+    ("q5_k_m", "GGUF Q5_K_M", 5.70, 5, "optional", "High quality, common pick."),
+    ("q5_k_s", "GGUF Q5_K_S", 5.57, 4, "optional", "Slightly smaller Q5."),
+    ("q4_k_m", "GGUF Q4_K_M", 4.89, 4, "optional", "The default sweet spot."),
+    ("q4_k_s", "GGUF Q4_K_S", 4.67, 4, "optional", "Smaller Q4."),
+    ("q4_0", "GGUF Q4_0", 4.50, 3, "none", "Legacy fixed 4-bit."),
+    ("iq4_nl", "GGUF IQ4_NL", 4.68, 4, "optional", "Non-linear 4-bit i-quant."),
+    ("iq4_xs", "GGUF IQ4_XS", 4.46, 4, "optional", "Efficient 4-bit i-quant."),
+    ("q3_k_l", "GGUF Q3_K_L", 4.30, 3, "optional", "Larger 3-bit K-quant."),
+    ("q3_k_m", "GGUF Q3_K_M", 4.00, 3, "optional", "Medium 3-bit."),
+    ("iq3_s", "GGUF IQ3_S", 3.66, 3, "required", "3-bit i-quant."),
+    ("q3_k_s", "GGUF Q3_K_S", 3.64, 2, "optional", "Small 3-bit."),
+    ("iq3_xxs", "GGUF IQ3_XXS", 3.25, 2, "required", "Aggressive 3-bit."),
+    ("q2_k", "GGUF Q2_K", 3.16, 2, "optional", "2-bit K-quant."),
+    ("iq2_s", "GGUF IQ2_S", 2.74, 2, "required", "2-bit i-quant."),
+    ("iq2_xs", "GGUF IQ2_XS", 2.59, 1, "required", "Very small 2-bit."),
+    ("iq2_xxs", "GGUF IQ2_XXS", 2.38, 1, "required", "Extremely small 2-bit."),
+    ("iq1_m", "GGUF IQ1_M", 2.15, 1, "required", "~1.75-bit; heavy loss."),
+    ("tq2_0", "GGUF TQ2_0", 2.06, 1, "none", "Ternary 2-bit (BitNet-style)."),
+    ("iq1_s", "GGUF IQ1_S", 1.78, 1, "required", "~1.5–2-bit; extreme loss."),
+    ("tq1_0", "GGUF TQ1_0", 1.69, 1, "none", "Ternary ~1.69-bit."),
+)
+
+
+def _gguf_formats() -> list[QuantFormat]:
+    formats: list[QuantFormat] = []
+    for suffix, label, bpw, qtier, calib, note in _GGUF:
+        formats.append(
+            QuantFormat(
+                id=f"gguf_{suffix}",
+                label=label,
+                family="gguf",
+                bits_per_weight=bpw,
+                produced_by="llama.cpp (llama-quantize)",
+                runtimes=("llamacpp", "ollama"),
+                execution=Execution.EXTERNAL,
+                calibration=calib,
+                requires_precision=None,  # llama.cpp runs on CPU + many GPUs
+                quality_tier=qtier,
+                speed_tier=4,
+                whole_model=True,
+                note=note,
+                pip=("gguf",),
+            )
+        )
+    return formats
+
+
+ALL_FORMATS: tuple[QuantFormat, ...] = tuple(list(CATALOG) + _gguf_formats())
+
+_BY_ID = {f.id: f for f in ALL_FORMATS}
+
+
+def get_format(format_id: str) -> QuantFormat | None:
+    return _BY_ID.get(format_id)
+
+
+def families() -> list[str]:
+    seen: list[str] = []
+    for f in ALL_FORMATS:
+        if f.family not in seen:
+            seen.append(f.family)
+    return seen
+
+
+def formats_by_family(family: str) -> list[QuantFormat]:
+    return [f for f in ALL_FORMATS if f.family == family]

zeroquantz/quantization/config.py

@@ -0,0 +1,106 @@
+"""Quantization configuration types.
+
+A :class:`QuantizationConfig` is the *actionable* description a backend consumes.
+It is deliberately backend-agnostic: ``backend`` + ``method`` select the
+implementation, and the remaining fields describe the numeric scheme. Mixed
+precision is expressed through ``module_overrides`` (a mapping of module-name glob
+-> weight bits) so the same config type covers both uniform and per-layer plans.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+from pydantic import BaseModel, Field
+
+
+class QuantMethod(str, Enum):
+    """Identifiers for the quantization schemes ZeroQuantz knows about.
+
+    v0.1 *implements* the bitsandbytes and TorchAO methods; the rest are declared
+    so the planner/recommender can reason about them and so future backends slot
+    in without touching core enums.
+    """
+
+    # bitsandbytes
+    BNB_NF4 = "nf4"
+    BNB_INT8 = "int8_bnb"
+    # TorchAO
+    TORCHAO_INT8 = "int8_torchao"
+    TORCHAO_INT4 = "int4_torchao"
+    # future backends (declared, not yet implemented)
+    AWQ = "awq"
+    GPTQ = "gptq"
+    AUTOROUND = "autoround"
+    FP8 = "fp8"
+    MXFP4 = "mxfp4"
+    NVFP4 = "nvfp4"
+    MIXED = "mixed"
+
+    def __str__(self) -> str:  # nicer display
+        return self.value
+
+
+class QuantizationConfig(BaseModel):
+    """A concrete, backend-ready quantization configuration."""
+
+    backend: str
+    method: str
+    weight_bits: int = Field(ge=1, le=16)
+    activation_bits: int = 16
+    group_size: int | None = 128
+    compute_dtype: str = "bfloat16"
+    double_quant: bool = False
+    quant_type: str | None = None  # bitsandbytes: "nf4" | "fp4"
+    skip_modules: list[str] = Field(default_factory=lambda: ["lm_head"])
+    # module-name glob -> weight bits, for mixed-precision plans
+    module_overrides: dict[str, int] = Field(default_factory=dict)
+    extra: dict = Field(default_factory=dict)
+
+    @property
+    def is_mixed_precision(self) -> bool:
+        return bool(self.module_overrides)
+
+    @property
+    def weight_precision(self) -> str:
+        """Canonical precision name (for the units/memory math) of the *weights*."""
+        return bits_to_precision(self.weight_bits, self.method)
+
+    @property
+    def label(self) -> str:
+        """Short human label, e.g. ``"bitsandbytes NF4"`` or ``"Mixed INT4/INT8"``."""
+        method_names = {
+            "nf4": "NF4",
+            "int8_bnb": "INT8",
+            "int8_torchao": "INT8",
+            "int4_torchao": "W4A16",
+            "awq": "AWQ W4A16",
+            "gptq": "GPTQ W4A16",
+            "fp8": "FP8",
+            "mixed": "Mixed INT4/INT8",
+        }
+        name = method_names.get(self.method, self.method.upper())
+        # Only prefix with the backend for the real quantization tools; roadmap /
+        # synthetic methods (awq, gptq, fp8, mixed) carry their name alone.
+        if self.backend in ("bitsandbytes", "torchao"):
+            return f"{_backend_display(self.backend)} {name}"
+        return name
+
+
+def bits_to_precision(weight_bits: int, method: str) -> str:
+    """Map (bits, method) -> a precision key understood by :mod:`zeroquantz.utils.units`."""
+    m = method.lower()
+    if m in ("nf4", "fp4"):
+        return "nf4" if m == "nf4" else "fp4"
+    if m == "fp8" or weight_bits == 8 and "fp8" in m:
+        return "fp8"
+    return {16: "float16", 8: "int8", 4: "int4", 3: "int3", 2: "int2"}.get(
+        weight_bits, "int8"
+    )
+
+
+def _backend_display(backend: str) -> str:
+    return {
+        "bitsandbytes": "bitsandbytes",
+        "torchao": "TorchAO",
+    }.get(backend, backend)