/**
 * Tensor Quantization for .rdrr Format
 * Implements Q4_K_M quantization (4-bit with k-means clustering).
 *
 * @module converter/quantizer
 */

/** Q4K block size in elements (256 weights per block) */
export declare const QK_K: number;

/** K-means scale size for Q4K */
export declare const K_SCALE_SIZE: number;

/** Q4K block size in bytes (144 bytes per 256 weights) */
export declare const QK4_K_BLOCK_SIZE: number;

export interface QuantizeResult {
  quantized: Uint8Array;
  numBlocks: number;
  originalSize: number;
  quantizedSize: number;
  compressionRatio: number;
}

export interface QuantizationError {
  mse: number;
  maxError: number;
  snr: number;
}

export declare function float32ToFloat16(value: number): number;

export declare function float16ToFloat32(h: number): number;

export declare function quantizeQ4KBlock(data: Float32Array, offset: number): Uint8Array;

/**
 * Flat Q4K quantization (original behavior).
 * Packs all elements sequentially - blocks may cross row boundaries.
 */
export declare function quantizeToQ4KM(data: Float32Array, shape: number[]): QuantizeResult;

/**
 * Row-wise Q4K quantization for matrix-like tensors.
 * Leading dimensions are treated as batches of rows; each row is padded to
 * the 256-element boundary before quantization.
 */
export declare function quantizeToQ4KMRowWise(data: Float32Array, shape: number[]): QuantizeResult;

/**
 * Transpose a 2D F32 matrix.
 */
export declare function transposeF32(data: Float32Array, shape: [number, number]): Float32Array;

/**
 * Column-wise Q4K quantization for 2D weight matrices.
 * Transposes W[out, K] → W^T[K, out], then applies row-wise quantization.
 */
export declare function quantizeToQ4KMColumnWise(
  data: Float32Array,
  shape: [number, number]
): QuantizeResult & { transposedShape: [number, number] };

export type Q4KLayout = 'row' | 'col' | null;

/**
 * Get expected Q4K size for different layouts.
 */
export declare function getQ4KSize(shape: number[], layout?: Q4KLayout): number;

export declare function dequantizeQ4KM(
  quantized: Uint8Array,
  numBlocks: number,
  shape: number[]
): Float32Array;

export declare function dequantizeQ4KMRowWise(
  quantized: Uint8Array,
  shape: number[]
): Float32Array;

export declare function calculateQuantizationError(
  original: Float32Array,
  reconstructed: Float32Array
): QuantizationError;

export declare function quantizeF16ToQ4KM(f16Data: Uint16Array, shape: number[]): QuantizeResult;

export interface QuantizeOptions {
  /** Also quantize embedding tables (default: false) */
  quantizeEmbeddings?: boolean;
  /** Modules to skip (from HF config) */
  modulesToNotConvert?: string[] | null;
}

export declare function shouldQuantize(
  tensorName: string,
  shape: number[],
  options?: QuantizeOptions
): boolean;

export declare function getQuantizedSize(shape: number[]): number;

/**
 * Per-row symmetric int4 quantization for a 2D weight matrix.
 * Returns packed int4 nibbles (rows × cols/2 bytes) plus per-row scales.
 */
export declare function quantizeToInt4PerRowSymmetric(
  f32Data: Float32Array,
  shape: [number, number]
): { quantized: Uint8Array; scales: Float32Array };

/**
 * Inverse of quantizeToInt4PerRowSymmetric — dequantize packed int4
 * rows back to Float32 using the saved per-row scales.
 */
export declare function dequantizeInt4PerRowSymmetric(
  quantized: Uint8Array,
  scales: Float32Array,
  shape: [number, number]
): Float32Array;