Metadata-Version: 2.4
Name: wlearn-cluster
Version: 0.1.0
Summary: Clustering native bindings backed by the wlearn C11 core
License-Expression: Apache-2.0
Project-URL: Homepage, https://wlearn.org
Project-URL: Repository, https://github.com/wlearn-org/cluster
Project-URL: Issues, https://github.com/wlearn-org/cluster/issues
Keywords: clustering,kmeans,dbscan,hierarchical,machine-learning,wlearn
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: numpy>=1.22
Requires-Dist: wlearn<0.4,>=0.3.0
Dynamic: license-file

# wlearn-cluster Python

Python estimator wrapper for the wlearn C11 clustering core.

## Install

```bash
pip install wlearn-cluster
```

## Example

```python
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.
