Restore Name prefix, Representation list, and top_n_words, and seed representative docs

Author: MaartenGr

bertopic/_bertopic.py

@@ -2869,6 +2869,13 @@ def _extract_words_per_topic(
                 c_tf_idf=c_tf_idf,
                 name="Main",
             )
+        else:
+            # Without a representation model the top c-TF-IDF words are the representation,
+            # so cut the extra candidates back to the `top_n_words` that were asked for
+            topic_representations = {
+                topic_id: Keywords(keywords.data[: self.top_n_words])
+                for topic_id, keywords in topic_representations.items()
+            }
 
         # Extract topic representations other than the Main one (called aspects)
         if calculate_aspects and isinstance(self.representation_model, dict):

bertopic/_corpus.py

@@ -258,9 +258,12 @@ def get_topic(self, topic_id: int, nr_samples: int | None = None) -> "Corpus":
         filtered_docs = [doc for doc, topic in zip(self.documents, self.topics) if topic == topic_id]
         filtered_indices = [i for i, topic in enumerate(self.topics) if topic == topic_id]
 
-        # Sample documents if nr_samples is specified
+        # Sample documents if nr_samples is specified, seeded so that representative
+        # documents — and any LLM representation built from them — repeat across runs
         if nr_samples is not None and len(filtered_docs) > nr_samples:
-            sampled_indices = np.random.choice(len(filtered_docs), size=nr_samples, replace=False)
+            sampled_indices = np.random.default_rng(42).choice(
+                len(filtered_docs), size=nr_samples, replace=False
+            )
             filtered_docs = [filtered_docs[i] for i in sampled_indices]
             filtered_indices = [filtered_indices[i] for i in sampled_indices]
 

bertopic/_topics.py

@@ -345,6 +345,15 @@ def label(self) -> str:
         else:
             return "No label could be created"
 
+    @property
+    def name(self) -> str:
+        """How the topic is named in `get_topic_info` and `topic_labels_`.
+
+        The topic's ID followed by its label, which is what makes two topics with similar
+        keywords tellable apart. A label the user set is returned as it was given.
+        """
+        return self._label if self._label is not None else f"{self.id}_{self.label}"
+
     def __getitem__(self, source: str) -> TopicRepresentation:
         """Get representation for a specific source, or default if not found."""
         return self.representations.get(source, TopicRepresentation())
@@ -355,17 +364,15 @@ def __setitem__(self, source: str, rep: TopicRepresentation):
 
     def to_info_dict(self) -> dict:
         """Serialize topic info to a flat dictionary for tabular output."""
-        info = {"Topic": self.id, "Count": self.nr_documents, "Name": self.label}
-        info["Representation"] = str(self.representations.get("Main"))
+        info = {"Topic": self.id, "Count": self.nr_documents, "Name": self.name}
+        info["Representation"] = self["Main"].words
 
         # Extract all other representations
         for name, rep in self.representations.items():
             if name != "Main":
-                info[name] = str(rep)
+                info[name] = rep.words
 
-        # Representative documents and images + truncate documents for readability
-        documents = self.representative_documents or [""]
-        info["Representative_Docs"] = [document[:80] for document in documents]
+        info["Representative_Docs"] = self.representative_documents or [""]
 
         return info
 
@@ -479,7 +486,7 @@ def frequencies(self) -> dict[int, int]:
     @property
     def labels(self) -> dict[int, str]:
         """Get labels for all topics."""
-        labels = {topic.id: topic.label if topic.label is not None else "" for topic in self.topics.values()}
+        labels = {topic.id: topic.name if topic.name is not None else "" for topic in self.topics.values()}
         return dict(sorted(labels.items()))
 
     @property

tests/test_corpus.py

@@ -271,3 +271,27 @@ def test_recombining_a_split_corpus_keeps_documents_distinct():
     combined = first + second
 
     assert combined.nr_documents == 6
+
+
+def test_candidate_sampling_is_repeatable():
+    """Representative documents feed LLM representations, so they must not drift.
+
+    The sampling was unseeded, so every fit chose different candidates and any label
+    built from them changed run to run. `random_state` on UMAP does not reach here.
+    """
+    corpus = Corpus(
+        documents=[f"document {index}" for index in range(1000)],
+        topics=np.array([0] * 1000),
+        embeddings=np.zeros((1000, 4)),
+    )
+
+    runs = [corpus.get_topic(0, nr_samples=100).documents for _ in range(3)]
+
+    assert runs[0] == runs[1] == runs[2]
+
+
+def test_sampling_only_kicks_in_above_the_limit():
+    """A topic smaller than `nr_samples` keeps every document, in order."""
+    corpus = Corpus(documents=["a", "b", "c"], topics=np.array([0, 0, 0]))
+
+    assert corpus.get_topic(0, nr_samples=100).documents == ["a", "b", "c"]

