numkong 7.0.0 → 7.4.2

package/include/numkong/types.hpp

@@ -45,6 +45,49 @@
  *
  *  @sa `dimensions_per_value<T>()` to convert dimension counts to value counts.
  *  @sa `bits_per_value<T>()` to infer the size of each value.
+ *
+ *  @section fp8_types FP8 Numeric Types
+ *
+ *  There are several variants of 8-bit floating point types supported by different industry memebers
+ *  with different hardware support. None are part of the IEEE 754 standard, but some are part of the
+ *  Open Compute Project (OCP) 8-bit Floating Point Specification (OFP8):
+ *
+ *      Format    Bias  Sign  Exp  Mant  Range   Infinity            NaN               Standard
+ *      E4M3FN    7     1     4    3     ±448    ❌ No               Only 0x7F/0xFF    OCP, NVIDIA, ONNX
+ *      E5M2      15    1     5    2     ±57344  ✅ Yes (0x7C/0xFC)  0x7D-7F, 0xFD-FF  OCP, IEEE-like
+ *      E4M3FNUZ  8     1     4    3     ±240    ❌ No               0x80 only         GraphCore, ONNX
+ *      E5M2FNUZ  16    1     5    2     ±57344  ❌ No               0x80 only         GraphCore, ONNX
+ *
+ *  In currently available and soon incoming harware, only two series of models prioritze FNUZ over OCP:
+ *
+ *  - GraphCore IPUs were the original platform proposing FNUZ
+ *  - AMD MI300 series based on CDNA3 implements FNUZ, but not OCP
+ *  - AMD MI350+ series based on CDNA4 switch to OCP and remove FNUZ
+ *  - NVIDIA Hopper and Blackwell only support E4M3FN, E5M2
+ *  - Intel AVX10.2 defines HF8 (E4M3FN) and BF8 (E5M2) - OCP-aligned
+ *  - Arm implements E4M3 (meaning E4M3FN) and E5M2 with a shared `__mfp8` type and a `FPMR` format selector
+ *
+ *  For brevety, across NumKong, "E4M3" implies "E4M3FN".
+ *
+ *  @section fp6_types FP6 Numeric Types
+ *
+ *  The OCP Microscaling (MX) v1.0 specification defines two 6-bit floating-point formats
+ *  for block-scaled quantization. Both are "FN" (finite-numeric): all bit patterns map
+ *  to real numbers with no Inf or NaN codes. Stored byte-aligned with 2 bits of padding.
+ *
+ *      Format  Bias  Sign  Exp  Mant  Range   Subnormals  Infinity  NaN  Standard
+ *      E2M3    1     1     2    3     ±7.5    14 of 64    ❌ No     ❌   OCP MX v1.0
+ *      E3M2    3     1     3    2     ±28     6 of 64     ❌ No     ❌   OCP MX v1.0
+ *
+ *  E2M3 favors mantissa precision (3 bits) for narrow dynamic range — ideal for activations.
+ *  E3M2 favors exponent range (3 bits) for wider dynamic range — suited for weights.
+ *  Both follow IEEE 754 subnormal rules: when exp=0, the implicit leading bit is 0,
+ *  giving value = (-1)^s × 0.mmm × 2^(1-bias). This provides gradual underflow to zero.
+ *
+ *  No hardware directly computes on FP6. On Arm with FEAT_FP8DOT4, E2M3 values can be
+ *  losslessly promoted to E4M3 (same mantissa width, rebias exponent by +6) and E3M2 to
+ *  E5M2 (same mantissa width, rebias exponent by +12), then fed to FDOT instructions.
+ *  Subnormal values (exp=0) require normalization during this promotion.
  */
 
 #ifndef NK_TYPES_HPP
