tico 0.1.0.dev250803__py3-none-any.whl → 0.1.0.dev251106__py3-none-any.whl

tico/quantization/wrapq/wrappers/llama/quant_decoder_layer.py

@@ -0,0 +1,176 @@
+# Copyright (c) 2025 Samsung Electronics Co., Ltd. All Rights Reserved
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from typing import Optional, Tuple
+
+import torch
+import torch.nn as nn
+
+from tico.quantization.config.ptq import PTQConfig
+from tico.quantization.wrapq.wrappers.llama.quant_attn import QuantLlamaAttention
+from tico.quantization.wrapq.wrappers.llama.quant_mlp import QuantLlamaMLP
+from tico.quantization.wrapq.wrappers.ptq_wrapper import PTQWrapper
+from tico.quantization.wrapq.wrappers.quant_module_base import QuantModuleBase
+from tico.quantization.wrapq.wrappers.registry import try_register
+
+
+@try_register("transformers.models.llama.modeling_llama.LlamaDecoderLayer")
+class QuantLlamaDecoderLayer(QuantModuleBase):
+    """
+    Quant-aware drop-in replacement for HF `LlamaDecoderLayer`.
+    Signature and return-value are identical to the original.
+
+    ▸ Attention & MLP blocks are replaced by their quantized counterparts
+    ▸ LayerNorms remain FP32 (no fake-quant)
+    ▸ A "static" causal mask is pre-built in `__init__` to avoid
+      dynamic boolean-to-float casts inside `forward`.
+
+    Notes on the causal mask
+    ------------------------
+    Building a boolean mask "inside" `forward` would introduce
+    non-deterministic dynamic ops that an integer-only accelerator cannot
+    fuse easily.  Therefore we:
+
+    1. Pre-compute a full upper-triangular mask of size
+       `[1, 1, max_seq, max_seq]` in `__init__`.
+    2. In `forward`, if the caller passes `attention_mask=None`, we
+       slice the pre-computed template to the current sequence length.
+    """
+
+    def __init__(
+        self,
+        fp_layer: nn.Module,
+        *,
+        qcfg: Optional[PTQConfig] = None,
+        fp_name: Optional[str] = None,
+        return_type: Optional[str] = None,
+    ):
+        """
+        Q) Why do we need `return_type`?
+        A) Different versions of `transformers` wrap the decoder output in
+            different containers: a plain Tensor or a tuple.
+        """
+        self.return_type = return_type
+        if self.return_type is None:
+            import transformers
+
+            v = tuple(map(int, transformers.__version__.split(".")[:2]))
+            self.return_type = "tensor" if v >= (4, 54) else "tuple"
+        assert self.return_type is not None
+        super().__init__(qcfg, fp_name=fp_name)
+
+        # Child QuantConfigs -------------------------------------------------
+        attn_cfg = qcfg.child("self_attn") if qcfg else None
+        mlp_cfg = qcfg.child("mlp") if qcfg else None
+
+        # Quantized sub-modules ---------------------------------------------
+        assert hasattr(fp_layer, "self_attn") and isinstance(
+            fp_layer.self_attn, torch.nn.Module
+        )
+        assert hasattr(fp_layer, "mlp") and isinstance(fp_layer.mlp, torch.nn.Module)
+        self.self_attn = PTQWrapper(
+            fp_layer.self_attn, qcfg=attn_cfg, fp_name=f"{fp_name}.self_attn"
+        )
+        self.mlp = PTQWrapper(fp_layer.mlp, qcfg=mlp_cfg, fp_name=f"{fp_name}.mlp")
+
+        # LayerNorms remain FP (copied from fp_layer to keep weights)
+        assert hasattr(fp_layer, "input_layernorm") and isinstance(
+            fp_layer.input_layernorm, torch.nn.Module
+        )
+        assert hasattr(fp_layer, "post_attention_layernorm") and isinstance(
+            fp_layer.post_attention_layernorm, torch.nn.Module
+        )
+        self.input_layernorm = fp_layer.input_layernorm
+        self.post_attention_layernorm = fp_layer.post_attention_layernorm
+
+        # Static causal mask template ---------------------------------------
+        assert hasattr(fp_layer.self_attn, "config") and hasattr(
+            fp_layer.self_attn.config, "max_position_embeddings"
+        )
+        assert isinstance(fp_layer.self_attn.config.max_position_embeddings, int)
+        max_seq = fp_layer.self_attn.config.max_position_embeddings
+        mask = torch.full((1, 1, max_seq, max_seq), float("-120"))
+        mask.triu_(1)
+        self.register_buffer("causal_mask_template", mask, persistent=False)
+
+    def _slice_causal(self, seq_len: int, device: torch.device) -> torch.Tensor:
+        """Return `[1,1,L,L]` causal mask slice on *device*."""
+        assert isinstance(self.causal_mask_template, torch.Tensor)
+        return self.causal_mask_template[..., :seq_len, :seq_len].to(device)
+
+    def forward(
+        self,
+        hidden_states: torch.Tensor,
+        attention_mask: Optional[torch.Tensor] = None,
+        position_ids: Optional[torch.LongTensor] = None,
+        past_key_value: Optional["Cache"] = None,  # type: ignore[name-defined]
+        output_attentions: Optional[bool] = False,
+        use_cache: Optional[bool] = False,
+        cache_position: Optional[torch.LongTensor] = None,
+        position_embeddings: Optional[tuple[torch.Tensor, torch.Tensor]] = None,
+        **kwargs,
+    ) -> Tuple[torch.Tensor] | torch.Tensor:
+        if output_attentions:
+            raise NotImplementedError(
+                "QuantLlamaDecoderLayer does not support output attention yet."
+            )
+        residual = hidden_states
+        hidden_states = self.input_layernorm(hidden_states)
+
+        if attention_mask is None or attention_mask.dtype == torch.bool:
+            L = hidden_states.size(1)
+            attention_mask = self._slice_causal(L, hidden_states.device)
+
+        attn_out = self.self_attn(
+            hidden_states=hidden_states,
+            attention_mask=attention_mask,
+            position_ids=position_ids,
+            past_key_value=past_key_value,
+            output_attentions=output_attentions,
+            use_cache=use_cache,
+            cache_position=cache_position,
+            position_embeddings=position_embeddings,
+            **kwargs,
+        )
+        if use_cache:
+            hidden_states_attn, _attn_weights, present_key_value = attn_out
+        else:
+            hidden_states_attn, _attn_weights = attn_out
+            present_key_value = None
+
+        hidden_states = residual + hidden_states_attn
+
+        # ─── MLP block ─────────────────────────────────────────────────
+        residual = hidden_states
+        hidden_states = self.post_attention_layernorm(hidden_states)
+        hidden_states = self.mlp(hidden_states)
+        hidden_states = residual + hidden_states
+
+        # Return type policy:
+        # - If use_cache: always return (hidden_states, present_key_value)
+        # - Else: return as configured (tuple/tensor) for HF compatibility
+        if use_cache:
+            return hidden_states, present_key_value  # type: ignore[return-value]
+
+        if self.return_type == "tuple":
+            return (hidden_states,)
+        elif self.return_type == "tensor":
+            return hidden_states
+        else:
+            raise RuntimeError("Invalid return type.")
+
+    # No local observers; just recurse into children
+    def _all_observers(self):
+        yield from self.self_attn._all_observers()
+        yield from self.mlp._all_observers()

