eclipse-ms 0.1.2__tar.gz

eclipse_ms-0.1.2/.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install (core + dev, no TF on CI)
+        run: |
+          python -m pip install --upgrade pip
+          # Install runtime deps without TensorFlow to keep CI fast; the
+          # TF-dependent tests skip automatically when TF is absent.
+          pip install numpy pandas scikit-learn platformdirs tqdm pytest
+          pip install -e . --no-deps
+      - name: Lint
+        run: |
+          pip install ruff
+          ruff check src tests
+      - name: Run tests
+        run: pytest -q

eclipse_ms-0.1.2/.github/workflows/publish.yml

@@ -0,0 +1,43 @@
+name: Publish to PyPI
+
+# Publishes to PyPI when you push a version tag (e.g. v0.1.0) or create a
+# GitHub Release. Uses PyPI Trusted Publishing (OIDC) — no API token needed.
+# One-time setup: on PyPI, add a "trusted publisher" for this repo pointing at
+# this workflow (https://docs.pypi.org/trusted-publishers/).
+
+on:
+  release:
+    types: [published]
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write   # required for trusted publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1

eclipse_ms-0.1.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Frederique Vilenne, Piotr Prostko, Dirk Valkenborg
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

eclipse_ms-0.1.2/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: eclipse-ms
+Version: 0.1.2
+Summary: Conditional spectrum autoencoder and clustering for MS/MS dark-proteome discovery
+Project-URL: Homepage, https://github.com/VilenneFrederique/ECLIPSE
+Project-URL: Repository, https://github.com/VilenneFrederique/ECLIPSE
+Project-URL: Issues, https://github.com/VilenneFrederique/ECLIPSE/issues
+Author-email: Frederique Vilenne <frederique.vilenne@uhasselt.be>
+License: MIT License
+        
+        Copyright (c) 2026 Frederique Vilenne, Piotr Prostko, Dirk Valkenborg
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: autoencoder,clustering,deep learning,mass spectrometry,proteomics
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.23
+Requires-Dist: pandas>=1.5
+Requires-Dist: platformdirs>=3.0
+Requires-Dist: scikit-learn>=1.2
+Requires-Dist: tensorflow>=2.13
+Requires-Dist: tqdm>=4.64
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1; extra == 'dev'
+Provides-Extra: hdbscan
+Requires-Dist: hdbscan>=0.8.33; extra == 'hdbscan'
+Provides-Extra: mzml
+Requires-Dist: pyteomics>=4.6; extra == 'mzml'
+Provides-Extra: train
+Requires-Dist: joblib>=1.2; extra == 'train'
+Requires-Dist: pyteomics>=4.6; extra == 'train'
+Requires-Dist: regex>=2023.0; extra == 'train'
+Requires-Dist: tqdm>=4.64; extra == 'train'
+Provides-Extra: viz
+Requires-Dist: matplotlib>=3.6; extra == 'viz'
+Requires-Dist: umap-learn>=0.5; extra == 'viz'
+Description-Content-Type: text/markdown
+
+# ECLIPSE
+
+**ECLIPSE** embeds MS/MS spectra with a conditional transformer autoencoder
+and clusters the latent space to discover candidate novel ("dark proteome")
+peptides. Spectra are conditioned on precursor *m/z*, charge, and ion mobility,
+so same-peptide spectra land close together in latent space.
+
+The trained model is large (~650 MB), so it is **not** shipped on PyPI. The pip
+package contains the code; the weights are hosted externally and downloaded +
+cached on first use. Because embedding only needs the **encoder**, the default
+download is encoder-only — roughly half the full model.
+
+## Installation
+
+```bash
+pip install eclipse-ms                 # core: load model, embed, cluster
+pip install "eclipse-ms[hdbscan]"      # add HDBSCAN clustering
+pip install "eclipse-ms[viz]"          # add plotting (matplotlib, umap)
+pip install "eclipse-ms[mzml]"         # add pyteomics for mzML
+pip install "eclipse-ms[train]"        # everything needed to retrain
+```
+
+TensorFlow is a core dependency (the encoder needs it) but is imported lazily —
+`import eclipse_ms` does not load TensorFlow until you actually build or load a
+model.
+
+## Getting the weights
+
+`load_encoder()` resolves the model files in this order:
+
+1. `ECLIPSE_MODEL_DIR` — set this to a folder holding the weights (handy on
+   an HPC node where you already have them):
+```bash
+   export ECLIPSE_MODEL_DIR=/path/to/weights
+```
+2. the local cache (downloaded once, then reused);
+3. download from the GitHub release (the URLs are configured in
+   `eclipse_ms.modelhub.REGISTRY`).
+
+With no setup, option 3 runs automatically on first use. You can also bypass
+the registry with explicit local paths:
+
+```python
+from eclipse_ms import load_encoder
+encoder = load_encoder(weights="encoder.weights.h5", config="encoder_config.json")
+```
+
+## Quick start
+
+```python
+import numpy as np
+from eclipse_ms import load_encoder, embed_raw_spectra, cluster_latents, score_clusters
+
+encoder = load_encoder()  # downloads/caches the encoder on first call
+
+# raw peak lists + precursor info (lists aligned by index)
+latents = embed_raw_spectra(
+    encoder,
+    mz_list, intensity_list,
+    precursor_mz, charge, ion_mobility,
+)
+
+labels, info = cluster_latents(latents, method="hdbscan", min_cluster_size=5)
+scores = score_clusters(latents, labels)
+print(info["n_clusters"], "clusters")
+```
+
+Command line:
+
+```bash
+eclipse embed   -i parquet_dir/ -o latents.npy
+eclipse cluster -i latents.npy  -o clusters/ --method hdbscan
+```
+
+## Repository layout
+
+```
+src/eclipse_ms/     installable package (model, embed, cluster, consensus, CLI)
+training/           NOT installed: HPC data-prep, training, and export scripts
+  export_encoder.py   run once to create the slim encoder assets to publish
+  reference/          the original monolithic scripts, kept verbatim
+tests/              run without TensorFlow or weights (model tests auto-skip)
+```
+
+## Citation
+Publication Pending!
+
+Vilenne, Frédérique & Valkenborg Dirk. Clustering the Dark Proteome: A Deep Learning Approach to Novel Peptide Discovery in Immunopeptidomics (2026)
+
+## License
+
+MIT © 2026 Frédérique Vilenne, Dirk Valkenborg

