zeroquantz 0.1.0__py3-none-any.whl

zeroquantz/quantization/registry.py

@@ -0,0 +1,101 @@
+"""The quantization backend registry.
+
+Built-in backends are registered directly. Third-party backends register through
+the ``zeroquantz.quantizers`` entry-point group, so a plugin package
+(``zeroquantz-awq``, ``zeroquantz-gptq``, ...) becomes available with no change to
+core. ``available_backends()`` reflects what is actually usable on this machine.
+"""
+
+from __future__ import annotations
+
+from zeroquantz.core.exceptions import BackendUnavailableError
+from zeroquantz.quantization.base import QuantizationBackend
+from zeroquantz.utils.logging import get_logger
+
+log = get_logger(__name__)
+
+_ENTRY_POINT_GROUP = "zeroquantz.quantizers"
+
+
+class BackendRegistry:
+    """A collection of quantization backends keyed by name."""
+
+    def __init__(self) -> None:
+        self._backends: dict[str, QuantizationBackend] = {}
+
+    def register(self, backend: QuantizationBackend, *, replace: bool = False) -> None:
+        if backend.name in self._backends and not replace:
+            raise ValueError(f"backend '{backend.name}' is already registered")
+        self._backends[backend.name] = backend
+
+    def all_backends(self) -> list[QuantizationBackend]:
+        """Every registered backend, whether or not its deps are installed."""
+        return list(self._backends.values())
+
+    def available_backends(self) -> list[QuantizationBackend]:
+        """Only backends whose dependencies are importable right now."""
+        return [b for b in self._backends.values() if b.is_available()]
+
+    def names(self) -> list[str]:
+        return list(self._backends)
+
+    def get(self, name: str) -> QuantizationBackend:
+        try:
+            return self._backends[name]
+        except KeyError as exc:
+            known = ", ".join(sorted(self._backends)) or "none"
+            raise BackendUnavailableError(
+                f"No quantization backend named '{name}'.",
+                detail=f"Registered backends: {known}.",
+                suggestions=["zeroquantz recommend <model>"],
+            ) from exc
+
+    def get_for_method(self, method: str) -> QuantizationBackend:
+        for backend in self._backends.values():
+            if method in backend.methods:
+                return backend
+        raise BackendUnavailableError(
+            f"No registered backend provides method '{method}'.",
+            suggestions=["zeroquantz recommend <model>"],
+        )
+
+    def methods(self) -> dict[str, str]:
+        """Map every known method -> the backend that provides it."""
+        return {m: b.name for b in self._backends.values() for m in b.methods}
+
+    def load_plugins(self) -> None:
+        """Discover and register external backends via entry points."""
+        try:
+            from importlib.metadata import entry_points
+        except ImportError:  # pragma: no cover - py<3.8, unreachable on 3.11+
+            return
+        try:
+            eps = entry_points(group=_ENTRY_POINT_GROUP)
+        except TypeError:  # pragma: no cover - very old importlib.metadata
+            eps = entry_points().get(_ENTRY_POINT_GROUP, [])  # type: ignore[attr-defined]
+        for ep in eps:
+            try:
+                factory = ep.load()
+                backend = factory() if isinstance(factory, type) else factory
+                if isinstance(backend, QuantizationBackend):
+                    self.register(backend, replace=True)
+                    log.info("loaded quantization plugin: %s", ep.name)
+            except Exception as exc:  # pragma: no cover - plugin defensive
+                log.warning("failed to load quantization plugin '%s': %s", ep.name, exc)
+
+
+_DEFAULT: BackendRegistry | None = None
+
+
+def default_registry() -> BackendRegistry:
+    """Return the process-wide registry, populated with built-ins + plugins."""
+    global _DEFAULT
+    if _DEFAULT is None:
+        from zeroquantz.quantization.backends import BitsAndBytesBackend, TorchAOBackend
+
+        registry = BackendRegistry()
+        registry.register(BitsAndBytesBackend())
+        registry.register(TorchAOBackend())
+        registry.load_plugins()
+        _DEFAULT = registry
+    return _DEFAULT

zeroquantz/render.py