tico/quantization/wrapq/wrappers/llama/quant_mlp.py

@@ -0,0 +1,96 @@
+# Copyright (c) 2025 Samsung Electronics Co., Ltd. All Rights Reserved
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from typing import Optional
+
+import torch
+import torch.nn as nn
+
+from tico.quantization.config.ptq import PTQConfig
+from tico.quantization.wrapq.wrappers.ptq_wrapper import PTQWrapper
+from tico.quantization.wrapq.wrappers.quant_module_base import QuantModuleBase
+from tico.quantization.wrapq.wrappers.registry import try_register
+
+
+@try_register("transformers.models.llama.modeling_llama.LlamaMLP")
+class QuantLlamaMLP(QuantModuleBase):
+    def __init__(
+        self,
+        mlp_fp: nn.Module,
+        *,
+        qcfg: Optional[PTQConfig] = None,
+        fp_name: Optional[str] = None,
+    ):
+        super().__init__(qcfg, fp_name=fp_name)
+
+        # ----- child configs (hierarchical override) -------------------
+        gate_cfg = qcfg.child("gate_proj") if qcfg else None
+        up_cfg = qcfg.child("up_proj") if qcfg else None
+        down_cfg = qcfg.child("down_proj") if qcfg else None
+        act_cfg = qcfg.child("act_fn") if qcfg else None
+
+        # ----- wrap three Linear layers -------------------------------
+        assert hasattr(mlp_fp, "gate_proj") and isinstance(
+            mlp_fp.gate_proj, torch.nn.Module
+        )
+        assert hasattr(mlp_fp, "up_proj") and isinstance(
+            mlp_fp.up_proj, torch.nn.Module
+        )
+        assert hasattr(mlp_fp, "down_proj") and isinstance(
+            mlp_fp.down_proj, torch.nn.Module
+        )
+        self.gate_proj = PTQWrapper(
+            mlp_fp.gate_proj, qcfg=gate_cfg, fp_name=f"{fp_name}.gate_proj"
+        )
+        self.up_proj = PTQWrapper(
+            mlp_fp.up_proj, qcfg=up_cfg, fp_name=f"{fp_name}.up_proj"
+        )
+        self.down_proj = PTQWrapper(
+            mlp_fp.down_proj, qcfg=down_cfg, fp_name=f"{fp_name}.down_proj"
+        )
+
+        # ----- activation ---------------------------------------------
+        assert hasattr(mlp_fp, "act_fn") and isinstance(mlp_fp.act_fn, torch.nn.Module)
+        self.act_fn = PTQWrapper(
+            mlp_fp.act_fn, qcfg=act_cfg, fp_name=f"{fp_name}.act_fn"
+        )
+
+        # ----- local observers ----------------------------------------
+        self.act_in_obs = self._make_obs("act_in")
+        self.mul_obs = self._make_obs("mul")
+
+    def forward(self, x: torch.Tensor):
+        # 1) quantize input once
+        x_q = self._fq(x, self.act_in_obs)
+
+        # 2) parallel projections
+        g = self.gate_proj(x_q)
+        u = self.up_proj(x_q)
+
+        # 3) activation on gate
+        a = self.act_fn(g)
+
+        # 4) element-wise product
+        h = self._fq(a * u, self.mul_obs)
+
+        # 5) final projection
+        return self.down_proj(h)
+
+    def _all_observers(self):
+        # local first
+        yield self.act_in_obs
+        yield self.mul_obs
+        # recurse into children that are QuantModuleBase
+        for m in (self.gate_proj, self.up_proj, self.down_proj, self.act_fn):
+            yield from m._all_observers()

