102 stars · MIT · release-0.5.4 (2026-09-04)
Names clusters at every level of a hierarchy using sub-cluster structure and sample documents rather than a bag of keywords.
▶Repo detailsthe review · specs · pros & cons · install
What it is
A library that takes clustered text embeddings and produces human-readable names for each cluster, at every layer of a hierarchy, using keywords, sub-cluster structure and sample documents as evidence rather than asking a model to guess from a bag of words. It comes from the Tutte Institute — the group that wrote UMAP and HDBSCAN.
Why it matters
Your entire pitch is a map somebody can read at a glance. Clustering gives you groups; the label on the group is what makes it a map instead of a blob diagram. BERTopic's default labels are keyword lists — model, prompt, token, api — which look exactly like debug output to a paying user, and hand-rolled prompting gets the hard part wrong in a predictable way: the parent's name ends up no broader than its children's, so the hierarchy stops meaning anything as you zoom. Toponymy is built for precisely that multi-scale naming problem. Ninety-nine stars is not much, but the lineage is the authors of the two algorithms BERTopic is built on, and this is the smallest change on today's page that a user would visibly notice.
- Purpose-built for naming a hierarchy at several scales, which is exactly the shape of Grasppy's drill-in
- MIT, and it consumes the sentence-transformers or model2vec embeddings your pipeline already produces
- From the group behind UMAP and HDBSCAN, so it composes with the machinery under BERTopic rather than competing with it
- Ninety-nine stars and a small research team. Treat it as a technique you could reimplement if it stalls, not a dependency to bet the product on
- It calls a model per cluster per layer, so a deep tree has a real per-import cost — LiteLLM again, before the first big run
- It names clusters; it cannot make bad clusters good. Chunking and embeddings still decide the quality of what it is naming
Clustering gives you groups; the label on the group is what makes it a map instead of a blob diagram.
source venv/bin/activate pip install toponymy