eclipse_ms-0.1.2/README.md

@@ -0,0 +1,92 @@
+# ECLIPSE
+
+**ECLIPSE** embeds MS/MS spectra with a conditional transformer autoencoder
+and clusters the latent space to discover candidate novel ("dark proteome")
+peptides. Spectra are conditioned on precursor *m/z*, charge, and ion mobility,
+so same-peptide spectra land close together in latent space.
+
+The trained model is large (~650 MB), so it is **not** shipped on PyPI. The pip
+package contains the code; the weights are hosted externally and downloaded +
+cached on first use. Because embedding only needs the **encoder**, the default
+download is encoder-only — roughly half the full model.
+
+## Installation
+
+```bash
+pip install eclipse-ms                 # core: load model, embed, cluster
+pip install "eclipse-ms[hdbscan]"      # add HDBSCAN clustering
+pip install "eclipse-ms[viz]"          # add plotting (matplotlib, umap)
+pip install "eclipse-ms[mzml]"         # add pyteomics for mzML
+pip install "eclipse-ms[train]"        # everything needed to retrain
+```
+
+TensorFlow is a core dependency (the encoder needs it) but is imported lazily —
+`import eclipse_ms` does not load TensorFlow until you actually build or load a
+model.
+
+## Getting the weights
+
+`load_encoder()` resolves the model files in this order:
+
+1. `ECLIPSE_MODEL_DIR` — set this to a folder holding the weights (handy on
+   an HPC node where you already have them):
+```bash
+   export ECLIPSE_MODEL_DIR=/path/to/weights
+```
+2. the local cache (downloaded once, then reused);
+3. download from the GitHub release (the URLs are configured in
+   `eclipse_ms.modelhub.REGISTRY`).
+
+With no setup, option 3 runs automatically on first use. You can also bypass
+the registry with explicit local paths:
+
+```python
+from eclipse_ms import load_encoder
+encoder = load_encoder(weights="encoder.weights.h5", config="encoder_config.json")
+```
+
+## Quick start
+
+```python
+import numpy as np
+from eclipse_ms import load_encoder, embed_raw_spectra, cluster_latents, score_clusters
+
+encoder = load_encoder()  # downloads/caches the encoder on first call
+
+# raw peak lists + precursor info (lists aligned by index)
+latents = embed_raw_spectra(
+    encoder,
+    mz_list, intensity_list,
+    precursor_mz, charge, ion_mobility,
+)
+
+labels, info = cluster_latents(latents, method="hdbscan", min_cluster_size=5)
+scores = score_clusters(latents, labels)
+print(info["n_clusters"], "clusters")
+```
+
+Command line:
+
+```bash
+eclipse embed   -i parquet_dir/ -o latents.npy
+eclipse cluster -i latents.npy  -o clusters/ --method hdbscan
+```
+
+## Repository layout
+
+```
+src/eclipse_ms/     installable package (model, embed, cluster, consensus, CLI)
+training/           NOT installed: HPC data-prep, training, and export scripts
+  export_encoder.py   run once to create the slim encoder assets to publish
+  reference/          the original monolithic scripts, kept verbatim
+tests/              run without TensorFlow or weights (model tests auto-skip)
+```
+
+## Citation
+Publication Pending!
+
+Vilenne, Frédérique & Valkenborg Dirk. Clustering the Dark Proteome: A Deep Learning Approach to Novel Peptide Discovery in Immunopeptidomics (2026)
+
+## License
+
+MIT © 2026 Frédérique Vilenne, Dirk Valkenborg