tico/quantization/wrapq/wrappers/nn/__init__.py

@@ -0,0 +1 @@
+# DO NOT REMOVE THIS FILE

tico/quantization/wrapq/wrappers/nn/quant_layernorm.py

@@ -0,0 +1,183 @@
+# Copyright (c) 2025 Samsung Electronics Co., Ltd. All Rights Reserved
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from typing import Iterable, Optional, Tuple
+
+import torch
+import torch.nn as nn
+
+from tico.quantization.config.ptq import PTQConfig
+
+from tico.quantization.wrapq.mode import Mode
+from tico.quantization.wrapq.wrappers.quant_module_base import QuantModuleBase
+from tico.quantization.wrapq.wrappers.registry import register
+
+
+@register(nn.LayerNorm)
+class QuantLayerNorm(QuantModuleBase):
+    """
+    QuantLayerNorm — drop-in replacement for nn.LayerNorm that quantizes
+    the elementary steps:
+        1) μ = mean(x, dims)                (mean)
+        2) c = x - μ                        (sub)
+        3) s = c * c                        (square)
+        4) v = mean(s, dims)                (variance)
+        5) e = v + eps                      (add-eps)
+        6) r = rsqrt(e)                     (rsqrt)
+        7) n = c * r                        (normalize)
+        8) y = (n * γ) + β                  (affine), with:
+             • affine_mul : n * γ
+             • affine_add : (n * γ) + β
+    """
+
+    def __init__(
+        self,
+        fp: nn.LayerNorm,
+        *,
+        qcfg: Optional[PTQConfig] = None,
+        fp_name: Optional[str] = None
+    ):
+        super().__init__(qcfg, fp_name=fp_name)
+        self.module = fp
+        self.eps = torch.tensor(self.module.eps)
+        # Number of trailing dims participating in normalization
+        # (PyTorch stores normalized_shape as a tuple even if an int was passed)
+        self._norm_ndim: int = len(fp.normalized_shape)  # safe for int→tuple
+
+        # Activation / intermediate observers
+        self.act_in_obs = self._make_obs("act_in")
+        self.mean_obs = self._make_obs("mean")
+        self.centered_obs = self._make_obs("centered")
+        self.square_obs = self._make_obs("square")
+        self.var_obs = self._make_obs("var")
+        self.eps_obs = self._make_obs("eps")
+        self.add_eps_obs = self._make_obs("add_eps")
+        self.inv_std_obs = self._make_obs("inv_std")
+        self.norm_obs = self._make_obs("norm")
+        self.act_out_obs = self._make_obs("act_out")
+
+        # Optional affine parameter observers (γ, β)
+        self.weight_obs = None
+        self.bias_obs = None
+        self.affine_mul_obs = None
+        self.affine_add_obs = None
+        if self.module.elementwise_affine:
+            if self.module.weight is not None:
+                self.weight_obs = self._make_obs("weight")
+            if self.module.bias is not None:
+                self.bias_obs = self._make_obs("bias")
+            # Per-op observers for (n * w) and (+ b)
+            self.affine_mul_obs = self._make_obs("affine_mul")
+            self.affine_add_obs = self._make_obs("affine_add")
+
+    def enable_calibration(self) -> None:
+        """
+        Switch to CALIB mode and collect *fixed* ranges for affine params
+        immediately, since they do not change across inputs.
+        """
+        super().enable_calibration()
+        if self.module.elementwise_affine:
+            if self.weight_obs is not None and self.module.weight is not None:
+                self.weight_obs.collect(self.module.weight)
+            if self.bias_obs is not None and self.module.bias is not None:
+                self.bias_obs.collect(self.module.bias)
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        # Determine reduction dims (last self._norm_ndim axes)
+        # Example: if x.ndim=4 and norm_ndim=2 → dims=(2,3)
+        dims = tuple(range(x.dim() - self._norm_ndim, x.dim()))
+
+        # 0) input
+        x_q = self._fq(x, self.act_in_obs)
+
+        # 1) mean
+        mu = x_q.mean(dim=dims, keepdim=True)
+        mu_q = self._fq(mu, self.mean_obs)
+
+        # 2) center
+        c = x_q - mu_q
+        c_q = self._fq(c, self.centered_obs)
+
+        # 3) square (elementwise mul)
+        s = c_q * c_q
+        s_q = self._fq(s, self.square_obs)
+
+        # 4) variance (via squared mean)
+        v = s_q.mean(dim=dims, keepdim=True)
+        v_q = self._fq(v, self.var_obs)
+
+        # 5) add eps
+        eps_q = self._fq(self.eps, self.eps_obs)
+        e = v_q + eps_q
+        e_q = self._fq(e, self.add_eps_obs)
+
+        # 6) inverse std
+        r = torch.rsqrt(e_q)
+        r_q = self._fq(r, self.inv_std_obs)
+
+        # 7) normalize
+        n = c_q * r_q
+        n_q = self._fq(n, self.norm_obs)
+
+        # 8) optional affine
+        if self.module.elementwise_affine:
+            w = self.module.weight
+            b = self.module.bias
+            if self._mode is Mode.QUANT:
+                if self.weight_obs is not None and w is not None:
+                    w = self.weight_obs.fake_quant(w)  # type: ignore[assignment]
+                if self.bias_obs is not None and b is not None:
+                    b = self.bias_obs.fake_quant(b)  # type: ignore[assignment]
+            y = n_q
+            # 8a) n * w  (fake-quant the result of the mul)
+            if w is not None:
+                y = y * w
+                if self.affine_mul_obs is not None:
+                    y = self._fq(y, self.affine_mul_obs)
+
+            # 8b) (+ b)  (fake-quant the result of the add)
+            if b is not None:
+                y = y + b
+                if self.affine_add_obs is not None:
+                    y = self._fq(y, self.affine_add_obs)
+        else:
+            y = n_q
+
+        # 9) output activation
+        return self._fq(y, self.act_out_obs)
+
+    def _all_observers(self) -> Iterable:
+        obs: Tuple = (
+            self.act_in_obs,
+            self.mean_obs,
+            self.centered_obs,
+            self.square_obs,
+            self.var_obs,
+            self.eps_obs,
+            self.add_eps_obs,
+            self.inv_std_obs,
+            self.norm_obs,
+            self.act_out_obs,
+        )
+        # Insert affine param observers if present
+        if self.module.elementwise_affine:
+            if self.weight_obs is not None:
+                obs = (self.weight_obs,) + obs
+            if self.bias_obs is not None:
+                obs = obs + (self.bias_obs,)
+            if self.affine_mul_obs is not None:
+                obs = obs + (self.affine_mul_obs,)
+            if self.affine_add_obs is not None:
+                obs = obs + (self.affine_add_obs,)
+        return obs