@@ -0,0 +1,341 @@
+"""Shared Rich renderers.
+
+Both the CLI and the TUI turn a :class:`~zeroquantz.agent.dispatcher.CommandResult`
+into Rich renderables through this module, so a ``/recommend`` looks the same
+whichever surface you run it from. Kept UI-agnostic: functions return Rich
+renderables and never print.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from rich.box import ROUNDED, SIMPLE
+from rich.console import Group, RenderableType
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+
+from zeroquantz.hardware.capabilities import PRECISIONS, PrecisionStatus
+
+if TYPE_CHECKING:
+    from zeroquantz.agent.dispatcher import CommandResult
+
+# ---- palette (OpenCode-style: cyan/green accents, muted secondaries) --------
+ACCENT = "cyan"
+OK = "green"
+WARN = "yellow"
+ERR = "red"
+MUTED = "grey62"
+HEAD = "bold cyan"
+
+
+def _status_text(status: PrecisionStatus) -> Text:
+    style = {
+        PrecisionStatus.SUPPORTED: OK,
+        PrecisionStatus.LIMITED: WARN,
+        PrecisionStatus.UNSUPPORTED: MUTED,
+    }[status]
+    return Text(status.label, style=style)
+
+
+def _kv_table(rows: list[tuple[str, Any]], *, key_style: str = MUTED) -> Table:
+    t = Table.grid(padding=(0, 2))
+    t.add_column(style=key_style, justify="left")
+    t.add_column(style="white")
+    for key, value in rows:
+        t.add_row(key, str(value))
+    return t
+
+
+# ---- individual renderers ---------------------------------------------------
+
+
+def render_model(profile) -> Panel:  # noqa: ANN001
+    rows = profile.summary_rows()
+    body: list[RenderableType] = [_kv_table(rows)]
+    if profile.is_estimated:
+        body.append(Text("\nparameter count estimated from config", style=f"italic {MUTED}"))
+    else:
+        body.append(Text("\nparameter count exact (safetensors headers)", style=f"italic {MUTED}"))
+    return Panel(
+        Group(*body),
+        title=f"[b]{profile.model_id}[/b]",
+        border_style=ACCENT,
+        box=ROUNDED,
+    )
+
+
+def render_hardware(hw) -> Panel:  # noqa: ANN001
+    rows = [("GPU", hw.gpu_name)]
+    if hw.gpu_count > 1:
+        rows.append(("GPUs", f"{hw.gpu_count} devices"))
+    rows.append(("VRAM", f"{hw.total_vram_gb:g} GB" if hw.total_vram_gb else "n/a"))
+    if hw.available_vram_gb is not None:
+        rows.append(("VRAM free", f"{hw.available_vram_gb:g} GB"))
+    if hw.sm:
+        rows.append(("Compute", hw.sm))
+    rows.append(("CUDA", hw.cuda_version or ("detected" if hw.cuda_available else "not detected")))
+    if hw.driver_version:
+        rows.append(("Driver", hw.driver_version))
+    if hw.torch_version:
+        rows.append(("Torch", hw.torch_version))
+    if hw.system_ram_gb:
+        rows.append(("System RAM", f"{hw.system_ram_gb:g} GB"))
+
+    prec = Table.grid(padding=(0, 2))
+    prec.add_column(style=MUTED)
+    prec.add_column()
+    for p in PRECISIONS:
+        prec.add_row(p.upper(), _status_text(hw.status(p)))
+
+    grid = Table.grid(padding=(0, 4))
+    grid.add_column()
+    grid.add_column()
+    grid.add_row(
+        Group(Text("Hardware", style=HEAD), _kv_table(rows)),
+        Group(Text("Supported", style=HEAD), prec),
+    )
+    body: list[RenderableType] = [grid]
+    for note in hw.notes:
+        body.append(Text(note, style=f"italic {MUTED}"))
+    return Panel(Group(*body), border_style=ACCENT, box=ROUNDED)
+
+
+def render_goal(goal) -> Panel:  # noqa: ANN001
+    return Panel(
+        _kv_table(goal.describe()),
+        title="[b]Optimization goal[/b]",
+        border_style=ACCENT,
+        box=ROUNDED,
+    )
+
+
+def _risk_style(label: str) -> str:
+    return {
+        "very low": OK,
+        "low": OK,
+        "moderate": WARN,
+        "high": "red",
+        "very high": "bold red",
+    }.get(label, "white")
+
+
+def render_candidates(payload: dict) -> RenderableType:
+    ranked = payload["ranked"]
+    best = payload.get("best")
+    compare = payload.get("compare", False)
+    pareto_ids = payload.get("pareto_ids", set())
+    best_id = best.candidate.format_id if best else None
+
+    table = Table(box=SIMPLE, expand=False, header_style=HEAD, pad_edge=False)
+    table.add_column("#", justify="right", style=MUTED)
+    if compare:
+        table.add_column("★", justify="center")
+    table.add_column("Strategy", no_wrap=True)
+    table.add_column("bpw", justify="right", no_wrap=True)
+    table.add_column("Size", justify="right", no_wrap=True)
+    table.add_column("VRAM", justify="right", no_wrap=True)
+    table.add_column("Fits", justify="center", no_wrap=True)
+    table.add_column("Max ctx", justify="right", no_wrap=True)
+    table.add_column("Quality", no_wrap=True)
+    table.add_column("Speed", justify="right", no_wrap=True)
+    table.add_column("Exec", no_wrap=True)
+    table.add_column("Notes", style=MUTED, max_width=22, overflow="ellipsis", no_wrap=True)
+
+    exec_label = {"in_env": "in-env", "isolated": "sub-env", "external": "produce", "planned": "roadmap"}
+    for rec in ranked:
+        c = rec.candidate
+        is_best = c.format_id == best_id and not compare
+        prefix = "» " if is_best else "  "
+        name = Text(prefix + c.label, style=f"bold {OK}" if is_best else "white")
+        vram = Text(f"{c.estimated_vram_gb:.1f}", style="white" if c.fits_memory else ERR)
+        fits = Text("✓", style=OK) if c.fits_memory else Text("✗", style=ERR)
+        maxctx = f"{c.max_context/1000:.1f}k" if c.max_context else "—"
+        risk = Text(c.quality_risk_label, style=_risk_style(c.quality_risk_label))
+        row = [str(rec.rank)]
+        if compare:
+            row.append("★" if id(c) in pareto_ids else "")
+        row += [
+            name,
+            f"{c.bits_per_weight:.2f}",
+            f"{c.estimated_size_gb:.1f}",
+            vram,
+            fits,
+            maxctx,
+            risk,
+            f"{c.estimated_speedup:.1f}x",
+            exec_label.get(c.execution, c.execution),
+            "; ".join(c.notes) if c.notes else "",
+        ]
+        table.add_row(*row)
+
+    parts: list[RenderableType] = [table]
+    if best is not None and not compare:
+        rec_body = Group(
+            Text(best.candidate.label, style=f"bold {OK}"),
+            Text(best.reason, style=MUTED),
+        )
+        parts.append(Panel(rec_body, title="[b]Recommended[/b]", border_style=OK, box=ROUNDED))
+    parts.append(Text("estimates, not measurements — run /benchmark to measure", style=f"italic {MUTED}"))
+    return Group(*parts)
+
+
+def render_plan(plan) -> Panel:  # noqa: ANN001
+    table = Table(box=SIMPLE, header_style=HEAD)
+    table.add_column("Modules")
+    table.add_column("Precision", style=ACCENT)
+    for name, prec in plan.grouped_rows():
+        table.add_row(name, prec)
+
+    fit_style = OK if plan.fits_budget else WARN
+    summary = _kv_table(
+        [
+            ("Estimated size", f"{plan.estimated_size_gb:.2f} GB"),
+            ("Estimated VRAM", f"{plan.estimated_vram_gb:.2f} GB"),
+            ("Budget", f"{plan.budget_gb:g} GB" if plan.budget_gb else "n/a"),
+            ("Fits budget", "yes" if plan.fits_budget else "no"),
+        ]
+    )
+    body: list[RenderableType] = [table, Text(""), summary]
+    for note in plan.notes:
+        body.append(Text(note, style=f"italic {WARN}"))
+    return Panel(
+        Group(*body),
+        title=f"[b]Mixed-precision plan · {plan.low_precision}/{plan.high_precision}[/b]",
+        border_style=fit_style,
+        box=ROUNDED,
+    )
+
+
+def render_profile(profile) -> Panel:  # noqa: ANN001
+    table = Table(box=SIMPLE, header_style=HEAD)
+    table.add_column("Layer")
+    table.add_column("Sensitivity", justify="right")
+    table.add_column("", style=MUTED)
+    for ls in profile.top(12):
+        bar = "█" * max(1, round(ls.score * 12))
+        table.add_row(ls.layer, f"{ls.score:.2f}", bar)
+    return Panel(
+        table,
+        title=f"[b]Layer sensitivity · {profile.metric}[/b] (top 12)",
+        border_style=ACCENT,
+        box=ROUNDED,
+    )
+
+
+def render_benchmark(bench) -> Panel:  # noqa: ANN001
+    body: list[RenderableType] = [_kv_table(bench.summary_rows())]
+    for note in bench.notes:
+        body.append(Text(note, style=f"italic {WARN}"))
+    return Panel(
+        Group(*body),
+        title=f"[b]Benchmark · {bench.model_ref}[/b] (measured)",
+        border_style=ACCENT,
+        box=ROUNDED,
+    )
+
+
+def render_verification(vr) -> Panel:  # noqa: ANN001
+    status_style = {"PASS": OK, "FAIL": ERR, "INCONCLUSIVE": WARN}.get(vr.status, "white")
+    rows = vr.summary_rows()
+    table = _kv_table(rows[:-1])
+    body: list[RenderableType] = [
+        table,
+        Text(""),
+        Text(f"Status: {vr.status}", style=f"bold {status_style}"),
+    ]
+    if vr.reasons:
+        body.append(Text("  " + "; ".join(vr.reasons), style=MUTED))
+    return Panel(Group(*body), title="[b]Verification[/b]", border_style=status_style, box=ROUNDED)
+
+
+def render_history(view: list[tuple[int, str, bool]]) -> Panel:
+    table = Table.grid(padding=(0, 2))
+    table.add_column(justify="right", style=MUTED)
+    table.add_column()
+    table.add_column()
+    for idx, label, current in view:
+        marker = Text("→" if current else " ", style=OK)
+        style = "bold white" if current else MUTED
+        table.add_row(f"v{idx}", marker, Text(label, style=style))
+    return Panel(table, title="[b]History[/b]", border_style=ACCENT, box=ROUNDED)
+
+
+def render_sessions(names: list[str]) -> Panel:
+    if not names:
+        body: RenderableType = Text("No saved sessions yet. Use /save to create one.", style=MUTED)
+    else:
+        t = Table.grid(padding=(0, 1))
+        t.add_column(style=MUTED)
+        t.add_column(style="white")
+        for n in names:
+            t.add_row("•", n)
+        body = t
+    return Panel(body, title="[b]Sessions[/b]", border_style=ACCENT, box=ROUNDED)
+
+
+def render_help(commands: tuple[tuple[str, str], ...]) -> Panel:
+    table = Table.grid(padding=(0, 3))
+    table.add_column(style=ACCENT, justify="left")
+    table.add_column(style=MUTED)
+    for cmd, desc in commands:
+        table.add_row(cmd, desc)
+    footer = Text(
+        "\nOr just type naturally: “fit Qwen/Qwen3-8B under 8GB for vLLM, quality first”.",
+        style=f"italic {MUTED}",
+    )
+    return Panel(Group(table, footer), title="[b]ZeroQuantz[/b]", border_style=ACCENT, box=ROUNDED)
+
+
+def render_error(message: str) -> Panel:
+    return Panel(Text(message, style="white"), title="[b red]Error[/b red]", border_style=ERR, box=ROUNDED)
+
+
+def render_message(message: str) -> Text:
+    return Text(message, style="white")
+
+
+def render_quant(result) -> Panel:  # noqa: ANN001
+    rows = [
+        ("Backend", result.backend),
+        ("Method", result.method),
+        ("Elapsed", f"{result.elapsed_s:.1f} s"),
+    ]
+    if result.quantized_size_gb is not None:
+        rows.append(("Quantized size", f"{result.quantized_size_gb:.2f} GB"))
+    if result.output_dir:
+        rows.append(("Output", result.output_dir))
+    return Panel(_kv_table(rows), title="[b]Quantization[/b]", border_style=OK, box=ROUNDED)
+
+
+# ---- top-level dispatch -----------------------------------------------------
+
+_RENDERERS = {
+    "model": lambda r: render_model(r.payload),
+    "hardware": lambda r: render_hardware(r.payload),
+    "goal": lambda r: render_goal(r.payload),
+    "candidates": lambda r: render_candidates(r.payload),
+    "plan": lambda r: render_plan(r.payload),
+    "profile": lambda r: render_profile(r.payload),
+    "benchmark": lambda r: render_benchmark(r.payload),
+    "verification": lambda r: render_verification(r.payload),
+    "history": lambda r: render_history(r.payload),
+    "sessions": lambda r: render_sessions(r.payload),
+    "help": lambda r: render_help(r.payload),
+    "quant": lambda r: render_quant(r.payload),
+    "error": lambda r: render_error(r.message),
+    "message": lambda r: render_message(r.message),
+    "exit": lambda r: render_message(r.message),
+}
+
+
+def render_result(result: CommandResult) -> RenderableType:
+    """Turn any :class:`CommandResult` into a Rich renderable."""
+    renderer = _RENDERERS.get(result.kind)
+    if renderer is None:
+        return render_message(result.message)
+    try:
+        return renderer(result)
+    except Exception:  # pragma: no cover - never let rendering crash the UI
+        return render_message(result.message)

zeroquantz/runtimes/__init__.py

@@ -0,0 +1,18 @@
+"""Runtime adapters and the centralized runtime-compatibility matrix."""
+
+from __future__ import annotations
+
+from zeroquantz.runtimes.compatibility import (
+    RuntimeCompat,
+    compatibility,
+    known_runtimes,
+)
+from zeroquantz.runtimes.registry import RuntimeRegistry, default_runtime_registry
+
+__all__ = [
+    "RuntimeCompat",
+    "RuntimeRegistry",
+    "compatibility",
+    "default_runtime_registry",
+    "known_runtimes",
+]

zeroquantz/runtimes/base.py

@@ -0,0 +1,64 @@
+"""Runtime adapter protocol.
+
+A runtime adapter knows how a deployment target (transformers, vLLM, ...) relates
+to quantized models: which schemes it can serve, whether a given model directory
+looks loadable, and what command/config would run it.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+from pydantic import BaseModel, Field
+
+from zeroquantz.runtimes.compatibility import RuntimeCompat, compatibility
+
+if TYPE_CHECKING:
+    from zeroquantz.quantization.config import QuantizationConfig
+
+
+class ValidationResult(BaseModel):
+    """Result of checking whether a model can run on a runtime."""
+
+    runtime: str
+    ok: bool
+    compat: RuntimeCompat = RuntimeCompat.UNKNOWN
+    messages: list[str] = Field(default_factory=list)
+    warnings: list[str] = Field(default_factory=list)
+    serve_command: str | None = None
+
+
+class RuntimeBackend(ABC):
+    """Abstract base for runtime adapters."""
+
+    name: str = "base"
+    description: str = ""
+
+    def compatibility(self, method: str) -> RuntimeCompat:
+        return compatibility(method, self.name)
+
+    def supports_quantization(self, config: QuantizationConfig) -> bool:
+        """True if this runtime can serve a model quantized with ``config``."""
+        return bool(self.compatibility(config.method))
+
+    @abstractmethod
+    def validate_model(
+        self, path: str, config: QuantizationConfig | None = None
+    ) -> ValidationResult:
+        """Check whether ``path`` looks runnable on this runtime."""
+
+    def serve_command(
+        self, path: str, config: QuantizationConfig | None = None
+    ) -> str | None:
+        """A shell command that would serve the model, or None if not applicable."""
+        return None
+
+    def benchmark(self, path: str, config: QuantizationConfig | None = None):  # noqa: ANN201
+        """Optional runtime-native benchmark. Not implemented for every runtime."""
+        raise NotImplementedError(
+            f"{self.name} does not implement a native benchmark yet."
+        )
+
+    def describe(self) -> dict:
+        return {"name": self.name, "description": self.description}