@@ -2352,10 +2395,13 @@ struct e5m2_t {
  *  @brief Float6 E2M3FN: 1 sign + 2 exponent (bias=1) + 3 mantissa bits, with 2 bits of padding.
  *
  *  Range: [-7.5, +7.5], stored byte-aligned (0b00SEEMMM, upper 2 bits padding).
- *  No Inf/NaN (OCP Microscaling FN format). All 64 bit patterns are valid.
+ *  No Inf/NaN (OCP Microscaling FN format). All 64 bit patterns are valid numbers.
+ *  64 total codes: 48 normal, 14 subnormal (exp=0, mant!=0), 2 zeros (+/-0).
  *  Only 18 of 64 values (28.1%) fall in [-1, +1] — 72% of codes represent |x| > 1.
+ *  Subnormal values span [+/-0.125, +/-0.875] using formula 0.mmm x 2^(1-bias).
  *  Dot products are exact via integer accumulation: every value x 16 is an integer
  *  in [-120, +120], so products fit in i16 and sums fit in i32 without rounding.
+ *  Losslessly promotable to E4M3 by rebiasing exponent +6 (normals) or normalizing (subnormals).
  *
  *  @see https://www.opencompute.org/documents/ocp-microscaling-formats-mx-v1-0-spec-final-pdf
  *  @see https://arxiv.org/abs/2401.14112 (FP6-LLM paper)
@@ -2533,10 +2579,13 @@ struct e2m3_t {
  *  @brief Float6 E3M2FN: 1 sign + 3 exponent (bias=3) + 2 mantissa bits, with 2 bits of padding.
  *
  *  Range: [-28, +28], stored byte-aligned (0b00SEEEMM, upper 2 bits padding).
- *  No Inf/NaN (OCP Microscaling FN format). All 64 bit patterns are valid.
+ *  No Inf/NaN (OCP Microscaling FN format). All 64 bit patterns are valid numbers.
+ *  64 total codes: 56 normal, 6 subnormal (exp=0, mant!=0), 2 zeros (+/-0).
  *  26 of 64 values (40.6%) fall in [-1, +1].
+ *  Subnormal values span [+/-0.0625, +/-0.1875] using formula 0.mm x 2^(1-bias).
  *  Dot products are exact via integer accumulation: every value x 4 is an integer
  *  in [-28, +28], so products fit in i16 and sums fit in i32 without rounding.
+ *  Losslessly promotable to E5M2 by rebiasing exponent +12 (normals) or normalizing (subnormals).
  *
  *  @see https://www.opencompute.org/documents/ocp-microscaling-formats-mx-v1-0-spec-final-pdf
  *  @see https://arxiv.org/abs/2401.14112 (FP6-LLM paper)
@@ -5266,7 +5315,7 @@ struct u4x2_t {
     constexpr std::strong_ordering operator<=>(u4x2_t const &o) const noexcept = default;
 };
 
-#pragma region - Enum Conversion
+#pragma region Enum Conversion
 
 /**
  *  @brief Maps `nk_dtype_t` enum values to their corresponding C++ wrapper types.
@@ -5301,9 +5350,9 @@ template <> struct type_for<nk_i4_k> { using type = i4x2_t; };
 template <> struct type_for<nk_u4_k> { using type = u4x2_t; };
 // clang-format on
 
-#pragma endregion - Enum Conversion
+#pragma endregion Enum Conversion
 
-#pragma region - Numeric Limits
+#pragma region Numeric Limits
 
 /** @brief Get the maximum representable value for a type. */
 template <typename scalar_type_>
@@ -5339,6 +5388,16 @@ constexpr unsigned dimensions_per_value() noexcept {
     return bits_per_value<scalar_type_>() / bits_per_dimension<scalar_type_>();
 }
 
+/**
+ *  @brief The mutable reference type for one logical dimension of a value.
+ *
+ *  For normal types (1 dim per value): a plain `value_type_ &`.
+ *  For sub-byte packed types: a `sub_byte_ref<value_type_>` proxy.
+ */
+template <typename value_type_>
+using value_ref =
+    std::conditional_t<dimensions_per_value<value_type_>() == 1, value_type_ &, sub_byte_ref<value_type_>>;
+
 /**
  *  @brief Extract the word type from a value type.
  *
@@ -5412,9 +5471,9 @@ constexpr std::size_t round_up_to_multiple(std::size_t n) {
     return divide_round_up<multiple_>(n) * multiple_;
 }
 
-#pragma endregion - Numeric Limits
+#pragma endregion Numeric Limits
 
-#pragma region - SIMD Dispatch Helpers
+#pragma region SIMD Dispatch Helpers
 
 /** @brief Controls whether template wrappers dispatch to SIMD C kernels. */
 enum allow_simd_t {
@@ -5553,9 +5612,9 @@ constexpr unsigned count_intersection(u1x8_t a, u1x8_t b) noexcept { return a.in
 /** @brief Count bit-level union for u1x8_t (8 packed bits). Returns popcount of OR. */
 constexpr unsigned count_union(u1x8_t a, u1x8_t b) noexcept { return a.union_size(b); }
 
-#pragma endregion - SIMD Dispatch Helpers
+#pragma endregion SIMD Dispatch Helpers
 
-#pragma region - f118_t Mixed Operators
+#pragma region F118 Mixed Operators
 
 constexpr f118_t operator+(double a, f118_t b) noexcept { return f118_t(a) + b; }
 constexpr f118_t operator-(double a, f118_t b) noexcept { return f118_t(a) - b; }
@@ -5569,9 +5628,9 @@ constexpr bool operator>(double a, f118_t b) noexcept { return f118_t(a) > b; }
 constexpr bool operator<=(double a, f118_t b) noexcept { return f118_t(a) <= b; }
 constexpr bool operator>=(double a, f118_t b) noexcept { return f118_t(a) >= b; }
 
-#pragma endregion - f118_t Mixed Operators
+#pragma endregion F118 Mixed Operators
 
-#pragma region - Concepts
+#pragma region Concepts
 
 template <typename matrix_type_, typename element_type_>
 concept const_matrix_of = requires(matrix_type_ const &m) {
@@ -5596,8 +5655,373 @@ concept packed_matrix_like = requires(packed_type_ const &p) {
     { p.depth() } -> std::convertible_to<std::size_t>;
 };
 
-#pragma endregion - Concepts
+#pragma endregion Concepts
+
+} // namespace ashvardanian::numkong
+
+#if __has_include(<format>)
+#include <format>
+#if defined(__cpp_lib_format) && __cpp_lib_format >= 202110L
+
+namespace ashvardanian::numkong {
+
+/**
+ *  Parsed format spec for NumKong scalar types.
+ *
+ *  Supports the standard format spec grammar `[[fill]align][sign][#][0][width][.precision][type]`:
+ *  - `{}` — clean float value, composes with C++23 range formatting
+ *  - `{:#}` — annotated: `3.14 [0x4248]`
+ *  - `{:.2f}` — precision/type forwarded to `std::formatter<float>`
+ *  - `{:x}` / `{:#x}` / `{:X}` — hex bits (with optional `0x` prefix)
+ *  - `{:b}` / `{:#b}` — binary bits (with optional `0b` prefix)
+ */
+struct scalar_format_spec_t {
+    enum class mode_t : unsigned char { float_val_k, hex_k, binary_k };
+    mode_t mode_ = mode_t::float_val_k;
+    bool annotate_ = false; // '#' in float mode → append [0xHHHH]
+    bool prefix_ = false;   // '#' in hex/binary mode → 0x/0b prefix
+    bool upper_ = false;    // 'X' vs 'x'
+    std::formatter<float> float_fmt_;
+
+    constexpr std::format_parse_context::iterator parse(std::format_parse_context &ctx) {
+        auto it = ctx.begin();
+        auto end = ctx.end();
+        if (it == end || *it == '}') return it;
+
+        // Find last character of the format spec (the type position).
+        auto spec_last = it;
+        for (auto s = it; s != end && *s != '}'; ++s) spec_last = s;
+
+        char type_char = *spec_last;
+        if (type_char == 'x' || type_char == 'X') {
+            mode_ = mode_t::hex_k;
+            upper_ = (type_char == 'X');
+            for (auto s = it; s != spec_last; ++s)
+                if (*s == '#') {
+                    prefix_ = true;
+                    break;
+                }
+            return spec_last + 1;
+        }
+        if (type_char == 'b' || type_char == 'B') {
+            mode_ = mode_t::binary_k;
+            for (auto s = it; s != spec_last; ++s)
+                if (*s == '#') {
+                    prefix_ = true;
+                    break;
+                }
+            return spec_last + 1;
+        }
+
+        // Float mode — '#' means annotate with hex bits.
+        for (auto s = it; s != end && *s != '}'; ++s)
+            if (*s == '#') {
+                annotate_ = true;
+                break;
+            }
+        return float_fmt_.parse(ctx);
+    }
+};
+
+/** Write zero-padded hex to an output iterator. `width` is 1, 2, or 4. Each branch uses a literal format string. */
+inline std::format_context::iterator format_hex_(std::format_context::iterator out, unsigned bits, unsigned width,
+                                                 bool prefix, bool upper) {
+    if (width == 4) {
+        if (prefix && upper) return std::format_to(out, "0X{:04X}", bits);
+        if (prefix) return std::format_to(out, "0x{:04x}", bits);
+        if (upper) return std::format_to(out, "{:04X}", bits);
+        return std::format_to(out, "{:04x}", bits);
+    }
+    if (width == 1) {
+        if (prefix && upper) return std::format_to(out, "0X{:01X}", bits);
+        if (prefix) return std::format_to(out, "0x{:01x}", bits);
+        if (upper) return std::format_to(out, "{:01X}", bits);
+        return std::format_to(out, "{:01x}", bits);
+    }
+    if (prefix && upper) return std::format_to(out, "0X{:02X}", bits);
+    if (prefix) return std::format_to(out, "0x{:02x}", bits);
+    if (upper) return std::format_to(out, "{:02X}", bits);
+    return std::format_to(out, "{:02x}", bits);
+}
+
+/** Write zero-padded binary to an output iterator. `width` is 4, 8, or 16. */
+inline std::format_context::iterator format_bin_(std::format_context::iterator out, unsigned bits, unsigned width,
+                                                 bool prefix) {
+    if (width == 16) {
+        if (prefix) return std::format_to(out, "0b{:016b}", bits);
+        return std::format_to(out, "{:016b}", bits);
+    }
+    if (width == 4) {
+        if (prefix) return std::format_to(out, "0b{:04b}", bits);
+        return std::format_to(out, "{:04b}", bits);
+    }
+    if (prefix) return std::format_to(out, "0b{:08b}", bits);
+    return std::format_to(out, "{:08b}", bits);
+}
+
+/** Write hex annotation suffix: ` [0x{hex}]`. */
+inline std::format_context::iterator format_hex_suffix_(std::format_context::iterator out, unsigned bits,
+                                                        unsigned width) {
+    if (width == 4) return std::format_to(out, " [0x{:04x}]", bits);
+    if (width == 1) return std::format_to(out, " [0x{:01x}]", bits);
+    return std::format_to(out, " [0x{:02x}]", bits);
+}
+
+/**
+ *  Formatter implementation for float-like scalar types (f16, bf16, e4m3, e5m2, e2m3, e3m2).
+ *  @tparam value_type_ The NumKong scalar type.
+ *  @tparam hex_width_ Number of hex digits (4 for 16-bit, 2 for 8-bit).
+ *  @tparam bin_width_ Number of binary digits (16 for 16-bit, 8 for 8-bit).
+ */
+template <typename value_type_, unsigned hex_width_, unsigned bin_width_>
+struct float_scalar_formatter_ {
+    scalar_format_spec_t spec_;
+
+    constexpr std::format_parse_context::iterator parse(std::format_parse_context &ctx) { return spec_.parse(ctx); }
+
+    std::format_context::iterator format(value_type_ v, std::format_context &ctx) const {
+        using mode_t = scalar_format_spec_t::mode_t;
+        unsigned bits;
+        if constexpr (requires { v.to_bits(); }) bits = static_cast<unsigned>(v.to_bits());
+        else bits = static_cast<unsigned>(v.raw_);
+
+        switch (spec_.mode_) {
+        case mode_t::hex_k: return format_hex_(ctx.out(), bits, hex_width_, spec_.prefix_, spec_.upper_);
+        case mode_t::binary_k: return format_bin_(ctx.out(), bits, bin_width_, spec_.prefix_);
+        default: {
+            auto out = spec_.float_fmt_.format(v.to_f32(), ctx);
+            if (spec_.annotate_) out = format_hex_suffix_(out, bits, hex_width_);
+            return out;
+        }
+        }
+    }
+};
 
 } // namespace ashvardanian::numkong
 
+template <>
+struct std::formatter<ashvardanian::numkong::f16_t>
+    : ashvardanian::numkong::float_scalar_formatter_<ashvardanian::numkong::f16_t, 4, 16> {};
+template <>
+struct std::formatter<ashvardanian::numkong::bf16_t>
+    : ashvardanian::numkong::float_scalar_formatter_<ashvardanian::numkong::bf16_t, 4, 16> {};
+template <>
+struct std::formatter<ashvardanian::numkong::e4m3_t>
+    : ashvardanian::numkong::float_scalar_formatter_<ashvardanian::numkong::e4m3_t, 2, 8> {};
+template <>
+struct std::formatter<ashvardanian::numkong::e5m2_t>
+    : ashvardanian::numkong::float_scalar_formatter_<ashvardanian::numkong::e5m2_t, 2, 8> {};
+template <>
+struct std::formatter<ashvardanian::numkong::e2m3_t>
+    : ashvardanian::numkong::float_scalar_formatter_<ashvardanian::numkong::e2m3_t, 2, 8> {};
+template <>
+struct std::formatter<ashvardanian::numkong::e3m2_t>
+    : ashvardanian::numkong::float_scalar_formatter_<ashvardanian::numkong::e3m2_t, 2, 8> {};
+
+template <>
+struct std::formatter<ashvardanian::numkong::i4x2_t> {
+    ashvardanian::numkong::scalar_format_spec_t spec_;
+
+    constexpr std::format_parse_context::iterator parse(std::format_parse_context &ctx) { return spec_.parse(ctx); }
+
+    std::format_context::iterator format(ashvardanian::numkong::i4x2_t v, std::format_context &ctx) const {
+        namespace nk = ashvardanian::numkong;
+        using mode_t = nk::scalar_format_spec_t::mode_t;
+        unsigned bits = static_cast<unsigned>(v.raw_);
+        switch (spec_.mode_) {
+        case mode_t::hex_k: return nk::format_hex_(ctx.out(), bits, 2, spec_.prefix_, spec_.upper_);
+        case mode_t::binary_k: return nk::format_bin_(ctx.out(), bits, 8, spec_.prefix_);
+        default: {
+            auto out = std::format_to(ctx.out(), "({}, {})", static_cast<int>(v.low().raw()),
+                                      static_cast<int>(v.high().raw()));
+            if (spec_.annotate_) out = nk::format_hex_suffix_(out, bits, 2);
+            return out;
+        }
+        }
+    }
+};
+
+template <>
+struct std::formatter<ashvardanian::numkong::u4x2_t> {
+    ashvardanian::numkong::scalar_format_spec_t spec_;
+
+    constexpr std::format_parse_context::iterator parse(std::format_parse_context &ctx) { return spec_.parse(ctx); }
+
+    std::format_context::iterator format(ashvardanian::numkong::u4x2_t v, std::format_context &ctx) const {
+        namespace nk = ashvardanian::numkong;
+        using mode_t = nk::scalar_format_spec_t::mode_t;
+        unsigned bits = static_cast<unsigned>(v.raw_);
+        switch (spec_.mode_) {
+        case mode_t::hex_k: return nk::format_hex_(ctx.out(), bits, 2, spec_.prefix_, spec_.upper_);
+        case mode_t::binary_k: return nk::format_bin_(ctx.out(), bits, 8, spec_.prefix_);
+        default: {
+            auto out = std::format_to(ctx.out(), "({}, {})", static_cast<unsigned>(v.low().raw()),
+                                      static_cast<unsigned>(v.high().raw()));
+            if (spec_.annotate_) out = nk::format_hex_suffix_(out, bits, 2);
+            return out;
+        }
+        }
+    }
+};
+
+template <>
+struct std::formatter<ashvardanian::numkong::u1x8_t> {
+    ashvardanian::numkong::scalar_format_spec_t spec_;
+
+    constexpr std::format_parse_context::iterator parse(std::format_parse_context &ctx) { return spec_.parse(ctx); }
+
+    std::format_context::iterator format(ashvardanian::numkong::u1x8_t v, std::format_context &ctx) const {
+        namespace nk = ashvardanian::numkong;
+        using mode_t = nk::scalar_format_spec_t::mode_t;
+        unsigned bits = static_cast<unsigned>(v.raw_);
+        switch (spec_.mode_) {
+        case mode_t::hex_k: return nk::format_hex_(ctx.out(), bits, 2, spec_.prefix_, spec_.upper_);
+        case mode_t::binary_k: return nk::format_bin_(ctx.out(), bits, 8, spec_.prefix_);
+        default: {
+            auto out = std::format_to(ctx.out(), "0b{:08b}", bits);
+            if (spec_.annotate_) out = nk::format_hex_suffix_(out, bits, 2);
+            return out;
+        }
+        }
+    }
+};
+
+/**
+ *  @brief Formatter for a single signed nibble (-8..7). Supports `{}`, `{:#}`, `{:x}`, `{:b}`.
+ *  Float-precision specs (e.g. `{:.2f}`) are not meaningful and ignored.
+ */
+template <>
+struct std::formatter<ashvardanian::numkong::sub_byte_ref<ashvardanian::numkong::i4x2_t>> {
+    ashvardanian::numkong::scalar_format_spec_t spec_;
+
+    constexpr std::format_parse_context::iterator parse(std::format_parse_context &ctx) { return spec_.parse(ctx); }
+
+    std::format_context::iterator format(ashvardanian::numkong::sub_byte_ref<ashvardanian::numkong::i4x2_t> v,
+                                         std::format_context &ctx) const {
+        namespace nk = ashvardanian::numkong;
+        using mode_t = nk::scalar_format_spec_t::mode_t;
+        unsigned bits = static_cast<unsigned>(v.get()) & 0x0Fu;
+        switch (spec_.mode_) {
+        case mode_t::hex_k: return nk::format_hex_(ctx.out(), bits, 1, spec_.prefix_, spec_.upper_);
+        case mode_t::binary_k: return nk::format_bin_(ctx.out(), bits, 4, spec_.prefix_);
+        default: {
+            auto out = std::format_to(ctx.out(), "{}", static_cast<int>(v.get()));
+            if (spec_.annotate_) out = nk::format_hex_suffix_(out, bits, 1);
+            return out;
+        }
+        }
+    }
+};
+
+/**
+ *  @brief Formatter for a single unsigned nibble (0..15). Supports `{}`, `{:#}`, `{:x}`, `{:b}`.
+ *  Float-precision specs (e.g. `{:.2f}`) are not meaningful and ignored.
+ */
+template <>
+struct std::formatter<ashvardanian::numkong::sub_byte_ref<ashvardanian::numkong::u4x2_t>> {
+    ashvardanian::numkong::scalar_format_spec_t spec_;
+
+    constexpr std::format_parse_context::iterator parse(std::format_parse_context &ctx) { return spec_.parse(ctx); }
+
+    std::format_context::iterator format(ashvardanian::numkong::sub_byte_ref<ashvardanian::numkong::u4x2_t> v,
+                                         std::format_context &ctx) const {
+        namespace nk = ashvardanian::numkong;
+        using mode_t = nk::scalar_format_spec_t::mode_t;
+        unsigned bits = static_cast<unsigned>(v.get());
+        switch (spec_.mode_) {
+        case mode_t::hex_k: return nk::format_hex_(ctx.out(), bits, 1, spec_.prefix_, spec_.upper_);
+        case mode_t::binary_k: return nk::format_bin_(ctx.out(), bits, 4, spec_.prefix_);
+        default: {
+            auto out = std::format_to(ctx.out(), "{}", static_cast<unsigned>(v.get()));
+            if (spec_.annotate_) out = nk::format_hex_suffix_(out, bits, 1);
+            return out;
+        }
+        }
+    }
+};
+
+/** @brief Formatter for a single bit. Only `{}` is supported — hex and binary are not meaningful. */
+template <>
+struct std::formatter<ashvardanian::numkong::sub_byte_ref<ashvardanian::numkong::u1x8_t>> {
+    constexpr std::format_parse_context::iterator parse(std::format_parse_context &ctx) { return ctx.begin(); }
+
+    std::format_context::iterator format(ashvardanian::numkong::sub_byte_ref<ashvardanian::numkong::u1x8_t> v,
+                                         std::format_context &ctx) const {
+        return std::format_to(ctx.out(), "{}", v.get() ? 1u : 0u);
+    }
+};
+
+template <>
+struct std::formatter<ashvardanian::numkong::f16c_t> {
+    ashvardanian::numkong::scalar_format_spec_t spec_;
+
+    constexpr std::format_parse_context::iterator parse(std::format_parse_context &ctx) { return spec_.parse(ctx); }
+
+    std::format_context::iterator format(ashvardanian::numkong::f16c_t v, std::format_context &ctx) const {
+        namespace nk = ashvardanian::numkong;
+        using mode_t = nk::scalar_format_spec_t::mode_t;
+        unsigned re_bits = static_cast<unsigned>(v.real().to_bits());
+        unsigned im_bits = static_cast<unsigned>(v.imag().to_bits());
+        switch (spec_.mode_) {
+        case mode_t::hex_k: {
+            auto out = std::format_to(ctx.out(), "(");
+            out = nk::format_hex_(out, re_bits, 4, spec_.prefix_, spec_.upper_);
+            out = std::format_to(out, ", ");
+            out = nk::format_hex_(out, im_bits, 4, spec_.prefix_, spec_.upper_);
+            return std::format_to(out, ")");
+        }
+        case mode_t::binary_k: {
+            auto out = std::format_to(ctx.out(), "(");
+            out = nk::format_bin_(out, re_bits, 16, spec_.prefix_);
+            out = std::format_to(out, ", ");
+            out = nk::format_bin_(out, im_bits, 16, spec_.prefix_);
+            return std::format_to(out, ")");
+        }
+        default:
+            if (spec_.annotate_)
+                return std::format_to(ctx.out(), "({} [0x{:04x}], {} [0x{:04x}])", v.real().to_f32(), re_bits,
+                                      v.imag().to_f32(), im_bits);
+            return std::format_to(ctx.out(), "({}, {})", v.real().to_f32(), v.imag().to_f32());
+        }
+    }
+};
+
+template <>
+struct std::formatter<ashvardanian::numkong::bf16c_t> {
+    ashvardanian::numkong::scalar_format_spec_t spec_;
+
+    constexpr std::format_parse_context::iterator parse(std::format_parse_context &ctx) { return spec_.parse(ctx); }
+
+    std::format_context::iterator format(ashvardanian::numkong::bf16c_t v, std::format_context &ctx) const {
+        namespace nk = ashvardanian::numkong;
+        using mode_t = nk::scalar_format_spec_t::mode_t;
+        unsigned re_bits = static_cast<unsigned>(v.real().to_bits());
+        unsigned im_bits = static_cast<unsigned>(v.imag().to_bits());
+        switch (spec_.mode_) {
+        case mode_t::hex_k: {
+            auto out = std::format_to(ctx.out(), "(");
+            out = nk::format_hex_(out, re_bits, 4, spec_.prefix_, spec_.upper_);
+            out = std::format_to(out, ", ");
+            out = nk::format_hex_(out, im_bits, 4, spec_.prefix_, spec_.upper_);
+            return std::format_to(out, ")");
+        }
+        case mode_t::binary_k: {
+            auto out = std::format_to(ctx.out(), "(");
+            out = nk::format_bin_(out, re_bits, 16, spec_.prefix_);
+            out = std::format_to(out, ", ");
+            out = nk::format_bin_(out, im_bits, 16, spec_.prefix_);
+            return std::format_to(out, ")");
+        }
+        default:
+            if (spec_.annotate_)
+                return std::format_to(ctx.out(), "({} [0x{:04x}], {} [0x{:04x}])", v.real().to_f32(), re_bits,
+                                      v.imag().to_f32(), im_bits);
+            return std::format_to(ctx.out(), "({}, {})", v.real().to_f32(), v.imag().to_f32());
+        }
+    }
+};
+
+#endif // __cpp_lib_format
+#endif // __has_include(<format>)
+
 #endif // NK_TYPES_HPP