tico/quantization/wrapq/wrappers/nn/quant_linear.py

@@ -0,0 +1,65 @@
+# Copyright (c) 2025 Samsung Electronics Co., Ltd. All Rights Reserved
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from typing import Optional
+
+import torch.nn as nn
+import torch.nn.functional as F
+
+from tico.quantization.config.ptq import PTQConfig
+
+from tico.quantization.wrapq.mode import Mode
+from tico.quantization.wrapq.qscheme import QScheme
+from tico.quantization.wrapq.wrappers.quant_module_base import QuantModuleBase
+from tico.quantization.wrapq.wrappers.registry import register
+
+
+@register(nn.Linear)
+class QuantLinear(QuantModuleBase):
+    """Per-channel weight fake-quant, eager-output activation fake-quant."""
+
+    def __init__(
+        self,
+        fp: nn.Linear,
+        *,
+        qcfg: Optional[PTQConfig] = None,
+        fp_name: Optional[str] = None
+    ):
+        super().__init__(qcfg, fp_name=fp_name)
+        self.weight_obs = self._make_obs(
+            "weight", qscheme=QScheme.PER_CHANNEL_ASYMM, channel_axis=0
+        )
+        self.act_in_obs = self._make_obs("act_in")
+        self.act_out_obs = self._make_obs("act_out")
+        self.module = fp
+
+    def enable_calibration(self) -> None:
+        super().enable_calibration()
+        # immediately capture the fixed weight range
+        self.weight_obs.collect(self.module.weight)
+
+    def forward(self, x):
+        x_q = self._fq(x, self.act_in_obs)
+
+        w = self.module.weight
+        if self._mode is Mode.QUANT:
+            w = self.weight_obs.fake_quant(w)
+        b = self.module.bias
+
+        out = F.linear(x_q, w, b)
+
+        return self._fq(out, self.act_out_obs)
+
+    def _all_observers(self):
+        return (self.weight_obs, self.act_in_obs, self.act_out_obs)