eclipse_ms-0.1.2/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "eclipse-ms"
+version = "0.1.2"
+description = "Conditional spectrum autoencoder and clustering for MS/MS dark-proteome discovery"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { file = "LICENSE" }
+authors = [
+    { name = "Frederique Vilenne", email = "frederique.vilenne@uhasselt.be" },
+]
+keywords = ["mass spectrometry", "proteomics", "autoencoder", "clustering", "deep learning"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+]
+
+# Core install: everything needed to LOAD the model, EMBED spectra, and CLUSTER.
+# TensorFlow is heavy; it stays a hard dependency because the encoder needs it.
+dependencies = [
+    "numpy>=1.23",
+    "pandas>=1.5",
+    "scikit-learn>=1.2",
+    "tensorflow>=2.13",
+    "platformdirs>=3.0",
+    "tqdm>=4.64",
+]
+
+[project.optional-dependencies]
+hdbscan = ["hdbscan>=0.8.33"]
+viz = ["matplotlib>=3.6", "umap-learn>=0.5"]
+mzml = ["pyteomics>=4.6"]
+# Everything required to (re)train and to run the HPC data-prep scripts.
+train = ["pyteomics>=4.6", "regex>=2023.0", "joblib>=1.2", "tqdm>=4.64"]
+dev = ["pytest>=7.0", "ruff>=0.1", "build>=1.0"]
+
+[project.urls]
+Homepage = "https://github.com/VilenneFrederique/ECLIPSE"
+Repository = "https://github.com/VilenneFrederique/ECLIPSE"
+Issues = "https://github.com/VilenneFrederique/ECLIPSE/issues"
+
+[project.scripts]
+eclipse = "eclipse_ms.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/eclipse_ms"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100

eclipse_ms-0.1.2/release_assets/encoder_config.json

@@ -0,0 +1,11 @@
+{
+  "n_bins": 3200,
+  "patch_size": 16,
+  "embed_dim": 256,
+  "num_heads": 8,
+  "num_layers": 4,
+  "ff_dim": 512,
+  "latent_dim": 256,
+  "cond_dim": 8,
+  "dropout": 0.1
+}

eclipse_ms-0.1.2/src/eclipse_ms/__init__.py

@@ -0,0 +1,45 @@
+"""ECLIPSE: conditional spectrum autoencoder + clustering for MS/MS.
+
+Importing this package does NOT import TensorFlow; TF is loaded lazily the
+first time you build or load a model (e.g. ``load_encoder``) or call
+``embed_spectra``. This keeps imports fast and lets the clustering / consensus
+utilities be used in TF-free environments.
+
+The Keras model classes live in ``eclipse_ms.models`` (importing that submodule
+does import TensorFlow).
+"""
+
+from .config import COND_DIM, Config
+from .preprocessing import bin_spectrum_numpy, build_cond_vector, preprocess
+from .cluster import cluster_latents, score_clusters
+from .consensus import generate_consensus_spectrum, write_mzml
+from .modelhub import (
+    REGISTRY,
+    cache_dir,
+    get_model_file,
+    load_autoencoder,
+    load_encoder,
+)
+from .embed import embed_raw_spectra, embed_spectra
+
+__version__ = "0.1.2"
+
+__all__ = [
+    "__version__",
+    "Config",
+    "COND_DIM",
+    "bin_spectrum_numpy",
+    "build_cond_vector",
+    "preprocess",
+    "load_encoder",
+    "load_autoencoder",
+    "get_model_file",
+    "cache_dir",
+    "REGISTRY",
+    "embed_spectra",
+    "embed_raw_spectra",
+    "cluster_latents",
+    "score_clusters",
+    "generate_consensus_spectrum",
+    "write_mzml",
+]