zeroquantz/runtimes/compatibility.py

@@ -0,0 +1,91 @@
+"""The single source of truth for "does quantization method X work on runtime Y".
+
+Keeping this as one data table (rather than scattering ``if runtime == "vllm"``
+checks across the codebase) is an explicit design requirement: adding a runtime
+or a method means editing one matrix.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class RuntimeCompat(str, Enum):
+    COMPATIBLE = "compatible"
+    LIMITED = "limited"
+    NOT_RECOMMENDED = "not_recommended"
+    UNSUPPORTED = "unsupported"
+    UNKNOWN = "unknown"
+
+    @property
+    def label(self) -> str:
+        return {
+            "compatible": "compatible",
+            "limited": "limited",
+            "not_recommended": "not recommended",
+            "unsupported": "unsupported",
+            "unknown": "unknown",
+        }[self.value]
+
+    @property
+    def rank(self) -> int:
+        """Higher is better — used when scoring candidates for a runtime."""
+        return {
+            "compatible": 3,
+            "limited": 2,
+            "not_recommended": 1,
+            "unknown": 1,
+            "unsupported": 0,
+        }[self.value]
+
+    def __bool__(self) -> bool:
+        return self not in (RuntimeCompat.UNSUPPORTED,)
+
+
+_C = RuntimeCompat.COMPATIBLE
+_L = RuntimeCompat.LIMITED
+_N = RuntimeCompat.NOT_RECOMMENDED
+_U = RuntimeCompat.UNSUPPORTED
+
+# runtime -> method -> compatibility
+_MATRIX: dict[str, dict[str, RuntimeCompat]] = {
+    "transformers": {
+        "nf4": _C,
+        "int8_bnb": _C,
+        "int8_torchao": _C,
+        "int4_torchao": _C,
+        "awq": _C,
+        "gptq": _C,
+        "fp8": _L,
+        "mixed": _C,
+    },
+    "vllm": {
+        "awq": _C,
+        "gptq": _C,
+        "fp8": _C,
+        "int8_torchao": _L,
+        "int4_torchao": _L,
+        "nf4": _N,  # vLLM can load bitsandbytes but it is slow / limited
+        "int8_bnb": _N,
+        "mixed": _L,
+    },
+}
+
+
+def known_runtimes() -> list[str]:
+    return list(_MATRIX)
+
+
+def compatibility(method: str, runtime: str | None) -> RuntimeCompat:
+    """Compatibility of ``method`` with ``runtime``.
+
+    * ``runtime is None`` -> no runtime constraint -> COMPATIBLE.
+    * unknown runtime      -> UNKNOWN (do not penalize; we simply don't know).
+    * known runtime        -> the matrix entry, defaulting to UNSUPPORTED.
+    """
+    if runtime is None:
+        return RuntimeCompat.COMPATIBLE
+    table = _MATRIX.get(runtime.strip().lower())
+    if table is None:
+        return RuntimeCompat.UNKNOWN
+    return table.get(method, RuntimeCompat.UNSUPPORTED)

zeroquantz/runtimes/registry.py

@@ -0,0 +1,70 @@
+"""Runtime adapter registry (mirrors the quantization backend registry)."""
+
+from __future__ import annotations
+
+from zeroquantz.core.exceptions import ZeroQuantzError
+from zeroquantz.runtimes.base import RuntimeBackend
+from zeroquantz.utils.logging import get_logger
+
+log = get_logger(__name__)
+
+_ENTRY_POINT_GROUP = "zeroquantz.runtimes"
+
+
+class RuntimeRegistry:
+    def __init__(self) -> None:
+        self._runtimes: dict[str, RuntimeBackend] = {}
+
+    def register(self, runtime: RuntimeBackend, *, replace: bool = False) -> None:
+        if runtime.name in self._runtimes and not replace:
+            raise ValueError(f"runtime '{runtime.name}' already registered")
+        self._runtimes[runtime.name] = runtime
+
+    def names(self) -> list[str]:
+        return list(self._runtimes)
+
+    def all_runtimes(self) -> list[RuntimeBackend]:
+        return list(self._runtimes.values())
+
+    def get(self, name: str) -> RuntimeBackend:
+        try:
+            return self._runtimes[name.strip().lower()]
+        except KeyError as exc:
+            known = ", ".join(sorted(self._runtimes)) or "none"
+            raise ZeroQuantzError(
+                f"Unknown runtime '{name}'.",
+                detail=f"Known runtimes: {known}.",
+            ) from exc
+
+    def load_plugins(self) -> None:
+        from importlib.metadata import entry_points
+
+        try:
+            eps = entry_points(group=_ENTRY_POINT_GROUP)
+        except TypeError:  # pragma: no cover
+            eps = entry_points().get(_ENTRY_POINT_GROUP, [])  # type: ignore[attr-defined]
+        for ep in eps:
+            try:
+                factory = ep.load()
+                runtime = factory() if isinstance(factory, type) else factory
+                if isinstance(runtime, RuntimeBackend):
+                    self.register(runtime, replace=True)
+            except Exception as exc:  # pragma: no cover
+                log.warning("failed to load runtime plugin '%s': %s", ep.name, exc)
+
+
+_DEFAULT: RuntimeRegistry | None = None
+
+
+def default_runtime_registry() -> RuntimeRegistry:
+    global _DEFAULT
+    if _DEFAULT is None:
+        from zeroquantz.runtimes.transformers import TransformersRuntime
+        from zeroquantz.runtimes.vllm import VLLMRuntime
+
+        registry = RuntimeRegistry()
+        registry.register(TransformersRuntime())
+        registry.register(VLLMRuntime())
+        registry.load_plugins()
+        _DEFAULT = registry
+    return _DEFAULT