tico/quantization/wrapq/wrappers/nn/quant_silu.py

@@ -0,0 +1,60 @@
+# Copyright (c) 2025 Samsung Electronics Co., Ltd. All Rights Reserved
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from typing import Optional
+
+import torch
+import torch.nn as nn
+
+from tico.quantization.config.ptq import PTQConfig
+from tico.quantization.wrapq.wrappers.quant_module_base import QuantModuleBase
+from tico.quantization.wrapq.wrappers.registry import try_register
+
+
+@try_register("torch.nn.SiLU", "transformers.activations.SiLUActivation")
+class QuantSiLU(QuantModuleBase):
+    """
+    QuantSiLU — drop-in quantized implementation of the SiLU operation.
+
+    This module quantizes both intermediate tensors:
+        • s  = sigmoid(x)   (logistic)
+        • y  = x * s        (mul)
+    """
+
+    def __init__(
+        self,
+        fp: nn.SiLU,
+        *,
+        qcfg: Optional[PTQConfig] = None,
+        fp_name: Optional[str] = None
+    ):
+        super().__init__(qcfg, fp_name=fp_name)
+        self.act_in_obs = self._make_obs("act_in")
+        self.sig_obs = self._make_obs("sigmoid")
+        self.mul_obs = self._make_obs("mul")
+        self.module = fp
+
+    def forward(self, x: torch.Tensor):
+        x_q = self._fq(x, self.act_in_obs)
+
+        s = torch.sigmoid(x_q)
+        s = self._fq(s, self.sig_obs)
+
+        y = x * s
+        y = self._fq(y, self.mul_obs)
+
+        return y
+
+    def _all_observers(self):
+        return (self.act_in_obs, self.sig_obs, self.mul_obs)