tests/test_invariants.py

@@ -160,3 +160,20 @@ def test_reduction_fixtures_have_more_topics_than_they_are_reduced_to(model, req
         f"{model} produced only {nr_topics} topics; the reduction tests reduce to 10 "
         "and need more than that to exercise a real reduction"
     )
+
+
+@pytest.mark.parametrize("model", ALL_MODEL_FIXTURES)
+def test_topic_names_carry_their_id(model, request):
+    """A generated name is `{topic}_{words}`, which tells similar topics apart.
+
+    Names the user chose are left alone, which is why zero-shot topics read as `cars`
+    rather than `0_cars` — 0.17 overwrote the generated label for those too. The prefix
+    was lost during the refactor and nothing noticed, because no test read the shape of
+    the column.
+    """
+    topic_model = request.getfixturevalue(model)
+
+    generated = [topic for topic in topic_model._topics if topic._label is None]
+    assert generated, "every topic was given a label, so nothing exercises the prefix"
+    for topic in generated:
+        assert topic.name.startswith(f"{topic.id}_")

tests/test_topics.py

@@ -579,3 +579,64 @@ def test_topics_keeps_rows_and_probabilities_consistent_through_a_merge():
     assert set(topics.predictions) <= set(topics.topic_ids())
     assert topics.probabilities.shape == (19, len(topics.topic_ids()))
     assert topics.probabilities[0].sum() == pytest.approx(1.0)
+
+
+# --------------------------------------------------------------------------------------
+# get_topic_info columns
+# --------------------------------------------------------------------------------------
+
+
+def test_representation_is_the_whole_word_list():
+    """0.17 returned every word; a `str(...)` here silently truncated to the top five."""
+    topics = build_topics({0: 4})
+    words = [(f"word{index}", 1.0 - index / 100) for index in range(10)]
+    topics.set_data(representations={"Main": {0: Keywords(data=words)}})
+
+    info = topics[0].to_info_dict()
+
+    assert info["Representation"] == [f"word{index}" for index in range(10)]
+
+
+def test_aspect_columns_are_word_lists_too():
+    """An aspect had the same bug, and `str(rep)` was never meaningful in a table."""
+    topics = build_topics({0: 4})
+    topics.set_data(representations={"Main": {0: Keywords(data=[("cat", 0.8)])}})
+    topics.set_data(representations={"Visual": {0: Images(data="collage", captions=["a cat"])}})
+
+    info = topics[0].to_info_dict()
+
+    assert info["Visual"] == ["a cat"]
+
+
+def test_name_carries_the_topic_id():
+    """What tells two topics with similar keywords apart, and what 0.17's `Name` had."""
+    topics = build_topics({0: 4})
+    topics.set_data(representations={"Main": {0: Keywords(data=[("cat", 0.9), ("dog", 0.8)])}})
+
+    assert topics[0].name == "0_cat_dog"
+    assert topics[0].to_info_dict()["Name"] == "0_cat_dog"
+
+
+def test_a_user_label_is_never_prefixed():
+    """`set_topic_labels("Politics")` should not become `0_Politics`."""
+    topics = build_topics({0: 4})
+    topics[0]._label = "Politics"
+
+    assert topics[0].name == "Politics"
+
+
+def test_label_stays_unprefixed():
+    """`TopicHierarchy` names its nodes from `label`, which 0.17 left unprefixed."""
+    topics = build_topics({0: 4})
+    topics.set_data(representations={"Main": {0: Keywords(data=[("cat", 0.9), ("dog", 0.8)])}})
+
+    assert topics[0].label == "cat_dog"
+
+
+def test_representative_documents_are_not_truncated():
+    """`get_topic_info` is a data accessor; the display layer already elides long text."""
+    topics = build_topics({0: 4})
+    long_document = "word " * 200
+    topics.set_data(representative_documents={0: [long_document]})
+
+    assert topics[0].to_info_dict()["Representative_Docs"] == [long_document]