eclipse_ms-0.1.2/src/eclipse_ms/cli.py

@@ -0,0 +1,107 @@
+"""ECLIPSE command-line interface.
+
+Subcommands:
+  embed      Bin + encode spectra from parquet to a latents .npy
+  cluster    Cluster a latents .npy into cluster labels
+  consensus  Build consensus spectra (mzML) from clusters
+
+Training and HPC data-prep live in the repo's ``training/`` scripts, not in the
+installed package.
+"""
+
+from __future__ import annotations
+
+import argparse
+import glob
+import json
+import os
+
+import numpy as np
+
+
+def _cmd_embed(args):
+    import pandas as pd
+
+    from .config import Config
+    from .embed import embed_raw_spectra
+    from .modelhub import load_encoder
+
+    encoder = load_encoder(weights=args.weights, config=args.config)
+
+    files = sorted(glob.glob(os.path.join(args.input, "*.parquet")))
+    print(f"Found {len(files)} parquet files")
+
+    mz, inten, pmz, charge, im = [], [], [], [], []
+    for fp in files:
+        df = pd.read_parquet(fp)
+        for _, row in df.iterrows():
+            mz.append(row["mz_array"])
+            inten.append(row["intensity_array"])
+            pmz.append(float(row.get("precursor_mz", 0.0)))
+            charge.append(int(row.get("precursor_charge", 2)))
+            im.append(float(row.get("ion_mobility", 0.0)))
+            if args.max_spectra and len(mz) >= args.max_spectra:
+                break
+        if args.max_spectra and len(mz) >= args.max_spectra:
+            break
+
+    latents = embed_raw_spectra(encoder, mz, inten, pmz, charge, im, Config, args.batch_size)
+    os.makedirs(os.path.dirname(args.output) or ".", exist_ok=True)
+    np.save(args.output, latents)
+    print(f"Saved {latents.shape} latents to {args.output}")
+
+
+def _cmd_cluster(args):
+    from .cluster import cluster_latents, score_clusters
+
+    latents = np.load(args.input)
+    labels, info = cluster_latents(
+        latents, method=args.method, min_cluster_size=args.min_cluster_size
+    )
+    os.makedirs(args.output, exist_ok=True)
+    np.save(os.path.join(args.output, "cluster_labels.npy"), labels)
+    with open(os.path.join(args.output, "cluster_info.json"), "w") as f:
+        json.dump(info, f, indent=2)
+    scores = score_clusters(latents, labels)
+    scores.to_csv(os.path.join(args.output, "cluster_scores.csv"), index=False)
+    print(f"Clusters: {info.get('n_clusters')}, noise: {info.get('n_noise', 0)}")
+    print(f"Wrote labels, info, and scores to {args.output}")
+
+
+def _cmd_consensus(args):
+    print(
+        "Consensus generation needs spectra grouped by cluster. See "
+        "eclipse_ms.consensus.generate_consensus_spectrum and the example in "
+        "training/consensus_reference.py for the full pipeline."
+    )
+
+
+def main(argv=None):
+    p = argparse.ArgumentParser(prog="eclipse", description="ECLIPSE")
+    sub = p.add_subparsers(dest="command", required=True)
+
+    pe = sub.add_parser("embed", help="Encode spectra to latents")
+    pe.add_argument("-i", "--input", required=True, help="Parquet directory")
+    pe.add_argument("-o", "--output", required=True, help="Output latents .npy")
+    pe.add_argument("--weights", default=None, help="Local encoder weights (.h5)")
+    pe.add_argument("--config", default=None, help="Local encoder config (.json)")
+    pe.add_argument("--batch-size", type=int, default=256)
+    pe.add_argument("--max-spectra", type=int, default=None)
+    pe.set_defaults(func=_cmd_embed)
+
+    pc = sub.add_parser("cluster", help="Cluster latents")
+    pc.add_argument("-i", "--input", required=True, help="latents .npy")
+    pc.add_argument("-o", "--output", required=True, help="Output directory")
+    pc.add_argument("--method", choices=["hdbscan", "kmeans"], default="hdbscan")
+    pc.add_argument("--min-cluster-size", type=int, default=5)
+    pc.set_defaults(func=_cmd_cluster)
+
+    pk = sub.add_parser("consensus", help="Consensus spectra from clusters")
+    pk.set_defaults(func=_cmd_consensus)
+
+    args = p.parse_args(argv)
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()