tico/quantization/wrapq/wrappers/ptq_wrapper.py

@@ -0,0 +1,69 @@
+# Copyright (c) 2025 Samsung Electronics Co., Ltd. All Rights Reserved
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from typing import Optional
+
+import torch
+
+from tico.quantization.config.ptq import PTQConfig
+from tico.quantization.wrapq.wrappers.quant_module_base import QuantModuleBase
+from tico.quantization.wrapq.wrappers.registry import lookup
+
+
+class PTQWrapper(QuantModuleBase):
+    """
+    Adapter that turns a fp module into its quantized counterpart.
+
+    It is itself a QuantModuleBase so composite wrappers can treat
+     it exactly like any other quant module.
+    """
+
+    def __init__(
+        self,
+        module: torch.nn.Module,
+        qcfg: Optional[PTQConfig] = None,
+        *,
+        fp_name: Optional[str] = None,
+    ):
+        super().__init__(qcfg)
+        wrapped_cls = lookup(type(module))
+        if wrapped_cls is None:
+            raise NotImplementedError(f"No quant wrapper for {type(module).__name__}")
+        self.wrapped: QuantModuleBase = wrapped_cls(module, qcfg=qcfg, fp_name=fp_name)  # type: ignore[arg-type, misc]
+
+    def forward(self, *args, **kwargs):
+        return self.wrapped(*args, **kwargs)
+
+    def _all_observers(self):
+        """
+        PTQWrapper itself owns NO observers (transparent node).
+        Returning an empty iterator prevents double-processing when parents
+        traverse the tree and then recurse into `self.wrapped`.
+        """
+        return ()  # no local observers
+
+    def named_observers(self):
+        """
+        Proxy to the wrapped module so debugging tools can still enumerate observers.
+        """
+        yield from self.wrapped.named_observers()
+
+    def get_observer(self, name: str):
+        """
+        Proxy to the wrapped module for direct lookup by name.
+        """
+        return self.wrapped.get_observer(name)
+
+    def extra_repr(self) -> str:
+        return self.wrapped.extra_repr()