wlearn-cluster Python

Python estimator wrapper for the wlearn C11 clustering core.

Install

pip install wlearn-cluster

Example

from wlearn_cluster import ClusterModel, silhouette, adjusted_rand

model = ClusterModel({"method": "kmeans", "k": 3, "seed": 42})
model.fit(X)
labels = model.labels
score = silhouette(X, labels)

model.save("cluster.wlrn")
restored = ClusterModel.load("cluster.wlrn")

API

• ClusterModel(params=None) or ClusterModel.create(params).
• fit(X) trains kmeans, minibatch, dbscan, hierarchical, or fastpam.
• predict(X) assigns new rows for centroid/medoid methods.
• score(X) returns silhouette score for fitted labels.
• save(path=None) returns WLRN bytes and writes them when given a str or Path.
• ClusterModel.load(bytes_or_path) accepts WLRN bytes, str, or Path.
• get_params() / set_params(...) support estimator cloning/search.
• default_search_space() returns the AutoML search-space IR.
• dispose() releases native memory early in long-running processes.

Fitted properties: labels, centers, medoid_indices, medoid_coords, core_mask, dendrogram, n_samples, n_features, n_clusters, n_iter, n_noise, inertia, method, is_fitted, capabilities.

Standalone metrics: silhouette, calinski_harabasz, davies_bouldin, adjusted_rand.

save() returns a WLRN bundle. Native cluster bytes are an internal artifact inside the bundle, matching JavaScript @wlearn/cluster.

Development

The canonical native source is repository root src/; py/csrc/ is generated for Python builds. make test-py uses fixtures and has no sklearn dependency. Use make test-py-ref for optional external parity tests.