import type { BaseClustering, DataMatrix, KMeansParams } from './types';
import * as tf from '../backend/adapter';
export interface KMeansJSON {
    params: KMeansParams;
    centroids_: number[][];
    inertia_: number | null;
}
/**
 * K-Means clustering algorithm using Lloyd's iteration with K-means++ initialization.
 *
 * Supports multiple random initializations (`n_init`) and selects the solution
 * with the lowest inertia, matching scikit-learn's default behavior.
 */
export declare class KMeans implements BaseClustering<KMeansParams> {
    readonly params: KMeansParams;
    labels_: number[] | null;
    centroids_: tf.Tensor2D | null;
    inertia_: number | null;
    private static readonly DEFAULT_MAX_ITER;
    private static readonly DEFAULT_TOL;
    private static readonly DEFAULT_N_INIT;
    constructor(params: KMeansParams);
    private static make_random_stream;
    private static validate_params;
    dispose(): void;
    /**
     * @throws {Error} If input data is empty or n_clusters exceeds n_samples.
     *
     * @example
     * ```typescript
     * const kmeans = new KMeans({ n_clusters: 3 });
     * await kmeans.fit([[1, 2], [3, 4], [5, 6]]);
     * console.log(kmeans.labels_);
     * ```
     */
    fit(X: DataMatrix): Promise<void>;
    /**
     * @throws {Error} If input data is empty or n_clusters exceeds n_samples.
     */
    fit_predict(X: DataMatrix): Promise<number[]>;
    /**
     * Distances are computed with `pairwise_distance_matrix` under the model's
     * metric (cosine rows are L2-normalized first, matching `fit`).
     *
     * @throws {Error} If called before `fit()` has populated `centroids_`.
     */
    predict(X: DataMatrix): Promise<number[]>;
    /**
     * @throws {Error} If the model is unfitted.
     */
    get_centroids(): number[][];
    /**
     * The centroid matrix fully determines cluster assignment; together with the
     * constructor params and `inertia_` it forms a complete snapshot.
     *
     * @throws {Error} If the model is unfitted.
     */
    to_json(): KMeansJSON;
    /**
     * The restored model reproduces cluster assignment via {@link predict} without re-fitting.
     */
    static from_json(json: KMeansJSON): KMeans;
    /**
     * Spherical k-means: L2-normalizes the data onto the unit sphere and runs
     * k-means++ seeding and Lloyd assignment under the cosine metric, routing
     * every distance through `pairwise_distance_matrix(points, 'cosine')`.
     * Centroids are stored as the (un-renormalized) means of the assigned unit
     * vectors, matching the `normalize(X)` + KMeans reference convention.
     */
    private fit_cosine;
}