K-Means Clustering

Task

Implement class KMeans(initial_centroids: np.ndarray, max_iterations: int, tolerance: float). Implement deterministic K-Means clustering from caller-provided centroids, including assignment, centroid updates, convergence state, inertia tracking, fitting, and prediction.

Requirements

• Copy initial_centroids so fitting does not mutate the caller's array.
• assign(x) returns the nearest centroid index by squared Euclidean distance; distance ties choose the lowest cluster index.
• update_centroids(x, assignments) replaces each non-empty cluster with its mean and keeps the previous centroid for an empty cluster.
• fit(x) alternates assignment and update for at most max_iterations.
• After each update, append the resulting sum of squared distances to inertia_history.
• Converge when the largest centroid L2 shift is less than or equal to tolerance.
• Store n_iterations, converged, labels, and final inertia after fitting.
• predict(x) assigns rows to the final centroids without mutating learned state.

Example

model = KMeans(
    np.array([[0.0], [10.0]]),
    max_iterations=10,
    tolerance=0.0,
)
model.fit(np.array([[0.0], [2.0], [8.0], [10.0]]))
model.predict(np.array([[0.0], [6.0], [10.0]]))
# array([0, 1, 1])