7.8k stars · MIT · v0.17.4 (2025-12-03)
The standard way to turn a long thread into named subtopics with a parent/child hierarchy and a timeline view.
▶Repo detailsthe review · specs · pros & cons · install
What it is
A topic-modelling library that embeds documents, clusters them, and labels each cluster with the words that distinguish it. It supports hierarchical topics, topics over time, and swapping in your own embedding model.
Why it matters
This is the economic counterweight to GraphRAG from Edition 1. GraphRAG produces a beautiful nested hierarchy and charges you thousands of LLM calls per document to do it — fine as a premium tier and ruinous as the default path for a free trial. BERTopic reaches a comparable structure by clustering embeddings, so the marginal cost of mapping a conversation is CPU time rather than API spend. Its hierarchical mode gives you the parent/child structure the drill-in UI needs, and its topics-over-time view is close to a feature in itself. Pair it with model2vec (Edition 1) as the embedding backend and the whole thing fits comfortably on the Hetzner box.
- MIT, mature, and by far the best-documented library in this space
- Hierarchical topics map directly onto Grasppy's drill-in interaction
- Pluggable embeddings, so model2vec keeps it inside your RAM budget
- Default settings are memory-hungry — the UMAP and HDBSCAN steps will bite on a small VPS
- Clustering is non-deterministic, so the same chat can produce a slightly different map twice. Users notice
- The outlier bucket (topic
-1) can swallow a lot of text; you must handle it in the UI
source venv/bin/activate pip install bertopic
