claude-flow 3.10.3 → 3.10.4

package/.claude/worktrees/adr-120-impl/v3/@claude-flow/plugins/src/integrations/ruvector/quantization.ts

@@ -1,2036 +0,0 @@
-/**
- * RuVector PostgreSQL Bridge - Vector Quantization Module
- *
- * Comprehensive vector quantization for memory reduction:
- * - Scalar Quantization (Int8): 4x memory reduction
- * - Binary Quantization: 32x memory reduction
- * - Product Quantization (PQ): High compression with codebooks
- * - Optimized Product Quantization (OPQ): PQ with learned rotation
- *
- * @module @claude-flow/plugins/integrations/ruvector/quantization
- * @version 1.0.0
- */
-
-// ============================================================================
-// Type Definitions
-// ============================================================================
-
-/**
- * Quantization type options.
- */
-export type QuantizationType = 'scalar' | 'binary' | 'pq' | 'opq';
-
-/**
- * Base interface for all quantizers.
- */
-export interface IQuantizer {
-  /** Quantization type */
-  readonly type: QuantizationType;
-  /** Original vector dimensions */
-  readonly dimensions: number;
-  /** Quantize a batch of vectors */
-  quantize(vectors: number[][]): Uint8Array[] | Int8Array[];
-  /** Dequantize back to float vectors (lossy) */
-  dequantize(quantized: Uint8Array[] | Int8Array[]): number[][];
-  /** Get compression ratio */
-  getCompressionRatio(): number;
-  /** Get memory reduction string (e.g., "4x") */
-  getMemoryReduction(): string;
-}
-
-/**
- * Options for scalar quantization.
- */
-export interface ScalarQuantizationOptions {
-  /** Vector dimensions */
-  dimensions: number;
-  /** Minimum value for calibration (auto-computed if not provided) */
-  minValue?: number;
-  /** Maximum value for calibration (auto-computed if not provided) */
-  maxValue?: number;
-  /** Use symmetric quantization around zero */
-  symmetric?: boolean;
-  /** Number of bits for quantization (default: 8) */
-  bits?: number;
-}
-
-/**
- * Options for binary quantization.
- */
-export interface BinaryQuantizationOptions {
-  /** Vector dimensions */
-  dimensions: number;
-  /** Threshold for binarization (default: 0, use sign) */
-  threshold?: number;
-  /** Use learned thresholds per dimension */
-  learnedThresholds?: number[];
-}
-
-/**
- * Options for product quantization.
- */
-export interface ProductQuantizationOptions {
-  /** Vector dimensions */
-  dimensions: number;
-  /** Number of subvectors (M) - must divide dimensions evenly */
-  numSubvectors: number;
-  /** Number of centroids per subvector (K) - typically 256 */
-  numCentroids: number;
-  /** Maximum iterations for k-means training */
-  maxIterations?: number;
-  /** Convergence tolerance */
-  tolerance?: number;
-  /** Random seed for reproducibility */
-  seed?: number;
-}
-
-/**
- * Options for optimized product quantization.
- */
-export interface OptimizedProductQuantizationOptions extends ProductQuantizationOptions {
-  /** Number of OPQ iterations */
-  opqIterations?: number;
-  /** Learning rate for rotation optimization */
-  learningRate?: number;
-}
-
-/**
- * General quantization options union type.
- */
-export type QuantizationOptions =
-  | ScalarQuantizationOptions
-  | BinaryQuantizationOptions
-  | ProductQuantizationOptions
-  | OptimizedProductQuantizationOptions;
-
-/**
- * Statistics from quantization operations.
- */
-export interface QuantizationStats {
-  /** Compression ratio (original size / compressed size) */
-  compressionRatio: number;
-  /** Memory reduction string (e.g., "4x", "32x") */
-  memoryReduction: string;
-  /** Recall@10 for approximate search (0-1) */
-  recallAt10: number;
-  /** Search speedup compared to exact search */
-  searchSpeedup: number;
-  /** Mean squared error from quantization */
-  mse?: number;
-  /** Training time in milliseconds */
-  trainingTimeMs?: number;
-}
-
-/**
- * Calibration data for scalar quantization.
- */
-interface CalibrationData {
-  minValue: number;
-  maxValue: number;
-  scale: number;
-  zeroPoint: number;
-}
-
-/**
- * Codebook for product quantization.
- */
-interface Codebook {
-  /** Centroids [numCentroids, subvectorDim] */
-  centroids: number[][];
-  /** Assignment counts for statistics */
-  counts: number[];
-}
-
-// ============================================================================
-// Utility Functions
-// ============================================================================
-
-/**
- * Computes the Euclidean distance between two vectors.
- */
-function euclideanDistance(a: number[], b: number[]): number {
-  let sum = 0;
-  for (let i = 0; i < a.length; i++) {
-    const diff = a[i] - b[i];
-    sum += diff * diff;
-  }
-  return Math.sqrt(sum);
-}
-
-/**
- * Computes the squared Euclidean distance.
- */
-function squaredEuclideanDistance(a: number[], b: number[]): number {
-  let sum = 0;
-  for (let i = 0; i < a.length; i++) {
-    const diff = a[i] - b[i];
-    sum += diff * diff;
-  }
-  return sum;
-}
-
-/**
- * Computes the dot product of two vectors.
- */
-function dot(a: number[], b: number[]): number {
-  let sum = 0;
-  for (let i = 0; i < a.length; i++) {
-    sum += a[i] * b[i];
-  }
-  return sum;
-}
-
-/**
- * Computes the norm of a vector.
- */
-function norm(v: number[]): number {
-  return Math.sqrt(dot(v, v));
-}
-
-/**
- * Normalizes a vector to unit length.
- */
-function normalize(v: number[]): number[] {
-  const n = norm(v);
-  if (n < 1e-10) return v.map(() => 0);
-  return v.map(x => x / n);
-}
-
-/**
- * Creates a zero-filled matrix.
- */
-function zerosMatrix(rows: number, cols: number): number[][] {
-  return Array.from({ length: rows }, () => new Array(cols).fill(0));
-}
-
-/**
- * Creates an identity matrix.
- */
-function identityMatrix(n: number): number[][] {
-  const result = zerosMatrix(n, n);
-  for (let i = 0; i < n; i++) {
-    result[i][i] = 1;
-  }
-  return result;
-}
-
-/**
- * Matrix-vector multiplication.
- */
-function matVec(matrix: number[][], vec: number[]): number[] {
-  return matrix.map(row => dot(row, vec));
-}
-
-/**
- * Matrix-matrix multiplication.
- */
-function matMul(a: number[][], b: number[][]): number[][] {
-  const rows = a.length;
-  const cols = b[0].length;
-  const inner = b.length;
-
-  const result = zerosMatrix(rows, cols);
-  for (let i = 0; i < rows; i++) {
-    for (let j = 0; j < cols; j++) {
-      let sum = 0;
-      for (let k = 0; k < inner; k++) {
-        sum += a[i][k] * b[k][j];
-      }
-      result[i][j] = sum;
-    }
-  }
-  return result;
-}
-
-/**
- * Matrix transpose.
- */
-function transpose(matrix: number[][]): number[][] {
-  const rows = matrix.length;
-  const cols = matrix[0].length;
-  const result = zerosMatrix(cols, rows);
-  for (let i = 0; i < rows; i++) {
-    for (let j = 0; j < cols; j++) {
-      result[j][i] = matrix[i][j];
-    }
-  }
-  return result;
-}
-
-/**
- * Simple seeded random number generator (Mulberry32).
- */
-function createRng(seed: number): () => number {
-  return function() {
-    seed = seed + 0x6d2b79f5 | 0;
-    let t = Math.imul(seed ^ seed >>> 15, 1 | seed);
-    t = t + Math.imul(t ^ t >>> 7, 61 | t) ^ t;
-    return ((t ^ t >>> 14) >>> 0) / 4294967296;
-  };
-}
-
-// ============================================================================
-// Scalar Quantization
-// ============================================================================
-
-/**
- * ScalarQuantizer implements per-dimension scalar quantization.
- *
- * Quantizes float32 vectors to int8 for 4x memory reduction.
- * Supports symmetric and asymmetric quantization schemes.
- *
- * @example
- * ```typescript
- * const quantizer = new ScalarQuantizer({ dimensions: 128 });
- * quantizer.calibrate(trainingVectors);
- * const quantized = quantizer.quantize(vectors);
- * const reconstructed = quantizer.dequantize(quantized);
- * ```
- */
-export class ScalarQuantizer implements IQuantizer {
-  readonly type: QuantizationType = 'scalar';
-  readonly dimensions: number;
-
-  private calibration: CalibrationData;
-  private readonly symmetric: boolean;
-  private readonly bits: number;
-  private readonly qmin: number;
-  private readonly qmax: number;
-  private isCalibrated: boolean = false;
-
-  constructor(options: ScalarQuantizationOptions) {
-    this.dimensions = options.dimensions;
-    this.symmetric = options.symmetric ?? false;
-    this.bits = options.bits ?? 8;
-
-    // Compute quantization range based on bits
-    this.qmin = -(1 << (this.bits - 1));
-    this.qmax = (1 << (this.bits - 1)) - 1;
-
-    // Initialize with default calibration
-    this.calibration = {
-      minValue: options.minValue ?? -1,
-      maxValue: options.maxValue ?? 1,
-      scale: 1,
-      zeroPoint: 0,
-    };
-
-    if (options.minValue !== undefined && options.maxValue !== undefined) {
-      this.computeCalibration(options.minValue, options.maxValue);
-      this.isCalibrated = true;
-    }
-  }
-
-  /**
-   * Calibrates the quantizer using sample vectors.
-   *
-   * @param samples - Representative vectors for calibration
-   */
-  calibrate(samples: number[][]): void {
-    if (samples.length === 0) {
-      throw new Error('Cannot calibrate with empty samples');
-    }
-
-    // Find min and max across all dimensions and samples
-    let minValue = Infinity;
-    let maxValue = -Infinity;
-
-    for (const sample of samples) {
-      for (let i = 0; i < sample.length; i++) {
-        minValue = Math.min(minValue, sample[i]);
-        maxValue = Math.max(maxValue, sample[i]);
-      }
-    }
-
-    // Add small margin for numerical stability
-    const range = maxValue - minValue;
-    minValue -= range * 0.01;
-    maxValue += range * 0.01;
-
-    this.computeCalibration(minValue, maxValue);
-    this.isCalibrated = true;
-  }
-
-  private computeCalibration(minValue: number, maxValue: number): void {
-    if (this.symmetric) {
-      // Symmetric quantization: use same scale for positive and negative
-      const absMax = Math.max(Math.abs(minValue), Math.abs(maxValue));
-      this.calibration = {
-        minValue: -absMax,
-        maxValue: absMax,
-        scale: (2 * absMax) / (this.qmax - this.qmin),
-        zeroPoint: 0,
-      };
-    } else {
-      // Asymmetric quantization: full range utilization
-      this.calibration = {
-        minValue,
-        maxValue,
-        scale: (maxValue - minValue) / (this.qmax - this.qmin),
-        zeroPoint: Math.round(this.qmin - minValue / ((maxValue - minValue) / (this.qmax - this.qmin))),
-      };
-    }
-  }
-
-  /**
-   * Quantizes float32 vectors to int8.
-   *
-   * @param vectors - Input vectors
-   * @returns Quantized int8 arrays
-   */
-  quantize(vectors: number[][]): Int8Array[] {
-    if (!this.isCalibrated) {
-      // Auto-calibrate if not done
-      this.calibrate(vectors);
-    }
-
-    const { scale, zeroPoint } = this.calibration;
-
-    return vectors.map((vec) => {
-      const quantized = new Int8Array(vec.length);
-      for (let i = 0; i < vec.length; i++) {
-        const q = Math.round(vec[i] / scale) + zeroPoint;
-        quantized[i] = Math.max(this.qmin, Math.min(this.qmax, q));
-      }
-      return quantized;
-    });
-  }
-
-  /**
-   * Dequantizes int8 arrays back to float32 vectors.
-   *
-   * @param quantized - Quantized int8 arrays
-   * @returns Reconstructed float vectors (lossy)
-   */
-  dequantize(quantized: Int8Array[]): number[][] {
-    const { scale, zeroPoint } = this.calibration;
-
-    return quantized.map((q) => {
-      const vec = new Array(q.length);
-      for (let i = 0; i < q.length; i++) {
-        vec[i] = (q[i] - zeroPoint) * scale;
-      }
-      return vec;
-    });
-  }
-
-  /**
-   * Computes approximate distance using quantized vectors.
-   *
-   * @param a - First quantized vector
-   * @param b - Second quantized vector
-   * @returns Approximate Euclidean distance
-   */
-  quantizedDistance(a: Int8Array, b: Int8Array): number {
-    const { scale } = this.calibration;
-    let sum = 0;
-    for (let i = 0; i < a.length; i++) {
-      const diff = a[i] - b[i];
-      sum += diff * diff;
-    }
-    return Math.sqrt(sum) * scale;
-  }
-
-  getCompressionRatio(): number {
-    // float32 (4 bytes) -> int8 (1 byte) = 4x
-    return 4;
-  }
-
-  getMemoryReduction(): string {
-    return '4x';
-  }
-
-  /**
-   * Gets the current calibration data.
-   */
-  getCalibration(): CalibrationData {
-    return { ...this.calibration };
-  }
-
-  /**
-   * Sets calibration data directly.
-   */
-  setCalibration(calibration: CalibrationData): void {
-    this.calibration = { ...calibration };
-    this.isCalibrated = true;
-  }
-}
-
-// ============================================================================
-// Binary Quantization
-// ============================================================================
-
-/**
- * BinaryQuantizer implements binary quantization for extreme compression.
- *
- * Quantizes float32 vectors to binary (1 bit per dimension) for 32x memory reduction.
- * Uses Hamming distance for fast comparison.
- *
- * @example
- * ```typescript
- * const quantizer = new BinaryQuantizer({ dimensions: 128 });
- * const quantized = quantizer.quantize(vectors);
- * const distance = quantizer.hammingDistance(quantized[0], quantized[1]);
- * ```
- */
-export class BinaryQuantizer implements IQuantizer {
-  readonly type: QuantizationType = 'binary';
-  readonly dimensions: number;
-
-  private threshold: number;
-  private learnedThresholds: number[] | null;
-  private readonly bytesPerVector: number;
-
-  constructor(options: BinaryQuantizationOptions) {
-    this.dimensions = options.dimensions;
-    this.threshold = options.threshold ?? 0;
-    this.learnedThresholds = options.learnedThresholds ?? null;
-
-    // Calculate bytes needed (ceil(dimensions / 8))
-    this.bytesPerVector = Math.ceil(this.dimensions / 8);
-  }
-
-  /**
-   * Learns optimal thresholds per dimension from training data.
-   *
-   * @param samples - Training vectors
-   */
-  learnThresholds(samples: number[][]): void {
-    if (samples.length === 0) {
-      throw new Error('Cannot learn thresholds from empty samples');
-    }
-
-    // Compute median per dimension as threshold
-    this.learnedThresholds = new Array(this.dimensions);
-
-    for (let d = 0; d < this.dimensions; d++) {
-      const values = samples.map(s => s[d]).sort((a, b) => a - b);
-      const mid = Math.floor(values.length / 2);
-      this.learnedThresholds[d] = values.length % 2 === 0
-        ? (values[mid - 1] + values[mid]) / 2
-        : values[mid];
-    }
-  }
-
-  /**
-   * Quantizes float32 vectors to binary.
-   *
-   * @param vectors - Input vectors
-   * @returns Binary quantized arrays (packed bits)
-   */
-  quantize(vectors: number[][]): Uint8Array[] {
-    return vectors.map((vec) => {
-      const binary = new Uint8Array(this.bytesPerVector);
-
-      for (let i = 0; i < this.dimensions; i++) {
-        const threshold = this.learnedThresholds
-          ? this.learnedThresholds[i]
-          : this.threshold;
-
-        if (vec[i] > threshold) {
-          const byteIdx = Math.floor(i / 8);
-          const bitIdx = i % 8;
-          binary[byteIdx] |= (1 << bitIdx);
-        }
-      }
-
-      return binary;
-    });
-  }
-
-  /**
-   * Dequantizes binary arrays back to float vectors.
-   * Note: This is highly lossy and mainly for debugging.
-   *
-   * @param quantized - Binary quantized arrays
-   * @returns Reconstructed vectors (-1 or +1 per dimension)
-   */
-  dequantize(quantized: Uint8Array[]): number[][] {
-    return quantized.map((binary) => {
-      const vec = new Array(this.dimensions);
-
-      for (let i = 0; i < this.dimensions; i++) {
-        const byteIdx = Math.floor(i / 8);
-        const bitIdx = i % 8;
-        const bit = (binary[byteIdx] >> bitIdx) & 1;
-        vec[i] = bit === 1 ? 1 : -1;
-      }
-
-      return vec;
-    });
-  }
-
-  /**
-   * Computes Hamming distance between two binary vectors.
-   *
-   * @param a - First binary vector
-   * @param b - Second binary vector
-   * @returns Hamming distance (number of differing bits)
-   */
-  hammingDistance(a: Uint8Array, b: Uint8Array): number {
-    let distance = 0;
-    for (let i = 0; i < a.length; i++) {
-      const xor = a[i] ^ b[i];
-      // Count bits using Brian Kernighan's algorithm
-      let bits = xor;
-      while (bits) {
-        distance++;
-        bits &= bits - 1;
-      }
-    }
-    return distance;
-  }
-
-  /**
-   * Two-stage search: binary filter + rerank with exact distances.
-   *
-   * @param query - Query vector (float)
-   * @param candidates - Candidate vectors (float)
-   * @param k - Number of results to return
-   * @param filterRatio - Ratio of candidates to keep after binary filter (default: 10)
-   * @returns Indices of top-k candidates after reranking
-   */
-  searchWithRerank(
-    query: number[],
-    candidates: number[][],
-    k: number,
-    filterRatio: number = 10
-  ): number[] {
-    // Step 1: Quantize query and all candidates
-    const queryBinary = this.quantize([query])[0];
-    const candidatesBinary = this.quantize(candidates);
-
-    // Step 2: Compute Hamming distances
-    const distances: Array<{ index: number; hamming: number }> = [];
-    for (let i = 0; i < candidatesBinary.length; i++) {
-      distances.push({
-        index: i,
-        hamming: this.hammingDistance(queryBinary, candidatesBinary[i]),
-      });
-    }
-
-    // Step 3: Filter top candidates by Hamming distance
-    distances.sort((a, b) => a.hamming - b.hamming);
-    const numCandidates = Math.min(k * filterRatio, candidates.length);
-    const filtered = distances.slice(0, numCandidates);
-
-    // Step 4: Rerank filtered candidates with exact Euclidean distance
-    const reranked: Array<{ index: number; distance: number }> = [];
-    for (const { index } of filtered) {
-      reranked.push({
-        index,
-        distance: euclideanDistance(query, candidates[index]),
-      });
-    }
-
-    // Step 5: Sort by exact distance and return top-k
-    reranked.sort((a, b) => a.distance - b.distance);
-    return reranked.slice(0, k).map(r => r.index);
-  }
-
-  /**
-   * Batch Hamming distance computation.
-   *
-   * @param query - Query binary vector
-   * @param candidates - Candidate binary vectors
-   * @returns Array of Hamming distances
-   */
-  batchHammingDistance(query: Uint8Array, candidates: Uint8Array[]): number[] {
-    return candidates.map(c => this.hammingDistance(query, c));
-  }
-
-  getCompressionRatio(): number {
-    // float32 (32 bits) -> binary (1 bit) = 32x
-    return 32;
-  }
-
-  getMemoryReduction(): string {
-    return '32x';
-  }
-}
-
-// ============================================================================
-// Product Quantization
-// ============================================================================
-
-/**
- * ProductQuantizer implements product quantization for high compression.
- *
- * Splits vectors into M subvectors and quantizes each to K centroids.
- * Memory: M * ceil(log2(K)) bits per vector (e.g., M=8, K=256 = 8 bytes)
- *
- * @example
- * ```typescript
- * const pq = new ProductQuantizer({
- *   dimensions: 128,
- *   numSubvectors: 8,
- *   numCentroids: 256
- * });
- * await pq.train(trainingVectors);
- * const codes = pq.encode(vectors);
- * const distances = pq.computeDistances(query, codes);
- * ```
- */
-export class ProductQuantizer implements IQuantizer {
-  readonly type: QuantizationType = 'pq';
-  readonly dimensions: number;
-  readonly numSubvectors: number;
-  readonly numCentroids: number;
-  readonly subvectorDim: number;
-
-  protected codebooks: Codebook[] = [];
-  protected isTrained: boolean = false;
-  protected readonly maxIterations: number;
-  protected readonly tolerance: number;
-  protected readonly rng: () => number;
-
-  constructor(options: ProductQuantizationOptions) {
-    this.dimensions = options.dimensions;
-    this.numSubvectors = options.numSubvectors;
-    this.numCentroids = options.numCentroids;
-
-    // Validate dimensions divisibility
-    if (options.dimensions % options.numSubvectors !== 0) {
-      throw new Error(
-        `Dimensions (${options.dimensions}) must be divisible by numSubvectors (${options.numSubvectors})`
-      );
-    }
-
-    this.subvectorDim = options.dimensions / options.numSubvectors;
-    this.maxIterations = options.maxIterations ?? 100;
-    this.tolerance = options.tolerance ?? 1e-6;
-    this.rng = createRng(options.seed ?? 42);
-  }
-
-  /**
-   * Trains codebooks from training data using k-means clustering.
-   *
-   * @param vectors - Training vectors
-   */
-  async train(vectors: number[][]): Promise<void> {
-    if (vectors.length < this.numCentroids) {
-      throw new Error(
-        `Need at least ${this.numCentroids} training vectors, got ${vectors.length}`
-      );
-    }
-
-    this.codebooks = [];
-
-    // Train a codebook for each subvector
-    for (let m = 0; m < this.numSubvectors; m++) {
-      // Extract subvectors
-      const subvectors = this.extractSubvectors(vectors, m);
-
-      // Train codebook using k-means
-      const codebook = await this.trainCodebook(subvectors);
-      this.codebooks.push(codebook);
-    }
-
-    this.isTrained = true;
-  }
-
-  /**
-   * Extracts the m-th subvector from all vectors.
-   */
-  protected extractSubvectors(vectors: number[][], m: number): number[][] {
-    const start = m * this.subvectorDim;
-    return vectors.map(v => v.slice(start, start + this.subvectorDim));
-  }
-
-  /**
-   * Trains a single codebook using k-means clustering.
-   */
-  protected async trainCodebook(subvectors: number[][]): Promise<Codebook> {
-    const k = this.numCentroids;
-    const dim = this.subvectorDim;
-
-    // Initialize centroids using k-means++ initialization
-    const centroids = this.kmeansppInit(subvectors, k);
-    const counts = new Array(k).fill(0);
-
-    // K-means iterations
-    for (let iter = 0; iter < this.maxIterations; iter++) {
-      // Assignment step
-      const assignments: number[][] = Array.from({ length: k }, () => []);
-
-      for (let i = 0; i < subvectors.length; i++) {
-        const nearestIdx = this.findNearestCentroid(subvectors[i], centroids);
-        assignments[nearestIdx].push(i);
-      }
-
-      // Update step
-      let maxShift = 0;
-      for (let c = 0; c < k; c++) {
-        if (assignments[c].length === 0) {
-          // Reinitialize empty centroid
-          const randomIdx = Math.floor(this.rng() * subvectors.length);
-          centroids[c] = [...subvectors[randomIdx]];
-          continue;
-        }
-
-        const newCentroid = new Array(dim).fill(0);
-        for (const idx of assignments[c]) {
-          for (let d = 0; d < dim; d++) {
-            newCentroid[d] += subvectors[idx][d];
-          }
-        }
-        for (let d = 0; d < dim; d++) {
-          newCentroid[d] /= assignments[c].length;
-        }
-
-        const shift = squaredEuclideanDistance(centroids[c], newCentroid);
-        maxShift = Math.max(maxShift, shift);
-        centroids[c] = newCentroid;
-        counts[c] = assignments[c].length;
-      }
-
-      // Check convergence
-      if (maxShift < this.tolerance) {
-        break;
-      }
-
-      // Yield to event loop periodically
-      if (iter % 10 === 0) {
-        await new Promise(resolve => setTimeout(resolve, 0));
-      }
-    }
-
-    return { centroids, counts };
-  }
-
-  /**
-   * K-means++ initialization for better centroid selection.
-   */
-  protected kmeansppInit(subvectors: number[][], k: number): number[][] {
-    const centroids: number[][] = [];
-
-    // First centroid: random
-    const firstIdx = Math.floor(this.rng() * subvectors.length);
-    centroids.push([...subvectors[firstIdx]]);
-
-    // Remaining centroids: proportional to squared distance
-    for (let c = 1; c < k; c++) {
-      const distances = subvectors.map(v => {
-        let minDist = Infinity;
-        for (const centroid of centroids) {
-          const dist = squaredEuclideanDistance(v, centroid);
-          minDist = Math.min(minDist, dist);
-        }
-        return minDist;
-      });
-
-      const totalDist = distances.reduce((a, b) => a + b, 0);
-      let threshold = this.rng() * totalDist;
-
-      for (let i = 0; i < subvectors.length; i++) {
-        threshold -= distances[i];
-        if (threshold <= 0) {
-          centroids.push([...subvectors[i]]);
-          break;
-        }
-      }
-
-      // Fallback if we didn't select (numerical issues)
-      if (centroids.length <= c) {
-        const fallbackIdx = Math.floor(this.rng() * subvectors.length);
-        centroids.push([...subvectors[fallbackIdx]]);
-      }
-    }
-
-    return centroids;
-  }
-
-  /**
-   * Finds the nearest centroid index for a subvector.
-   */
-  protected findNearestCentroid(subvector: number[], centroids: number[][]): number {
-    let minDist = Infinity;
-    let minIdx = 0;
-
-    for (let i = 0; i < centroids.length; i++) {
-      const dist = squaredEuclideanDistance(subvector, centroids[i]);
-      if (dist < minDist) {
-        minDist = dist;
-        minIdx = i;
-      }
-    }
-
-    return minIdx;
-  }
-
-  /**
-   * Encodes vectors to PQ codes.
-   *
-   * @param vectors - Input vectors
-   * @returns PQ codes (one byte per subvector, assuming K=256)
-   */
-  encode(vectors: number[][]): Uint8Array[] {
-    if (!this.isTrained) {
-      throw new Error('ProductQuantizer must be trained before encoding');
-    }
-
-    return vectors.map((vec) => {
-      const codes = new Uint8Array(this.numSubvectors);
-
-      for (let m = 0; m < this.numSubvectors; m++) {
-        const start = m * this.subvectorDim;
-        const subvector = vec.slice(start, start + this.subvectorDim);
-        codes[m] = this.findNearestCentroid(subvector, this.codebooks[m].centroids);
-      }
-
-      return codes;
-    });
-  }
-
-  /**
-   * Implements IQuantizer interface - encodes vectors.
-   */
-  quantize(vectors: number[][]): Uint8Array[] {
-    return this.encode(vectors);
-  }
-
-  /**
-   * Decodes PQ codes back to approximate vectors.
-   *
-   * @param codes - PQ codes
-   * @returns Reconstructed vectors
-   */
-  decode(codes: Uint8Array[]): number[][] {
-    if (!this.isTrained) {
-      throw new Error('ProductQuantizer must be trained before decoding');
-    }
-
-    return codes.map((code) => {
-      const vec = new Array(this.dimensions);
-
-      for (let m = 0; m < this.numSubvectors; m++) {
-        const centroid = this.codebooks[m].centroids[code[m]];
-        const start = m * this.subvectorDim;
-        for (let d = 0; d < this.subvectorDim; d++) {
-          vec[start + d] = centroid[d];
-        }
-      }
-
-      return vec;
-    });
-  }
-
-  /**
-   * Implements IQuantizer interface - decodes vectors.
-   */
-  dequantize(quantized: Uint8Array[]): number[][] {
-    return this.decode(quantized);
-  }
-
-  /**
-   * Computes asymmetric distances from a query to encoded vectors.
-   *
-   * Asymmetric distance computation (ADC):
-   * - Query is NOT quantized (exact)
-   * - Database vectors are quantized (codes)
-   * - Distance is computed using lookup tables
-   *
-   * @param query - Query vector (float)
-   * @param codes - Database PQ codes
-   * @returns Array of distances
-   */
-  computeDistances(query: number[], codes: Uint8Array[]): number[] {
-    if (!this.isTrained) {
-      throw new Error('ProductQuantizer must be trained before computing distances');
-    }
-
-    // Build distance lookup tables
-    const distanceTables = this.buildDistanceTables(query);
-
-    // Compute distances using tables
-    return codes.map((code) => {
-      let distance = 0;
-      for (let m = 0; m < this.numSubvectors; m++) {
-        distance += distanceTables[m][code[m]];
-      }
-      return Math.sqrt(distance);
-    });
-  }
-
-  /**
-   * Builds distance lookup tables for asymmetric distance computation.
-   */
-  protected buildDistanceTables(query: number[]): number[][] {
-    const tables: number[][] = [];
-
-    for (let m = 0; m < this.numSubvectors; m++) {
-      const start = m * this.subvectorDim;
-      const querySubvector = query.slice(start, start + this.subvectorDim);
-
-      const table = new Array(this.numCentroids);
-      for (let c = 0; c < this.numCentroids; c++) {
-        table[c] = squaredEuclideanDistance(
-          querySubvector,
-          this.codebooks[m].centroids[c]
-        );
-      }
-      tables.push(table);
-    }
-
-    return tables;
-  }
-
-  /**
-   * Computes symmetric distances between two sets of codes.
-   *
-   * @param codesA - First set of PQ codes
-   * @param codesB - Second set of PQ codes
-   * @returns Distance matrix
-   */
-  computeSymmetricDistances(codesA: Uint8Array[], codesB: Uint8Array[]): number[][] {
-    if (!this.isTrained) {
-      throw new Error('ProductQuantizer must be trained before computing distances');
-    }
-
-    // Precompute inter-centroid distances for each subvector
-    const centroidDists: number[][][] = [];
-    for (let m = 0; m < this.numSubvectors; m++) {
-      const dists = zerosMatrix(this.numCentroids, this.numCentroids);
-      for (let i = 0; i < this.numCentroids; i++) {
-        for (let j = i; j < this.numCentroids; j++) {
-          const d = squaredEuclideanDistance(
-            this.codebooks[m].centroids[i],
-            this.codebooks[m].centroids[j]
-          );
-          dists[i][j] = d;
-          dists[j][i] = d;
-        }
-      }
-      centroidDists.push(dists);
-    }
-
-    // Compute distance matrix
-    const result = zerosMatrix(codesA.length, codesB.length);
-    for (let i = 0; i < codesA.length; i++) {
-      for (let j = 0; j < codesB.length; j++) {
-        let dist = 0;
-        for (let m = 0; m < this.numSubvectors; m++) {
-          dist += centroidDists[m][codesA[i][m]][codesB[j][m]];
-        }
-        result[i][j] = Math.sqrt(dist);
-      }
-    }
-
-    return result;
-  }
-
-  getCompressionRatio(): number {
-    // float32 * dimensions -> numSubvectors bytes (for K=256)
-    // = (4 * dimensions) / numSubvectors
-    return (4 * this.dimensions) / this.numSubvectors;
-  }
-
-  getMemoryReduction(): string {
-    const ratio = this.getCompressionRatio();
-    return `${ratio.toFixed(1)}x`;
-  }
-
-  /**
-   * Gets the trained codebooks.
-   */
-  getCodebooks(): Codebook[] {
-    return this.codebooks.map(cb => ({
-      centroids: cb.centroids.map(c => [...c]),
-      counts: [...cb.counts],
-    }));
-  }
-
-  /**
-   * Sets codebooks directly (for loading pretrained).
-   */
-  setCodebooks(codebooks: Codebook[]): void {
-    if (codebooks.length !== this.numSubvectors) {
-      throw new Error(`Expected ${this.numSubvectors} codebooks, got ${codebooks.length}`);
-    }
-    this.codebooks = codebooks;
-    this.isTrained = true;
-  }
-
-  /**
-   * Checks if the quantizer is trained.
-   */
-  get trained(): boolean {
-    return this.isTrained;
-  }
-}
-
-// ============================================================================
-// Optimized Product Quantization (OPQ)
-// ============================================================================
-
-/**
- * OptimizedProductQuantizer extends PQ with learned rotation.
- *
- * Learns an orthogonal rotation matrix to minimize quantization error.
- * The rotation decorrelates dimensions and distributes variance evenly.
- *
- * @example
- * ```typescript
- * const opq = new OptimizedProductQuantizer({
- *   dimensions: 128,
- *   numSubvectors: 8,
- *   numCentroids: 256,
- *   opqIterations: 10
- * });
- * await opq.trainWithRotation(trainingVectors);
- * const codes = opq.encode(vectors);
- * ```
- */
-export class OptimizedProductQuantizer extends ProductQuantizer {
-  override readonly type: QuantizationType = 'opq';
-
-  private rotationMatrix: number[][] | null = null;
-  private readonly opqIterations: number;
-  private readonly learningRate: number;
-
-  constructor(options: OptimizedProductQuantizationOptions) {
-    super(options);
-    this.opqIterations = options.opqIterations ?? 10;
-    this.learningRate = options.learningRate ?? 0.01;
-  }
-
-  /**
-   * Trains the quantizer with rotation matrix optimization.
-   *
-   * @param vectors - Training vectors
-   */
-  async trainWithRotation(vectors: number[][]): Promise<void> {
-    // Initialize rotation matrix as identity
-    this.rotationMatrix = identityMatrix(this.dimensions);
-
-    for (let opqIter = 0; opqIter < this.opqIterations; opqIter++) {
-      // Step 1: Rotate vectors
-      const rotatedVectors = this.rotateVectors(vectors);
-
-      // Step 2: Train PQ on rotated vectors
-      await super.train(rotatedVectors);
-
-      // Step 3: Update rotation matrix using Procrustes analysis
-      this.updateRotation(vectors);
-
-      // Yield to event loop
-      await new Promise(resolve => setTimeout(resolve, 0));
-    }
-
-    // Final PQ training with final rotation
-    const finalRotated = this.rotateVectors(vectors);
-    await super.train(finalRotated);
-  }
-
-  /**
-   * Rotates vectors using the learned rotation matrix.
-   */
-  private rotateVectors(vectors: number[][]): number[][] {
-    if (!this.rotationMatrix) {
-      return vectors;
-    }
-    return vectors.map(v => matVec(this.rotationMatrix!, v));
-  }
-
-  /**
-   * Updates the rotation matrix using Procrustes analysis.
-   * Minimizes ||X - R * decode(encode(R^T * X))||^2
-   */
-  private updateRotation(vectors: number[][]): void {
-    if (!this.rotationMatrix) return;
-
-    // Get reconstructed vectors
-    const rotated = this.rotateVectors(vectors);
-    const codes = this.encode(rotated);
-    const reconstructed = this.decode(codes);
-
-    // Compute X^T * Y for Procrustes
-    const xty = zerosMatrix(this.dimensions, this.dimensions);
-    for (let i = 0; i < vectors.length; i++) {
-      for (let j = 0; j < this.dimensions; j++) {
-        for (let k = 0; k < this.dimensions; k++) {
-          xty[j][k] += vectors[i][j] * reconstructed[i][k];
-        }
-      }
-    }
-
-    // SVD approximation using power iteration
-    // For simplicity, we use gradient descent on the rotation
-    const gradientUpdate = this.computeRotationGradient(vectors, reconstructed);
-
-    // Update rotation matrix
-    for (let i = 0; i < this.dimensions; i++) {
-      for (let j = 0; j < this.dimensions; j++) {
-        this.rotationMatrix![i][j] -= this.learningRate * gradientUpdate[i][j];
-      }
-    }
-
-    // Orthogonalize using Gram-Schmidt
-    this.orthogonalize();
-  }
-
-  /**
-   * Computes gradient for rotation update.
-   */
-  private computeRotationGradient(
-    original: number[][],
-    reconstructed: number[][]
-  ): number[][] {
-    const gradient = zerosMatrix(this.dimensions, this.dimensions);
-
-    for (let i = 0; i < original.length; i++) {
-      const rotatedOrig = matVec(this.rotationMatrix!, original[i]);
-      const error = rotatedOrig.map((v, j) => v - reconstructed[i][j]);
-
-      for (let j = 0; j < this.dimensions; j++) {
-        for (let k = 0; k < this.dimensions; k++) {
-          gradient[j][k] += error[j] * original[i][k];
-        }
-      }
-    }
-
-    // Normalize
-    const scale = 1 / original.length;
-    for (let i = 0; i < this.dimensions; i++) {
-      for (let j = 0; j < this.dimensions; j++) {
-        gradient[i][j] *= scale;
-      }
-    }
-
-    return gradient;
-  }
-
-  /**
-   * Orthogonalizes the rotation matrix using modified Gram-Schmidt.
-   */
-  private orthogonalize(): void {
-    if (!this.rotationMatrix) return;
-
-    for (let i = 0; i < this.dimensions; i++) {
-      // Normalize column i
-      let n = 0;
-      for (let j = 0; j < this.dimensions; j++) {
-        n += this.rotationMatrix[j][i] * this.rotationMatrix[j][i];
-      }
-      n = Math.sqrt(n);
-      if (n > 1e-10) {
-        for (let j = 0; j < this.dimensions; j++) {
-          this.rotationMatrix[j][i] /= n;
-        }
-      }
-
-      // Remove component from remaining columns
-      for (let k = i + 1; k < this.dimensions; k++) {
-        let projection = 0;
-        for (let j = 0; j < this.dimensions; j++) {
-          projection += this.rotationMatrix[j][i] * this.rotationMatrix[j][k];
-        }
-        for (let j = 0; j < this.dimensions; j++) {
-          this.rotationMatrix[j][k] -= projection * this.rotationMatrix[j][i];
-        }
-      }
-    }
-  }
-
-  /**
-   * Encodes vectors with rotation.
-   */
-  override encode(vectors: number[][]): Uint8Array[] {
-    const rotated = this.rotateVectors(vectors);
-    return super.encode(rotated);
-  }
-
-  /**
-   * Decodes codes and applies inverse rotation.
-   */
-  override decode(codes: Uint8Array[]): number[][] {
-    const decoded = super.decode(codes);
-    if (!this.rotationMatrix) {
-      return decoded;
-    }
-    // Apply inverse rotation (transpose for orthogonal matrix)
-    const invRotation = transpose(this.rotationMatrix);
-    return decoded.map(v => matVec(invRotation, v));
-  }
-
-  /**
-   * Computes distances with rotation applied to query.
-   */
-  override computeDistances(query: number[], codes: Uint8Array[]): number[] {
-    const rotatedQuery = this.rotationMatrix
-      ? matVec(this.rotationMatrix, query)
-      : query;
-    return super.computeDistances(rotatedQuery, codes);
-  }
-
-  /**
-   * Gets the rotation matrix.
-   */
-  getRotationMatrix(): number[][] | null {
-    return this.rotationMatrix ? this.rotationMatrix.map(r => [...r]) : null;
-  }
-
-  /**
-   * Sets the rotation matrix directly.
-   */
-  setRotationMatrix(matrix: number[][]): void {
-    if (matrix.length !== this.dimensions || matrix[0].length !== this.dimensions) {
-      throw new Error(`Expected ${this.dimensions}x${this.dimensions} matrix`);
-    }
-    this.rotationMatrix = matrix.map(r => [...r]);
-  }
-}
-
-// ============================================================================
-// SQL Integration
-// ============================================================================
-
-/**
- * QuantizationSQL generates SQL for quantized vector operations.
- *
- * Provides SQL statements for:
- * - Creating quantized storage tables
- * - Inserting quantized vectors
- * - Searching with quantized distances
- */
-export class QuantizationSQL {
-  /**
-   * Generates SQL for creating a table with quantized vector storage.
-   *
-   * @param tableName - Table name
-   * @param type - Quantization type
-   * @param options - Quantization options
-   * @returns CREATE TABLE SQL statement
-   */
-  static createQuantizedTable(
-    tableName: string,
-    type: QuantizationType,
-    options?: {
-      dimensions?: number;
-      numSubvectors?: number;
-      idType?: 'SERIAL' | 'BIGSERIAL' | 'UUID';
-      additionalColumns?: string;
-    }
-  ): string {
-    const {
-      dimensions = 128,
-      numSubvectors = 8,
-      idType = 'BIGSERIAL',
-      additionalColumns = '',
-    } = options ?? {};
-
-    let vectorColumn: string;
-    let comment: string;
-
-    switch (type) {
-      case 'scalar':
-        vectorColumn = `quantized_vector BYTEA NOT NULL`;
-        comment = `Scalar quantized vectors (int8, ${dimensions} dims, 4x compression)`;
-        break;
-
-      case 'binary':
-        const binaryBytes = Math.ceil(dimensions / 8);
-        vectorColumn = `binary_vector BIT(${dimensions})`;
-        comment = `Binary quantized vectors (${dimensions} dims, ${binaryBytes} bytes, 32x compression)`;
-        break;
-
-      case 'pq':
-      case 'opq':
-        vectorColumn = `pq_codes BYTEA NOT NULL`;
-        comment = `${type === 'opq' ? 'Optimized ' : ''}Product quantized vectors (M=${numSubvectors}, K=256)`;
-        break;
-
-      default:
-        throw new Error(`Unknown quantization type: ${type}`);
-    }
-
-    const extraCols = additionalColumns ? `\n  ${additionalColumns},` : '';
-
-    return `
--- Table for ${comment}
-CREATE TABLE IF NOT EXISTS ${tableName} (
-  id ${idType} PRIMARY KEY,${extraCols}
-  original_vector vector(${dimensions}),  -- Optional: keep original for reranking
-  ${vectorColumn},
-  metadata JSONB,
-  created_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP
-);
-
--- Index for quantized search
-CREATE INDEX IF NOT EXISTS idx_${tableName}_quantized ON ${tableName} (quantized_vector);
-
-COMMENT ON TABLE ${tableName} IS '${comment}';
-    `.trim();
-  }
-
-  /**
-   * Generates SQL for inserting a quantized vector.
-   *
-   * @param tableName - Table name
-   * @param type - Quantization type
-   * @returns INSERT SQL template with placeholders
-   */
-  static insertQuantizedSQL(tableName: string, type: QuantizationType): string {
-    const column = type === 'binary' ? 'binary_vector' :
-                   (type === 'pq' || type === 'opq') ? 'pq_codes' : 'quantized_vector';
-
-    return `
-INSERT INTO ${tableName} (original_vector, ${column}, metadata)
-VALUES ($1::vector, $2, $3::jsonb)
-RETURNING id;
-    `.trim();
-  }
-
-  /**
-   * Generates SQL for batch insert of quantized vectors.
-   *
-   * @param tableName - Table name
-   * @param type - Quantization type
-   * @param count - Number of vectors
-   * @returns Batch INSERT SQL
-   */
-  static batchInsertSQL(
-    tableName: string,
-    type: QuantizationType,
-    count: number
-  ): string {
-    const column = type === 'binary' ? 'binary_vector' :
-                   (type === 'pq' || type === 'opq') ? 'pq_codes' : 'quantized_vector';
-
-    const values = Array.from({ length: count }, (_, i) => {
-      const offset = i * 3;
-      return `($${offset + 1}::vector, $${offset + 2}, $${offset + 3}::jsonb)`;
-    }).join(',\n  ');
-
-    return `
-INSERT INTO ${tableName} (original_vector, ${column}, metadata)
-VALUES
-  ${values}
-RETURNING id;
-    `.trim();
-  }
-
-  /**
-   * Generates SQL for scalar quantized search.
-   *
-   * @param tableName - Table name
-   * @param k - Number of results
-   * @param useReranking - Whether to rerank with original vectors
-   * @returns Search SQL template
-   */
-  static scalarSearchSQL(
-    tableName: string,
-    k: number,
-    useReranking: boolean = true
-  ): string {
-    if (useReranking) {
-      // Two-stage search: filter with quantized, rerank with original
-      const filterK = k * 10;
-      return `
-WITH candidates AS (
-  SELECT id, original_vector, metadata,
-         ruvector_scalar_distance(quantized_vector, $1::bytea) AS approx_dist
-  FROM ${tableName}
-  ORDER BY approx_dist ASC
-  LIMIT ${filterK}
-)
-SELECT id, metadata,
-       original_vector <-> $2::vector AS exact_dist
-FROM candidates
-ORDER BY exact_dist ASC
-LIMIT ${k};
-      `.trim();
-    }
-
-    return `
-SELECT id, metadata,
-       ruvector_scalar_distance(quantized_vector, $1::bytea) AS distance
-FROM ${tableName}
-ORDER BY distance ASC
-LIMIT ${k};
-    `.trim();
-  }
-
-  /**
-   * Generates SQL for binary quantized search with Hamming distance.
-   *
-   * @param tableName - Table name
-   * @param k - Number of results
-   * @param useReranking - Whether to rerank with original vectors
-   * @returns Search SQL template
-   */
-  static binarySearchSQL(
-    tableName: string,
-    k: number,
-    useReranking: boolean = true
-  ): string {
-    if (useReranking) {
-      const filterK = k * 10;
-      return `
-WITH candidates AS (
-  SELECT id, original_vector, metadata,
-         bit_count(binary_vector # $1::bit) AS hamming_dist
-  FROM ${tableName}
-  ORDER BY hamming_dist ASC
-  LIMIT ${filterK}
-)
-SELECT id, metadata,
-       original_vector <-> $2::vector AS exact_dist
-FROM candidates
-ORDER BY exact_dist ASC
-LIMIT ${k};
-      `.trim();
-    }
-
-    return `
-SELECT id, metadata,
-       bit_count(binary_vector # $1::bit) AS hamming_distance
-FROM ${tableName}
-ORDER BY hamming_distance ASC
-LIMIT ${k};
-    `.trim();
-  }
-
-  /**
-   * Generates SQL for PQ search using distance lookup tables.
-   *
-   * @param tableName - Table name
-   * @param k - Number of results
-   * @param numSubvectors - Number of PQ subvectors
-   * @param useReranking - Whether to rerank
-   * @returns Search SQL template
-   */
-  static pqSearchSQL(
-    tableName: string,
-    k: number,
-    numSubvectors: number = 8,
-    useReranking: boolean = true
-  ): string {
-    // Generate SQL for lookup table based distance computation
-    const distanceTerms = Array.from(
-      { length: numSubvectors },
-      (_, m) => `ruvector_pq_subvector_dist($1, ${m}, get_byte(pq_codes, ${m}))`
-    ).join(' + ');
-
-    if (useReranking) {
-      const filterK = k * 10;
-      return `
-WITH candidates AS (
-  SELECT id, original_vector, metadata,
-         sqrt(${distanceTerms}) AS approx_dist
-  FROM ${tableName}
-  ORDER BY approx_dist ASC
-  LIMIT ${filterK}
-)
-SELECT id, metadata,
-       original_vector <-> $2::vector AS exact_dist
-FROM candidates
-ORDER BY exact_dist ASC
-LIMIT ${k};
-      `.trim();
-    }
-
-    return `
-SELECT id, metadata,
-       sqrt(${distanceTerms}) AS distance
-FROM ${tableName}
-ORDER BY distance ASC
-LIMIT ${k};
-    `.trim();
-  }
-
-  /**
-   * Generates SQL for creating PQ lookup tables.
-   *
-   * @param tableName - Lookup table name
-   * @param numSubvectors - Number of subvectors (M)
-   * @param numCentroids - Number of centroids (K)
-   * @returns CREATE TABLE SQL for lookup tables
-   */
-  static createPQLookupTables(
-    tableName: string,
-    numSubvectors: number = 8,
-    numCentroids: number = 256
-  ): string {
-    return `
--- PQ codebooks storage
-CREATE TABLE IF NOT EXISTS ${tableName}_codebooks (
-  subvector_id INTEGER NOT NULL,
-  centroid_id INTEGER NOT NULL,
-  centroid vector NOT NULL,
-  PRIMARY KEY (subvector_id, centroid_id)
-);
-
--- Precomputed distance lookup (for specific queries)
-CREATE TABLE IF NOT EXISTS ${tableName}_distance_lookup (
-  query_id BIGINT NOT NULL,
-  subvector_id INTEGER NOT NULL,
-  centroid_id INTEGER NOT NULL,
-  squared_distance REAL NOT NULL,
-  PRIMARY KEY (query_id, subvector_id, centroid_id)
-);
-
-CREATE INDEX IF NOT EXISTS idx_${tableName}_lookup_query
-ON ${tableName}_distance_lookup (query_id, subvector_id);
-
-COMMENT ON TABLE ${tableName}_codebooks IS 'PQ codebooks: M=${numSubvectors}, K=${numCentroids}';
-    `.trim();
-  }
-
-  /**
-   * Generates SQL for inserting PQ codebooks.
-   *
-   * @param tableName - Base table name
-   * @param codebooks - Trained codebooks
-   * @returns INSERT SQL for codebooks
-   */
-  static insertCodebooksSQL(
-    tableName: string,
-    codebooks: Array<{ centroids: number[][] }>
-  ): string {
-    const values: string[] = [];
-
-    for (let m = 0; m < codebooks.length; m++) {
-      for (let k = 0; k < codebooks[m].centroids.length; k++) {
-        const centroidStr = `'[${codebooks[m].centroids[k].join(',')}]'`;
-        values.push(`(${m}, ${k}, ${centroidStr}::vector)`);
-      }
-    }
-
-    return `
-INSERT INTO ${tableName}_codebooks (subvector_id, centroid_id, centroid)
-VALUES
-  ${values.join(',\n  ')}
-ON CONFLICT (subvector_id, centroid_id) DO UPDATE
-SET centroid = EXCLUDED.centroid;
-    `.trim();
-  }
-
-  /**
-   * Generates SQL function for computing PQ distance.
-   *
-   * @param functionName - Function name
-   * @param numSubvectors - Number of subvectors
-   * @returns CREATE FUNCTION SQL
-   */
-  static createPQDistanceFunction(
-    functionName: string = 'pq_asymmetric_distance',
-    numSubvectors: number = 8
-  ): string {
-    return `
-CREATE OR REPLACE FUNCTION ${functionName}(
-  query_vector vector,
-  pq_codes bytea,
-  codebook_table text
-)
-RETURNS real AS $$
-DECLARE
-  total_distance real := 0;
-  m integer;
-  code integer;
-  subvector_dim integer;
-  query_subvector vector;
-  centroid vector;
-BEGIN
-  subvector_dim := vector_dims(query_vector) / ${numSubvectors};
-
-  FOR m IN 0..${numSubvectors - 1} LOOP
-    code := get_byte(pq_codes, m);
-
-    -- Extract query subvector
-    query_subvector := vector_slice(query_vector, m * subvector_dim, (m + 1) * subvector_dim);
-
-    -- Get centroid from codebook
-    EXECUTE format('SELECT centroid FROM %I WHERE subvector_id = $1 AND centroid_id = $2',
-                   codebook_table || '_codebooks')
-    INTO centroid
-    USING m, code;
-
-    -- Add squared distance
-    total_distance := total_distance + (query_subvector <-> centroid)^2;
-  END LOOP;
-
-  RETURN sqrt(total_distance);
-END;
-$$ LANGUAGE plpgsql IMMUTABLE;
-    `.trim();
-  }
-
-  /**
-   * Generates SQL for OPQ with rotation.
-   *
-   * @param tableName - Table name
-   * @param dimensions - Vector dimensions
-   * @returns SQL for rotation matrix storage
-   */
-  static createOPQRotationTable(tableName: string, dimensions: number): string {
-    return `
--- OPQ rotation matrix storage
-CREATE TABLE IF NOT EXISTS ${tableName}_rotation (
-  row_id INTEGER NOT NULL,
-  col_id INTEGER NOT NULL,
-  value REAL NOT NULL,
-  PRIMARY KEY (row_id, col_id)
-);
-
--- Function to apply rotation
-CREATE OR REPLACE FUNCTION ${tableName}_rotate_vector(v vector)
-RETURNS vector AS $$
-DECLARE
-  result float8[];
-  i integer;
-  sum float8;
-  j integer;
-BEGIN
-  result := array_fill(0::float8, ARRAY[${dimensions}]);
-
-  FOR i IN 0..${dimensions - 1} LOOP
-    sum := 0;
-    FOR j IN 0..${dimensions - 1} LOOP
-      SELECT sum + r.value * v[j+1]
-      INTO sum
-      FROM ${tableName}_rotation r
-      WHERE r.row_id = i AND r.col_id = j;
-    END LOOP;
-    result[i+1] := sum;
-  END LOOP;
-
-  RETURN result::vector;
-END;
-$$ LANGUAGE plpgsql IMMUTABLE;
-
-COMMENT ON TABLE ${tableName}_rotation IS 'OPQ rotation matrix (${dimensions}x${dimensions})';
-    `.trim();
-  }
-
-  /**
-   * Generates SQL for quantization statistics view.
-   *
-   * @param tableName - Base table name
-   * @returns CREATE VIEW SQL
-   */
-  static createStatsView(tableName: string): string {
-    return `
-CREATE OR REPLACE VIEW ${tableName}_quantization_stats AS
-SELECT
-  pg_total_relation_size('${tableName}'::regclass) AS total_size_bytes,
-  pg_relation_size('${tableName}'::regclass) AS table_size_bytes,
-  pg_indexes_size('${tableName}'::regclass) AS index_size_bytes,
-  (SELECT count(*) FROM ${tableName}) AS row_count,
-  CASE
-    WHEN (SELECT count(*) FROM ${tableName}) > 0
-    THEN pg_relation_size('${tableName}'::regclass)::float / (SELECT count(*) FROM ${tableName})
-    ELSE 0
-  END AS avg_bytes_per_row;
-    `.trim();
-  }
-}
-
-// ============================================================================
-// Factory and Utilities
-// ============================================================================
-
-/**
- * Creates a quantizer based on the specified type.
- *
- * @param type - Quantization type
- * @param options - Type-specific options
- * @returns Configured quantizer instance
- *
- * @example
- * ```typescript
- * const scalar = createQuantizer('scalar', { dimensions: 128 });
- * const binary = createQuantizer('binary', { dimensions: 128 });
- * const pq = createQuantizer('pq', { dimensions: 128, numSubvectors: 8, numCentroids: 256 });
- * ```
- */
-export function createQuantizer(
-  type: 'scalar',
-  options: ScalarQuantizationOptions
-): ScalarQuantizer;
-export function createQuantizer(
-  type: 'binary',
-  options: BinaryQuantizationOptions
-): BinaryQuantizer;
-export function createQuantizer(
-  type: 'pq',
-  options: ProductQuantizationOptions
-): ProductQuantizer;
-export function createQuantizer(
-  type: 'opq',
-  options: OptimizedProductQuantizationOptions
-): OptimizedProductQuantizer;
-export function createQuantizer(
-  type: QuantizationType,
-  options?: QuantizationOptions
-): IQuantizer;
-export function createQuantizer(
-  type: QuantizationType,
-  options?: QuantizationOptions
-): IQuantizer {
-  switch (type) {
-    case 'scalar':
-      return new ScalarQuantizer(options as ScalarQuantizationOptions);
-    case 'binary':
-      return new BinaryQuantizer(options as BinaryQuantizationOptions);
-    case 'pq':
-      return new ProductQuantizer(options as ProductQuantizationOptions);
-    case 'opq':
-      return new OptimizedProductQuantizer(options as OptimizedProductQuantizationOptions);
-    default:
-      throw new Error(`Unknown quantization type: ${type}`);
-  }
-}
-
-/**
- * Computes quantization statistics by comparing original and reconstructed vectors.
- *
- * @param original - Original vectors
- * @param reconstructed - Reconstructed vectors after quantization
- * @param quantizer - The quantizer used
- * @returns Quantization statistics
- */
-export function computeQuantizationStats(
-  original: number[][],
-  reconstructed: number[][],
-  quantizer: IQuantizer
-): QuantizationStats {
-  if (original.length !== reconstructed.length) {
-    throw new Error('Original and reconstructed arrays must have same length');
-  }
-
-  // Compute MSE
-  let mse = 0;
-  for (let i = 0; i < original.length; i++) {
-    mse += squaredEuclideanDistance(original[i], reconstructed[i]);
-  }
-  mse /= original.length;
-
-  // Estimate recall@10 by comparing rankings
-  // (simplified - real evaluation would use a test set)
-  const recallAt10 = estimateRecall(original, reconstructed, 10);
-
-  return {
-    compressionRatio: quantizer.getCompressionRatio(),
-    memoryReduction: quantizer.getMemoryReduction(),
-    recallAt10,
-    searchSpeedup: quantizer.getCompressionRatio() * 0.8, // Approximate
-    mse,
-  };
-}
-
-/**
- * Estimates recall@k by comparing original and reconstructed rankings.
- */
-function estimateRecall(
-  original: number[][],
-  reconstructed: number[][],
-  k: number
-): number {
-  if (original.length < k + 1) {
-    return 1.0; // Not enough data to evaluate
-  }
-
-  let totalRecall = 0;
-  const numQueries = Math.min(100, original.length);
-
-  for (let q = 0; q < numQueries; q++) {
-    const query = original[q];
-
-    // Get true top-k using original vectors
-    const trueDistances: Array<{ idx: number; dist: number }> = [];
-    for (let i = 0; i < original.length; i++) {
-      if (i !== q) {
-        trueDistances.push({
-          idx: i,
-          dist: euclideanDistance(query, original[i]),
-        });
-      }
-    }
-    trueDistances.sort((a, b) => a.dist - b.dist);
-    const trueTopK = new Set(trueDistances.slice(0, k).map(d => d.idx));
-
-    // Get approx top-k using reconstructed vectors
-    const approxDistances: Array<{ idx: number; dist: number }> = [];
-    for (let i = 0; i < reconstructed.length; i++) {
-      if (i !== q) {
-        approxDistances.push({
-          idx: i,
-          dist: euclideanDistance(query, reconstructed[i]),
-        });
-      }
-    }
-    approxDistances.sort((a, b) => a.dist - b.dist);
-    const approxTopK = approxDistances.slice(0, k).map(d => d.idx);
-
-    // Count intersection
-    let hits = 0;
-    for (const idx of approxTopK) {
-      if (trueTopK.has(idx)) {
-        hits++;
-      }
-    }
-
-    totalRecall += hits / k;
-  }
-
-  return totalRecall / numQueries;
-}
-
-/**
- * Serializes a quantizer to JSON for persistence.
- *
- * @param quantizer - Quantizer to serialize
- * @returns JSON-serializable object
- */
-export function serializeQuantizer(quantizer: IQuantizer): Record<string, unknown> {
-  const base = {
-    type: quantizer.type,
-    dimensions: quantizer.dimensions,
-  };
-
-  if (quantizer instanceof ScalarQuantizer) {
-    return {
-      ...base,
-      calibration: quantizer.getCalibration(),
-    };
-  }
-
-  if (quantizer instanceof OptimizedProductQuantizer) {
-    return {
-      ...base,
-      numSubvectors: quantizer.numSubvectors,
-      numCentroids: quantizer.numCentroids,
-      codebooks: quantizer.getCodebooks(),
-      rotationMatrix: quantizer.getRotationMatrix(),
-    };
-  }
-
-  if (quantizer instanceof ProductQuantizer) {
-    return {
-      ...base,
-      numSubvectors: quantizer.numSubvectors,
-      numCentroids: quantizer.numCentroids,
-      codebooks: quantizer.getCodebooks(),
-    };
-  }
-
-  if (quantizer instanceof BinaryQuantizer) {
-    return base;
-  }
-
-  return base;
-}
-
-/**
- * Deserializes a quantizer from JSON.
- *
- * @param data - Serialized quantizer data
- * @returns Restored quantizer instance
- */
-export function deserializeQuantizer(data: Record<string, unknown>): IQuantizer {
-  const type = data.type as QuantizationType;
-  const dimensions = data.dimensions as number;
-
-  switch (type) {
-    case 'scalar': {
-      const quantizer = new ScalarQuantizer({ dimensions });
-      if (data.calibration) {
-        quantizer.setCalibration(data.calibration as CalibrationData);
-      }
-      return quantizer;
-    }
-
-    case 'binary': {
-      return new BinaryQuantizer({ dimensions });
-    }
-
-    case 'pq': {
-      const quantizer = new ProductQuantizer({
-        dimensions,
-        numSubvectors: data.numSubvectors as number,
-        numCentroids: data.numCentroids as number,
-      });
-      if (data.codebooks) {
-        quantizer.setCodebooks(data.codebooks as Codebook[]);
-      }
-      return quantizer;
-    }
-
-    case 'opq': {
-      const quantizer = new OptimizedProductQuantizer({
-        dimensions,
-        numSubvectors: data.numSubvectors as number,
-        numCentroids: data.numCentroids as number,
-      });
-      if (data.codebooks) {
-        quantizer.setCodebooks(data.codebooks as Codebook[]);
-      }
-      if (data.rotationMatrix) {
-        quantizer.setRotationMatrix(data.rotationMatrix as number[][]);
-      }
-      return quantizer;
-    }
-
-    default:
-      throw new Error(`Unknown quantization type: ${type}`);
-  }
-}
-
-// ============================================================================
-// Constants
-// ============================================================================
-
-/**
- * Default configurations for different use cases.
- */
-export const QUANTIZATION_PRESETS = {
-  /** Fast search with good accuracy (scalar int8) */
-  balanced: {
-    type: 'scalar' as const,
-    options: {
-      dimensions: 128,
-      symmetric: true,
-    },
-  },
-
-  /** Maximum compression (binary) */
-  maxCompression: {
-    type: 'binary' as const,
-    options: {
-      dimensions: 128,
-      threshold: 0,
-    },
-  },
-
-  /** High accuracy with compression (PQ) */
-  highAccuracy: {
-    type: 'pq' as const,
-    options: {
-      dimensions: 128,
-      numSubvectors: 16,
-      numCentroids: 256,
-    },
-  },
-
-  /** Best accuracy (OPQ) */
-  bestAccuracy: {
-    type: 'opq' as const,
-    options: {
-      dimensions: 128,
-      numSubvectors: 16,
-      numCentroids: 256,
-      opqIterations: 10,
-    },
-  },
-} as const;
-
-/**
- * Memory reduction factors for each quantization type.
- */
-export const MEMORY_REDUCTION = {
-  scalar: 4,    // float32 -> int8
-  binary: 32,   // float32 -> 1 bit
-  pq: 16,       // Typical for M=8, K=256
-  opq: 16,      // Same as PQ
-} as const;