eclipse_ms-0.1.2/src/eclipse_ms/cluster.py

@@ -0,0 +1,105 @@
+"""Cluster latent vectors and score the resulting clusters."""
+
+from __future__ import annotations
+
+import time
+from typing import Tuple
+
+import numpy as np
+
+
+def cluster_latents(
+    latents: np.ndarray,
+    method: str = "hdbscan",
+    min_cluster_size: int = 5,
+    pca_dims: int = 100,
+    random_state: int = 42,
+) -> Tuple[np.ndarray, dict]:
+    """Cluster latent vectors with HDBSCAN (preferred) or MiniBatchKMeans.
+
+    Reduces dimensionality with PCA first when ``n_dims > pca_dims``. Falls back
+    to KMeans if HDBSCAN is not installed.
+
+    Returns ``(labels, info)`` where ``labels`` is ``-1`` for HDBSCAN noise.
+    """
+    from sklearn.decomposition import PCA
+
+    n_samples, n_dims = latents.shape
+    info = {"method": method, "n_samples": int(n_samples)}
+
+    if n_dims > pca_dims:
+        pca = PCA(n_components=pca_dims, random_state=random_state)
+        reduced = pca.fit_transform(latents)
+        info["pca_variance_explained"] = float(pca.explained_variance_ratio_.sum())
+    else:
+        reduced = latents
+
+    if method == "hdbscan":
+        try:
+            import hdbscan
+        except ImportError:
+            print("hdbscan not installed (`pip install eclipse-ms[hdbscan]`); using KMeans.")
+            method = "kmeans"
+
+    if method == "hdbscan":
+        import hdbscan
+
+        start = time.time()
+        clusterer = hdbscan.HDBSCAN(
+            min_cluster_size=min_cluster_size,
+            min_samples=3,
+            metric="euclidean",
+            cluster_selection_method="eom",
+            core_dist_n_jobs=-1,
+        )
+        labels = clusterer.fit_predict(reduced)
+        info["time"] = time.time() - start
+        info["n_clusters"] = len(set(labels)) - (1 if -1 in labels else 0)
+        info["n_noise"] = int((labels == -1).sum())
+
+    elif method == "kmeans":
+        from sklearn.cluster import MiniBatchKMeans
+
+        n_clusters = max(2, min(10000, n_samples // 10))
+        start = time.time()
+        kmeans = MiniBatchKMeans(
+            n_clusters=n_clusters, batch_size=1024, random_state=random_state, n_init=3
+        )
+        labels = kmeans.fit_predict(reduced)
+        info["time"] = time.time() - start
+        info["n_clusters"] = len(set(labels))
+        info["n_noise"] = 0
+    else:
+        raise ValueError(f"Unknown method: {method}")
+
+    return labels, info
+
+
+def score_clusters(latents: np.ndarray, labels: np.ndarray) -> "pd.DataFrame":  # noqa: F821
+    """Lightweight per-cluster quality scores from latent geometry.
+
+    For each non-noise cluster, reports size and intra-cluster cohesion
+    (mean distance to centroid; smaller = tighter).
+    """
+    import pandas as pd
+
+    rows = []
+    for c in sorted(set(labels)):
+        if c == -1:
+            continue
+        idx = np.where(labels == c)[0]
+        pts = latents[idx]
+        centroid = pts.mean(axis=0)
+        dists = np.linalg.norm(pts - centroid, axis=1)
+        rows.append(
+            {
+                "cluster": int(c),
+                "size": int(len(idx)),
+                "cohesion_mean_dist": float(dists.mean()),
+                "cohesion_std_dist": float(dists.std()),
+            }
+        )
+    df = pd.DataFrame(rows)
+    if not df.empty:
+        df = df.sort_values("size", ascending=False).reset_index(drop=True)
+    return df