topic-stability 0.1.0__py3-none-any.whl

topic_stability/__init__.py

@@ -0,0 +1,7 @@
+"""topic_stability — evaluate and visualize topic model stability."""
+
+from .run import TopicRun
+from .embeddings import DocumentEmbedder
+from .analysis import StabilityAnalysis
+
+__all__ = ["TopicRun", "DocumentEmbedder", "StabilityAnalysis"]

topic_stability/_align.py

@@ -0,0 +1,14 @@
+import numpy as np
+from scipy.optimize import linear_sum_assignment
+
+
+def _normalise_rows(m):
+    norms = np.linalg.norm(m, axis=1, keepdims=True)
+    return m / np.where(norms > 0, norms, 1.0)
+
+
+def align_to_reference(ref_centroids, cur_centroids):
+    """Return perm where perm[k] = index in cur that best matches reference topic k."""
+    sim = _normalise_rows(ref_centroids) @ _normalise_rows(cur_centroids).T
+    _, perm = linear_sum_assignment(-sim)
+    return perm

topic_stability/_metrics.py

@@ -0,0 +1,35 @@
+import numpy as np
+
+
+def _normalise(v):
+    s = v.sum()
+    return v / s if s > 0 else np.full_like(v, 1.0 / len(v))
+
+
+def js_divergence(p, q):
+    """Jensen-Shannon divergence in [0, 1] (log base 2)."""
+    m = (p + q) / 2.0
+
+    def kl(a, b):
+        mask = a > 0
+        return np.sum(a[mask] * np.log2(a[mask] / b[mask]))
+
+    return (kl(p, m) + kl(q, m)) / 2.0
+
+
+def pairwise_stability(profiles):
+    """Mean pairwise (1 - JS) for a list of normalised column vectors."""
+    scores = []
+    for i in range(len(profiles)):
+        for j in range(i + 1, len(profiles)):
+            scores.append(1.0 - js_divergence(profiles[i], profiles[j]))
+    return float(np.mean(scores)) if scores else 1.0
+
+
+def doc_profiles(run, permutation):
+    """
+    Normalised document-profile columns, reordered so column k corresponds to
+    reference topic k.  Returns ndarray of shape (n_topics, n_docs).
+    """
+    cols = run.doc_topic[:, permutation].T.copy()  # (n_topics, n_docs)
+    return np.array([_normalise(col) for col in cols])

topic_stability/analysis.py

@@ -0,0 +1,174 @@
+"""StabilityAnalysis: multi-run topic alignment and stability scoring."""
+from __future__ import annotations
+
+import numpy as np
+
+from ._align import align_to_reference
+from ._metrics import doc_profiles, pairwise_stability
+
+
+class StabilityAnalysis:
+    """Compare multiple topic model runs over the same document set.
+
+    Parameters
+    ----------
+    runs:       list of TopicRun objects, all with the same n_docs and n_topics
+    embeddings: ndarray (n_docs, embedding_dim), or a DocumentEmbedder whose
+                cache to load.  Required — used for both alignment and UMAP layout.
+    doc_ids:    explicit ID order to reconcile runs whose rows differ in order.
+                If None, run rows are assumed to already be aligned.
+
+    Workflow
+    --------
+    analysis = StabilityAnalysis(runs, embeddings)
+    analysis.align()                    # match topics across runs
+    scores = analysis.topic_stability() # per-topic stability in [0, 1]
+    analysis.visualize("out.png")       # small-multiples UMAP plot
+    """
+
+    def __init__(self, runs, embeddings, *, doc_ids=None):
+        self.runs = list(runs)
+        self.embeddings = _resolve_embeddings(embeddings)
+        self._permutations: list[np.ndarray] | None = None
+        self._umap_coords: np.ndarray | None = None
+
+        if doc_ids is not None:
+            self.runs = [_reorder_run(run, doc_ids) for run in self.runs]
+
+    # ── alignment ────────────────────────────────────────────────────────────
+
+    def _topic_centroids(self, run) -> np.ndarray:
+        """Weighted embedding centroid for each topic, L2-normalised.
+
+        centroid_k = sum_d(theta_{dk} * e_d) / |...|
+        Returns ndarray (n_topics, dim).
+        """
+        weights = run.doc_topic          # (n_docs, n_topics)
+        centroids = weights.T @ self.embeddings  # (n_topics, dim)
+        norms = np.linalg.norm(centroids, axis=1, keepdims=True)
+        return centroids / np.where(norms > 0, norms, 1.0)
+
+    def align(self, reference: int = 0) -> None:
+        """Align all runs to a reference run via embedding-centroid cosine similarity.
+
+        For each run, computes the weighted embedding centroid of each topic
+        (the same quantity used for UMAP grid layout in a single run) and finds
+        the best bijective mapping to reference topics via the Hungarian algorithm.
+
+        This is model-agnostic: no shared vocabulary is required.
+        """
+        K = self.runs[reference].n_topics
+        ref_centroids = self._topic_centroids(self.runs[reference])
+        perms = []
+        for i, run in enumerate(self.runs):
+            if i == reference:
+                perms.append(np.arange(K))
+            else:
+                cur_centroids = self._topic_centroids(run)
+                perms.append(align_to_reference(ref_centroids, cur_centroids))
+        self._permutations = perms
+
+    # ── stability metrics ─────────────────────────────────────────────────────
+
+    def topic_stability(self) -> np.ndarray:
+        """Per-topic stability as mean pairwise (1 - JS divergence) in [0, 1].
+
+        For each topic k (in reference labeling), collects the normalised
+        document-profile column from every run — treating theta[:,k] as a
+        distribution over documents — then averages pairwise (1 - JS) scores.
+
+        1.0 = perfectly stable across runs; 0.0 = maximally unstable.
+        """
+        if self._permutations is None:
+            raise RuntimeError("Call align() before topic_stability()")
+
+        K = self.runs[0].n_topics
+        all_profiles = [doc_profiles(run, perm) for run, perm in
+                        zip(self.runs, self._permutations)]  # each: (K, n_docs)
+
+        return np.array([
+            pairwise_stability([profiles[k] for profiles in all_profiles])
+            for k in range(K)
+        ])
+
+    def overall_stability(self) -> float:
+        """Mean stability across all topics."""
+        return float(self.topic_stability().mean())
+
+    # ── UMAP and visualization ────────────────────────────────────────────────
+
+    def umap_projection(self, **umap_kwargs) -> np.ndarray:
+        """Project embeddings to 2D with UMAP.  Result is cached on the object.
+
+        Requires umap-learn: pip install topic-stability[umap]
+        """
+        if self._umap_coords is not None:
+            return self._umap_coords
+        try:
+            import umap as umap_lib
+        except ImportError as e:
+            raise ImportError(
+                "umap-learn is required for projection. "
+                "Install with: pip install topic-stability[umap]"
+            ) from e
+        params = dict(n_neighbors=15, min_dist=0.1, metric="cosine",
+                      n_components=2, random_state=42)
+        params.update(umap_kwargs)
+        self._umap_coords = umap_lib.UMAP(**params).fit_transform(self.embeddings)
+        return self._umap_coords
+
+    def visualize(
+        self,
+        output_path: str,
+        *,
+        reference_run: int = 0,
+        umap_coords: np.ndarray | None = None,
+    ) -> None:
+        """Produce a small-multiples UMAP PNG for the reference run.
+
+        Topics are laid out in a grid whose positions reflect where their
+        high-weight documents cluster in the UMAP projection.  Stability
+        scores are shown in each panel title when align() has been called.
+
+        umap_coords: pass a precomputed (n_docs, 2) array to skip UMAP.
+        """
+        from .visualization import plot_topic_grid
+
+        if umap_coords is None:
+            umap_coords = self.umap_projection()
+
+        stability = self.topic_stability() if self._permutations is not None else None
+
+        plot_topic_grid(
+            umap_coords,
+            self.runs[reference_run],
+            output_path,
+            stability_scores=stability,
+        )
+
+
+# ── helpers ───────────────────────────────────────────────────────────────────
+
+
+def _resolve_embeddings(embeddings) -> np.ndarray:
+    if isinstance(embeddings, np.ndarray):
+        return embeddings
+    if hasattr(embeddings, "load"):
+        arr, _ = embeddings.load()
+        return arr
+    return np.asarray(embeddings, dtype=float)
+
+
+def _reorder_run(run, target_ids):
+    from .run import TopicRun
+
+    if run.doc_ids is None:
+        raise ValueError("Run has no doc_ids; cannot reorder by target_ids")
+    index = {id_: i for i, id_ in enumerate(run.doc_ids)}
+    order = [index[id_] for id_ in target_ids]
+    return TopicRun(
+        doc_topic=run.doc_topic[order],
+        doc_ids=list(target_ids),
+        word_topic=run.word_topic,
+        vocab=run.vocab,
+    )

topic_stability/cli/embed.py

@@ -0,0 +1,30 @@
+"""CLI: generate and cache document embeddings."""
+import argparse
+import sys
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Generate sentence-transformer embeddings for a TSV corpus."
+    )
+    parser.add_argument("tsv_path", help="Three-column TSV: id, date, text")
+    parser.add_argument("output_npy", help="Output .npy path")
+    parser.add_argument("--model", default="all-MiniLM-L6-v2",
+                        help="sentence-transformers model name")
+    args = parser.parse_args()
+
+    import numpy as np
+    from ..embeddings import DocumentEmbedder
+
+    ids, texts = [], []
+    with open(args.tsv_path, encoding="utf-8") as f:
+        for line in f:
+            parts = line.rstrip("\n").split("\t")
+            ids.append(parts[0])
+            texts.append(parts[2])
+
+    print(f"Read {len(texts)} documents from {args.tsv_path}")
+    embedder = DocumentEmbedder(model=args.model, cache_path=args.output_npy)
+    embeddings = embedder.embed(texts, ids=ids)
+    print(f"Saved {embeddings.shape} embeddings to {args.output_npy}")
+    print(f"Saved IDs to {args.output_npy}.ids")

topic_stability/cli/estimate.py

@@ -0,0 +1,49 @@
+"""CLI: estimate distributions from Mallet state files."""
+import argparse
+import os
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Estimate doc-topic and word-topic distributions from Mallet state files."
+    )
+    parser.add_argument("model_dir")
+    parser.add_argument("num_topics", type=int)
+    parser.add_argument("tsv_path")
+    args = parser.parse_args()
+
+    import csv
+    import numpy as np
+    from ..io import read_mallet_states
+
+    doc_topic, word_topic, vocab, doc_ids = read_mallet_states(
+        args.model_dir, tsv_path=args.tsv_path
+    )
+
+    if doc_ids and doc_topic.shape[0] != len(doc_ids):
+        raise ValueError(
+            f"State files have {doc_topic.shape[0]} docs "
+            f"but {args.tsv_path} has {len(doc_ids)}"
+        )
+
+    topic_cols = [f"topic_{k}" for k in range(args.num_topics)]
+
+    # doc_topic_avg.csv
+    dt_path = os.path.join(args.model_dir, "doc_topic_avg.csv")
+    with open(dt_path, "w", newline="", encoding="utf-8") as f:
+        writer = csv.writer(f)
+        writer.writerow(["id"] + topic_cols)
+        id_list = doc_ids if doc_ids else [str(i) for i in range(len(doc_topic))]
+        for id_, row in zip(id_list, doc_topic):
+            writer.writerow([id_] + [f"{v:.8f}" for v in row])
+
+    # word_topic_avg.csv
+    wt_path = os.path.join(args.model_dir, "word_topic_avg.csv")
+    with open(wt_path, "w", newline="", encoding="utf-8") as f:
+        writer = csv.writer(f)
+        writer.writerow(["word"] + topic_cols)
+        for word, row in zip(vocab, word_topic):
+            writer.writerow([word] + [f"{v:.8f}" for v in row])
+
+    print(f"Wrote {dt_path}")
+    print(f"Wrote {wt_path}")

topic_stability/cli/project.py

@@ -0,0 +1,45 @@
+"""CLI: project embeddings to 2D with UMAP."""
+import argparse
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Project document embeddings to 2D using UMAP."
+    )
+    parser.add_argument("embeddings_npy")
+    parser.add_argument("output_csv")
+    parser.add_argument("--neighbors", type=int, default=15)
+    parser.add_argument("--min-dist", type=float, default=0.1)
+    parser.add_argument("--metric", default="cosine")
+    args = parser.parse_args()
+
+    try:
+        import umap as umap_lib
+    except ImportError as e:
+        raise ImportError(
+            "umap-learn is required for projection. "
+            "Install with: pip install topic-stability[umap]"
+        ) from e
+
+    from ..embeddings import DocumentEmbedder
+
+    embedder = DocumentEmbedder(cache_path=args.embeddings_npy)
+    embeddings, ids = embedder.load()
+    print(f"Loaded {embeddings.shape[0]} embeddings ({embeddings.shape[1]} dim)")
+
+    reducer = umap_lib.UMAP(
+        n_neighbors=args.neighbors,
+        min_dist=args.min_dist,
+        metric=args.metric,
+        n_components=2,
+        random_state=42,
+    )
+    coords = reducer.fit_transform(embeddings)
+
+    id_list = ids if ids else [str(i) for i in range(len(coords))]
+    with open(args.output_csv, "w", encoding="utf-8") as f:
+        f.write("id,x,y\n")
+        for id_, (x, y) in zip(id_list, coords):
+            f.write(f"{id_},{x:.6f},{y:.6f}\n")
+
+    print(f"Saved 2D projection to {args.output_csv}")

topic_stability/cli/visualize.py

@@ -0,0 +1,41 @@
+"""CLI: produce small-multiples UMAP topic visualization."""
+import argparse
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Small-multiples UMAP visualization coloured by topic weight."
+    )
+    parser.add_argument("umap_csv", help="CSV with columns id, x, y")
+    parser.add_argument("doc_topic_csv", help="doc-topic CSV (id, topic_0, ...)")
+    parser.add_argument("word_topic_csv", help="word-topic CSV (word, topic_0, ...)")
+    parser.add_argument("output_png")
+    args = parser.parse_args()
+
+    import numpy as np
+    from ..run import TopicRun
+    from ..visualization import plot_topic_grid
+
+    umap_ids, rows = [], []
+    with open(args.umap_csv, encoding="utf-8") as f:
+        next(f)  # header
+        for line in f:
+            parts = line.strip().split(",")
+            umap_ids.append(parts[0])
+            rows.append([float(parts[1]), float(parts[2])])
+    umap_coords = np.array(rows)
+
+    run = TopicRun.from_csv(args.doc_topic_csv, word_topic_path=args.word_topic_csv)
+
+    if run.doc_ids and run.doc_ids != umap_ids:
+        index = {id_: i for i, id_ in enumerate(run.doc_ids)}
+        order = [index[id_] for id_ in umap_ids]
+        run = TopicRun(
+            doc_topic=run.doc_topic[order],
+            doc_ids=umap_ids,
+            word_topic=run.word_topic,
+            vocab=run.vocab,
+        )
+
+    plot_topic_grid(umap_coords, run, args.output_png)
+    print(f"Saved to {args.output_png}")

topic_stability/embeddings.py

@@ -0,0 +1,87 @@
+"""Sentence-embedding generation with optional disk caching."""
+from __future__ import annotations
+
+import os
+
+import numpy as np
+
+DEFAULT_MODEL = "all-MiniLM-L6-v2"
+
+
+class DocumentEmbedder:
+    """Generate or load sentence embeddings, with optional .npy cache.
+
+    Parameters
+    ----------
+    model:      sentence-transformers model name
+    cache_path: if given, load embeddings from <cache_path> on disk if they
+                exist; otherwise compute and save them there after encoding.
+                A parallel <cache_path>.ids file stores document IDs.
+
+    Usage
+    -----
+    # Generate (and cache) from raw text:
+    embedder = DocumentEmbedder(cache_path="embeddings.npy")
+    embeddings = embedder.embed(texts, ids=doc_ids)
+
+    # Load previously cached embeddings:
+    embedder = DocumentEmbedder(cache_path="embeddings.npy")
+    embeddings, ids = embedder.load()
+
+    # Pass the numpy array directly to StabilityAnalysis:
+    analysis = StabilityAnalysis(runs, embeddings=embeddings)
+    """
+
+    def __init__(self, model: str = DEFAULT_MODEL, *, cache_path: str | None = None):
+        self._model_name = model
+        self._model = None  # lazy-loaded
+        self.cache_path = cache_path
+
+    def embed(self, texts: list[str], *, ids: list[str] | None = None) -> np.ndarray:
+        """Encode texts; return (n_docs, dim) array.
+
+        If cache_path is set and the cache file already exists, the cached
+        embeddings are returned without re-encoding.  If the cache does not
+        exist, embeddings are computed and saved.
+        """
+        if self.cache_path and os.path.exists(self.cache_path):
+            embeddings, _ = self.load()
+            return embeddings
+
+        if self._model is None:
+            try:
+                from sentence_transformers import SentenceTransformer
+            except ImportError as e:
+                raise ImportError(
+                    "sentence-transformers is required for embedding. "
+                    "Install with: pip install topic-stability[embed]"
+                ) from e
+            self._model = SentenceTransformer(self._model_name)
+
+        embeddings = self._model.encode(texts, show_progress_bar=True, convert_to_numpy=True)
+
+        if self.cache_path:
+            np.save(self.cache_path, embeddings)
+            if ids is not None:
+                with open(self.cache_path + ".ids", "w", encoding="utf-8") as f:
+                    f.write("\n".join(ids) + "\n")
+
+        return embeddings
+
+    def load(self) -> tuple[np.ndarray, list[str] | None]:
+        """Load embeddings and IDs from cache.
+
+        Returns (embeddings, ids).  ids is None if no .ids file was saved.
+        """
+        if not self.cache_path:
+            raise ValueError("No cache_path set")
+        if not os.path.exists(self.cache_path):
+            raise FileNotFoundError(self.cache_path)
+
+        embeddings = np.load(self.cache_path)
+        ids_path = self.cache_path + ".ids"
+        ids = None
+        if os.path.exists(ids_path):
+            with open(ids_path, encoding="utf-8") as f:
+                ids = [line.rstrip("\n") for line in f if line.strip()]
+        return embeddings, ids

topic_stability/integrations/bertopic.py

@@ -0,0 +1,163 @@
+"""BERTopic integration for topic_stability.
+
+Structural differences from probabilistic topic models (LDA, NMF)
+------------------------------------------------------------------
+BERTopic and LDA/NMF occupy different positions in the topic-model landscape,
+and the differences matter for how stability scores should be interpreted.
+
+Representation
+  BERTopic defines topics by clustering in sentence-embedding space; a topic
+  is a centroid, not a word distribution.  LDA/NMF define topics as
+  distributions over a fixed vocabulary learned from token co-occurrence.
+
+Assignment
+  BERTopic default: hard — each document belongs to exactly one topic.
+  LDA/NMF: soft — each document has a probability distribution over all topics.
+  Soft BERTopic probabilities require calculate_probabilities=True at fit time.
+
+Outliers
+  BERTopic assigns documents that don't fit any cluster to topic -1.  These
+  documents are present in the corpus but absent from every topic.  This
+  function represents them as an all-zero row in doc_topic.
+
+Vocabulary
+  BERTopic uses c-TF-IDF to label topics post-hoc; the word-topic matrix is
+  not a generative distribution.  Word-based alignment (cosine similarity of
+  word distributions) is therefore not equivalent across model types.  Use
+  centroid-based alignment (the default in StabilityAnalysis) when mixing
+  BERTopic and LDA/NMF runs.
+
+Stability interpretation
+  For LDA/NMF, a stable topic means the same semantic region of the word
+  distribution recurs across runs.  For BERTopic, stability means the same
+  cluster of documents recurs — an inherently geometric notion.  Comparing
+  stability scores between the two model types is not straightforward.
+
+When to mix model types
+  Cross-model comparison can be informative as a sensitivity check: do runs
+  trained with completely different methods agree on which documents belong
+  together?  But the JS divergence of document profiles measures agreement on
+  *which documents* are in a topic, not agreement on *what the topic means*.
+"""
+from __future__ import annotations
+
+import numpy as np
+
+
+def from_bertopic(
+    model,
+    docs: list[str] | None = None,
+    *,
+    embeddings=None,
+    doc_ids: list[str] | None = None,
+) -> tuple:
+    """Extract a TopicRun and embeddings from a fitted BERTopic model.
+
+    Parameters
+    ----------
+    model:      fitted BERTopic instance
+    docs:       original document texts, needed only if embeddings are not
+                stored on the model and embeddings= is not passed
+    embeddings: precomputed ndarray (n_docs, dim) — use when you passed
+                embeddings directly to model.fit_transform() and BERTopic
+                did not cache them on model._embeddings
+    doc_ids:    document identifiers, parallel to docs / embeddings rows
+
+    Returns
+    -------
+    (TopicRun, embeddings)  where embeddings is an ndarray (n_docs, dim)
+
+    Notes
+    -----
+    doc_topic is taken from model.probabilities_ when available (soft
+    assignment, requires calculate_probabilities=True).  Otherwise a one-hot
+    encoding of model.topics_ is used.  Either way, documents assigned to
+    topic -1 (outliers) receive an all-zero row.
+
+    word_topic is populated from model.get_topics() as a c-TF-IDF matrix.
+    This is a relevance score, not a probability, and is not directly
+    comparable to LDA/NMF word-topic distributions.
+    """
+    from ..run import TopicRun
+
+    embeddings = _get_embeddings(model, docs, embeddings)
+    doc_topic, topic_labels = _get_doc_topic(model)
+    word_topic, vocab = _get_word_topic(model)
+
+    run = TopicRun(
+        doc_topic=doc_topic,
+        doc_ids=doc_ids,
+        word_topic=word_topic,
+        vocab=vocab,
+    )
+    return run, embeddings
+
+
+# ── internals ─────────────────────────────────────────────────────────────────
+
+
+def _get_embeddings(model, docs, precomputed):
+    if precomputed is not None:
+        return np.asarray(precomputed, dtype=float)
+    if getattr(model, "_embeddings", None) is not None:
+        return np.asarray(model._embeddings, dtype=float)
+    if docs is None:
+        raise ValueError(
+            "No embeddings available: pass embeddings= (precomputed ndarray), "
+            "docs= (texts to re-encode), or fit with a model that caches _embeddings."
+        )
+    return np.asarray(model.embedding_model.embed(docs), dtype=float)
+
+
+def _get_doc_topic(model):
+    """Hard (binary) document-topic matrix from BERTopic's cluster assignments.
+
+    BERTopic assigns each document to exactly one cluster; documents that
+    don't fit any cluster are labelled -1 (outliers).  We represent this as
+    a binary matrix: 1.0 where a document is assigned, 0.0 everywhere else.
+
+    We deliberately ignore model.probabilities_ here.  Those are HDBSCAN soft
+    membership scores that measure how strongly a point sits inside its
+    cluster — a geometric property of the embedding space, not a probability
+    distribution over topics.  Using them would produce apparent gradations
+    that are not directly comparable to LDA/NMF topic weights.  Hard 0/1
+    assignment makes BERTopic's discrete nature explicit.
+    """
+    topics = np.array(model.topics_)
+    valid = sorted(set(topics) - {-1})
+    K = len(valid)
+    label_to_col = {t: i for i, t in enumerate(valid)}
+    n_docs = len(topics)
+
+    doc_topic = np.zeros((n_docs, K))
+    for d, t in enumerate(topics):
+        if t != -1:
+            doc_topic[d, label_to_col[t]] = 1.0
+
+    return doc_topic, valid
+
+
+def _get_word_topic(model):
+    """Return (vocab, word_topic) from c-TF-IDF topic representations."""
+    topics = model.get_topics()
+    if not topics:
+        return None, None
+
+    # Collect all words across topics to build a shared vocabulary.
+    all_words = []
+    for words_scores in topics.values():
+        for word, _ in words_scores:
+            if word not in all_words:
+                all_words.append(word)
+    word_index = {w: i for i, w in enumerate(all_words)}
+
+    valid_ids = sorted(k for k in topics if k != -1)
+    K = len(valid_ids)
+    W = len(all_words)
+    word_topic = np.zeros((W, K))
+    for col, tid in enumerate(valid_ids):
+        for word, score in topics[tid]:
+            if word in word_index:
+                word_topic[word_index[word], col] = max(score, 0.0)
+
+    return word_topic, all_words

topic_stability/io.py

@@ -0,0 +1,153 @@
+"""File I/O helpers for topic distributions."""
+from __future__ import annotations
+
+import csv
+import gzip
+import os
+
+import numpy as np
+
+_MALLET_ITERATIONS = [1000, 1050, 1100, 1150, 1200]
+
+
+# ── CSV (current pipeline format) ────────────────────────────────────────────
+
+
+def read_doc_topic_csv(path) -> tuple[list[str], np.ndarray]:
+    """Read a doc-topic CSV (id, topic_0, topic_1, ...).
+
+    Returns (doc_ids, doc_topic) where doc_topic has shape (n_docs, n_topics).
+    """
+    with open(path, encoding="utf-8", newline="") as f:
+        reader = csv.reader(f)
+        header = next(reader)
+        ids, rows = [], []
+        for row in reader:
+            ids.append(row[0])
+            rows.append([float(v) for v in row[1:]])
+    return ids, np.array(rows)
+
+
+def read_word_topic_csv(path) -> tuple[list[str], np.ndarray]:
+    """Read a word-topic CSV (word, topic_0, topic_1, ...).
+
+    Returns (vocab, word_topic) where word_topic has shape (n_words, n_topics).
+
+    Words may contain commas (e.g. "specifically,we"); n_topics is inferred
+    from the header so the last n_topics comma-separated fields are always
+    treated as the numeric values.
+    """
+    with open(path, encoding="utf-8") as f:
+        header = f.readline().rstrip("\n").split(",")
+        n_topics = len(header) - 1
+        vocab, rows = [], []
+        for line in f:
+            if not line.strip():
+                continue
+            parts = line.rstrip("\n").split(",")
+            word = ",".join(parts[:-n_topics])
+            rows.append([float(v) for v in parts[-n_topics:]])
+            vocab.append(word)
+    return vocab, np.array(rows)
+
+
+# ── Mallet state files ────────────────────────────────────────────────────────
+
+
+def _read_one_state(path):
+    """Parse a single Mallet .gz state file.
+
+    Returns (doc_topic_counts, topic_word_counts, vocab, alpha, beta).
+    """
+    alpha = beta = None
+    vocab: dict[str, int] = {}
+
+    with gzip.open(path, "rt", encoding="utf-8") as f:
+        for line in f:
+            if line.startswith("#alpha"):
+                alpha = [float(v) for v in line.strip().split()[2:]]
+            elif line.startswith("#beta"):
+                beta = float(line.strip().split()[2])
+            elif not line.startswith("#"):
+                word = line.split()[4]
+                if word not in vocab:
+                    vocab[word] = len(vocab)
+
+    if alpha is None or beta is None:
+        raise ValueError(f"Could not parse alpha/beta from {path}")
+
+    num_topics = len(alpha)
+    W = len(vocab)
+    topic_word = np.zeros((num_topics, W), dtype=np.int32)
+    doc_topic_dict: dict[int, np.ndarray] = {}
+
+    with gzip.open(path, "rt", encoding="utf-8") as f:
+        for line in f:
+            if line.startswith("#"):
+                continue
+            parts = line.split()
+            doc_id = int(parts[0])
+            word = parts[4]
+            topic = int(parts[5])
+            topic_word[topic, vocab[word]] += 1
+            if doc_id not in doc_topic_dict:
+                doc_topic_dict[doc_id] = np.zeros(num_topics, dtype=np.int32)
+            doc_topic_dict[doc_id][topic] += 1
+
+    num_docs = max(doc_topic_dict) + 1
+    doc_topic = np.zeros((num_docs, num_topics), dtype=np.int32)
+    for did, counts in doc_topic_dict.items():
+        doc_topic[did] = counts
+
+    return doc_topic, topic_word, list(vocab.keys()), alpha, beta
+
+
+def _smooth_doc_topic(counts, alpha):
+    a = np.array(alpha)
+    return (counts + a) / (counts.sum(axis=1, keepdims=True) + a.sum())
+
+
+def _smooth_word_topic(topic_word, beta):
+    W = topic_word.shape[1]
+    phi = (topic_word + beta) / (topic_word.sum(axis=1, keepdims=True) + W * beta)
+    return phi.T  # (n_words, n_topics)
+
+
+def read_mallet_states(
+    model_dir,
+    *,
+    iterations: list[int] | None = None,
+    tsv_path: str | None = None,
+) -> tuple[np.ndarray, np.ndarray, list[str], list[str] | None]:
+    """Average doc-topic and word-topic distributions over multiple Mallet states.
+
+    Returns (doc_topic, word_topic, vocab, doc_ids).
+    doc_ids is read from tsv_path if provided, otherwise None.
+    """
+    if iterations is None:
+        iterations = _MALLET_ITERATIONS
+
+    doc_ids = None
+    if tsv_path is not None:
+        with open(tsv_path, encoding="utf-8") as f:
+            doc_ids = [line.split("\t")[0] for line in f]
+
+    all_dt, all_wt = [], []
+    shared_vocab = None
+
+    for it in iterations:
+        path = os.path.join(model_dir, f"state_{it}.gz")
+        if not os.path.exists(path):
+            continue
+        dt_counts, tw_counts, vocab, alpha, beta = _read_one_state(path)
+        if shared_vocab is None:
+            shared_vocab = vocab
+        all_dt.append(_smooth_doc_topic(dt_counts, alpha))
+        all_wt.append(_smooth_word_topic(tw_counts, beta))
+
+    if not all_dt:
+        raise FileNotFoundError(f"No state files found in {model_dir}")
+
+    doc_topic = np.mean(all_dt, axis=0)
+    word_topic = np.mean(all_wt, axis=0)
+    return doc_topic, word_topic, shared_vocab, doc_ids

topic_stability/run.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+import numpy as np
+from dataclasses import dataclass, field
+
+
+@dataclass
+class TopicRun:
+    """One run's topic distributions.
+
+    doc_topic: ndarray (n_docs, n_topics) — required
+    doc_ids:   list of document identifiers, parallel to doc_topic rows
+    word_topic: ndarray (n_words, n_topics) — optional; used for word-based inspection
+    vocab:     list of words parallel to word_topic rows
+    """
+
+    doc_topic: np.ndarray
+    doc_ids: list[str] | None = field(default=None)
+    word_topic: np.ndarray | None = field(default=None)
+    vocab: list[str] | None = field(default=None)
+
+    @property
+    def n_docs(self) -> int:
+        return self.doc_topic.shape[0]
+
+    @property
+    def n_topics(self) -> int:
+        return self.doc_topic.shape[1]
+
+    # ── constructors ─────────────────────────────────────────────────────────
+
+    @classmethod
+    def from_matrix(
+        cls,
+        doc_topic,
+        *,
+        doc_ids=None,
+        word_topic=None,
+        vocab=None,
+    ) -> "TopicRun":
+        """Construct from numpy arrays.
+
+        doc_topic: array-like (n_docs, n_topics)
+        word_topic: array-like (n_words, n_topics), optional
+        """
+        return cls(
+            doc_topic=np.asarray(doc_topic, dtype=float),
+            doc_ids=list(doc_ids) if doc_ids is not None else None,
+            word_topic=np.asarray(word_topic, dtype=float) if word_topic is not None else None,
+            vocab=list(vocab) if vocab is not None else None,
+        )
+
+    @classmethod
+    def from_sklearn(cls, model, X, *, doc_ids=None, vocab=None) -> "TopicRun":
+        """Construct from a fitted sklearn-compatible topic model.
+
+        Calls model.transform(X) to get doc-topic probabilities.
+        Reads model.components_ (n_topics, n_features) as word-topic if present.
+
+        Compatible with LatentDirichletAllocation, NMF, and any model that
+        follows the sklearn transformer interface.
+        """
+        doc_topic = model.transform(X)
+        word_topic = None
+        if hasattr(model, "components_"):
+            word_topic = model.components_.T  # → (n_features, n_topics)
+        return cls.from_matrix(doc_topic, doc_ids=doc_ids, word_topic=word_topic, vocab=vocab)
+
+    @classmethod
+    def from_csv(cls, doc_topic_path, *, word_topic_path=None) -> "TopicRun":
+        """Construct from the CSV files produced by the topic-stability pipeline.
+
+        doc_topic_path: CSV with columns id, topic_0, topic_1, ...
+        word_topic_path: CSV with columns word, topic_0, topic_1, ... (optional)
+        """
+        from .io import read_doc_topic_csv, read_word_topic_csv
+
+        doc_ids, doc_topic = read_doc_topic_csv(doc_topic_path)
+        vocab, word_topic = None, None
+        if word_topic_path is not None:
+            vocab, word_topic = read_word_topic_csv(word_topic_path)
+        return cls(doc_topic=doc_topic, doc_ids=doc_ids, word_topic=word_topic, vocab=vocab)
+
+    @classmethod
+    def from_mallet_states(
+        cls,
+        model_dir,
+        *,
+        iterations=None,
+        tsv_path=None,
+    ) -> "TopicRun":
+        """Construct by averaging over multiple Mallet Gibbs sampling states.
+
+        model_dir: directory containing state_<iter>.gz files
+        iterations: list of iteration numbers to include (default: 1000–1200)
+        tsv_path: original corpus TSV to recover document IDs (optional)
+        """
+        from .io import read_mallet_states
+
+        doc_topic, word_topic, vocab, doc_ids = read_mallet_states(
+            model_dir, iterations=iterations, tsv_path=tsv_path
+        )
+        return cls(doc_topic=doc_topic, doc_ids=doc_ids, word_topic=word_topic, vocab=vocab)

topic_stability/visualization.py

@@ -0,0 +1,128 @@
+"""Small-multiples UMAP topic visualization."""
+from __future__ import annotations
+
+import math
+
+import numpy as np
+
+
+def _topic_centroids_2d(xy, weights):
+    """Weighted-average 2D UMAP position per topic. Returns (n_topics, 2)."""
+    w_norm = weights / weights.sum(axis=0, keepdims=True)
+    return w_norm.T @ xy
+
+
+def _assign_grid(centroids, nrows, ncols):
+    """Hungarian matching of topic centroids to grid cells.
+
+    Returns dict {topic_index: (row, col)}.
+    """
+    from scipy.optimize import linear_sum_assignment
+
+    x_min, x_max = centroids[:, 0].min(), centroids[:, 0].max()
+    y_min, y_max = centroids[:, 1].min(), centroids[:, 1].max()
+
+    col_centres = x_min + (np.arange(ncols) + 0.5) / ncols * (x_max - x_min)
+    row_centres = y_max - (np.arange(nrows) + 0.5) / nrows * (y_max - y_min)
+    gx, gy = np.meshgrid(col_centres, row_centres)
+    cell_xy = np.column_stack([gx.ravel(), gy.ravel()])
+
+    diff = centroids[:, np.newaxis, :] - cell_xy[np.newaxis, :, :]
+    cost = np.sqrt((diff ** 2).sum(axis=2))
+    topic_ind, cell_ind = linear_sum_assignment(cost)
+    return {k: (int(c) // ncols, int(c) % ncols) for k, c in zip(topic_ind, cell_ind)}
+
+
+def plot_topic_grid(
+    umap_coords: np.ndarray,
+    run,
+    output_path: str,
+    *,
+    stability_scores: np.ndarray | None = None,
+    top_n_words: int = 8,
+) -> None:
+    """Render a small-multiples grid coloured by per-topic document weight.
+
+    Each panel shows all documents in UMAP space, coloured by their weight
+    for that topic.  Grid positions reflect where each topic's documents
+    cluster in the projection.  When stability_scores is provided, the
+    per-topic score is appended to each panel title.
+
+    Requires matplotlib: pip install topic-stability[viz]
+    """
+    try:
+        import matplotlib.pyplot as plt
+        import matplotlib.colors as mcolors
+    except ImportError as e:
+        raise ImportError(
+            "matplotlib is required for visualization. "
+            "Install with: pip install topic-stability[viz]"
+        ) from e
+
+    xy = umap_coords
+    weights = run.doc_topic  # (n_docs, n_topics)
+    K = run.n_topics
+
+    ncols = math.ceil(math.sqrt(K))
+    nrows = math.ceil(K / ncols)
+
+    centroids_2d = _topic_centroids_2d(xy, weights)
+    grid_pos = _assign_grid(centroids_2d, nrows, ncols)
+
+    top_words = _top_words(run, top_n_words)
+
+    cmap = mcolors.LinearSegmentedColormap.from_list(
+        "topic_weight", ["#d8d8d8", "#f5a623", "#c0392b"]
+    )
+
+    fig, axes = plt.subplots(nrows, ncols,
+                             figsize=(ncols * 2.6, nrows * 3.0),
+                             facecolor="white")
+    axes = np.array(axes).reshape(nrows, ncols)
+
+    occupied = set()
+    x, y = xy[:, 0], xy[:, 1]
+
+    for k in range(K):
+        row, col = grid_pos[k]
+        occupied.add((row, col))
+        ax = axes[row, col]
+        w = weights[:, k]
+
+        vmax = np.percentile(w, 95)
+        if vmax == 0:
+            vmax = w.max() or 1.0
+        norm_w = np.clip(w / vmax, 0, 1)
+        order = np.argsort(norm_w)
+
+        ax.scatter(x[order], y[order], c=norm_w[order], cmap=cmap,
+                   vmin=0, vmax=1, s=2, linewidths=0, rasterized=True)
+
+        words = top_words[k] if top_n_words > 0 and top_words else []
+        label = " ".join(words[:4]) + ("\n" + " ".join(words[4:]) if words[4:] else "")
+        if stability_scores is not None:
+            label += f"\nstability {stability_scores[k]:.2f}"
+        ax.set_title(label, fontsize=6.5, pad=3, linespacing=1.4)
+        ax.set_xticks([])
+        ax.set_yticks([])
+        for spine in ax.spines.values():
+            spine.set_visible(False)
+
+    for r in range(nrows):
+        for c in range(ncols):
+            if (r, c) not in occupied:
+                axes[r, c].set_visible(False)
+
+    fig.tight_layout(pad=0.4)
+    fig.savefig(output_path, dpi=150, bbox_inches="tight")
+    plt.close(fig)
+
+
+def _top_words(run, n):
+    if run.word_topic is None or run.vocab is None or n == 0:
+        return [[] for _ in range(run.n_topics)]
+    wt = run.word_topic  # (n_words, n_topics)
+    return [
+        [run.vocab[i] for i in np.argsort(wt[:, k])[::-1][:n]]
+        for k in range(run.n_topics)
+    ]

topic_stability-0.1.0.dist-info/METADATA

@@ -0,0 +1,215 @@
+Metadata-Version: 2.4
+Name: topic-stability
+Version: 0.1.0
+Summary: Measure and visualize topic model stability across multiple runs
+Project-URL: Homepage, https://github.com/mimno/TopicStability
+Project-URL: Repository, https://github.com/mimno/TopicStability
+Project-URL: Issues, https://github.com/mimno/TopicStability/issues
+Author-email: David Mimno <mimno@cornell.edu>
+License: MIT License
+        
+        Copyright (c) 2026 mimno
+        
+        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: BERTopic,LDA,NLP,stability,text analysis,topic modeling
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Text Processing :: Linguistic
+Requires-Python: >=3.10
+Requires-Dist: numpy
+Requires-Dist: scipy
+Provides-Extra: all
+Requires-Dist: matplotlib; extra == 'all'
+Requires-Dist: sentence-transformers; extra == 'all'
+Requires-Dist: umap-learn; extra == 'all'
+Provides-Extra: embed
+Requires-Dist: sentence-transformers; extra == 'embed'
+Provides-Extra: umap
+Requires-Dist: umap-learn; extra == 'umap'
+Provides-Extra: viz
+Requires-Dist: matplotlib; extra == 'viz'
+Description-Content-Type: text/markdown
+
+# topic-stability
+
+Measure and visualize the stability of topic models across multiple runs.
+
+Topic models are stochastic: two runs with the same settings produce differently-labelled topics in a different order. **topic-stability** aligns topics across runs using sentence-embedding centroids and scores each topic by how consistently the same documents are assigned to it (Jensen-Shannon divergence). The result is a per-topic stability score in [0, 1] and a small-multiples UMAP visualization with stability annotated on each panel.
+
+Works with any topic model that produces a document-topic matrix — LDA, NMF, BERTopic, and more.
+
+## Install
+
+```bash
+pip install topic-stability                      # core (numpy + scipy only)
+pip install "topic-stability[embed]"             # + sentence-transformers
+pip install "topic-stability[umap,viz]"          # + UMAP + matplotlib
+pip install "topic-stability[all]"               # everything
+```
+
+## Quick start
+
+### sklearn (LDA, NMF, …)
+
+```python
+from sklearn.decomposition import LatentDirichletAllocation
+from topic_stability import TopicRun, StabilityAnalysis, DocumentEmbedder
+
+# Embed documents once and cache to disk
+embedder = DocumentEmbedder(cache_path="embeddings.npy")
+embeddings = embedder.embed(texts, ids=doc_ids)
+
+# Train several runs
+runs = [TopicRun.from_sklearn(
+            LatentDirichletAllocation(n_components=20).fit(X), X
+        ) for _ in range(5)]
+
+analysis = StabilityAnalysis(runs, embeddings=embeddings)
+analysis.align()
+
+print(analysis.topic_stability())   # array of shape (n_topics,)
+print(analysis.overall_stability()) # scalar
+
+analysis.visualize("topics.png")    # requires topic-stability[umap,viz]
+```
+
+### Pass precomputed embeddings (e.g. from BERTopic)
+
+```python
+from topic_stability.integrations.bertopic import from_bertopic
+
+run, embeddings = from_bertopic(model, embeddings=precomputed_embeddings)
+```
+
+See [BERTopic notes](#bertopic) below for important differences.
+
+### From files (Mallet / CSV pipeline)
+
+```python
+runs = [
+    TopicRun.from_csv(
+        f"model_42_run{i}/doc_topic_avg.csv",
+        word_topic_path=f"model_42_run{i}/word_topic_avg.csv",
+    )
+    for i in range(1, 6)
+]
+
+embedder = DocumentEmbedder(cache_path="embeddings.npy")
+embeddings, _ = embedder.load()
+
+analysis = StabilityAnalysis(runs, embeddings=embeddings)
+analysis.align()
+analysis.visualize("topics.png", umap_coords=precomputed_umap)
+```
+
+## API
+
+### `TopicRun`
+
+One run's topic distributions.
+
+| Constructor | Use when |
+|---|---|
+| `TopicRun.from_matrix(doc_topic, *, doc_ids, word_topic, vocab)` | You have numpy arrays |
+| `TopicRun.from_sklearn(model, X, *, doc_ids, vocab)` | sklearn `transform()` interface |
+| `TopicRun.from_csv(doc_topic_path, *, word_topic_path)` | CSV files from the CLI pipeline |
+| `TopicRun.from_mallet_states(model_dir, *, iterations, tsv_path)` | Mallet `.gz` state files |
+
+### `DocumentEmbedder`
+
+```python
+embedder = DocumentEmbedder(model="all-MiniLM-L6-v2", cache_path="embeddings.npy")
+embeddings = embedder.embed(texts, ids=doc_ids)  # computes and caches
+embeddings, ids = embedder.load()                # load from cache
+```
+
+Pass the returned array directly to `StabilityAnalysis(runs, embeddings=embeddings)`.
+
+### `StabilityAnalysis`
+
+```python
+analysis = StabilityAnalysis(runs, embeddings, *, doc_ids=None)
+analysis.align(reference=0)         # must call before scoring
+analysis.topic_stability()          # ndarray (n_topics,) in [0, 1]
+analysis.overall_stability()        # float
+analysis.umap_projection(**kwargs)  # ndarray (n_docs, 2)
+analysis.visualize(path, *, reference_run=0, umap_coords=None)
+```
+
+**Alignment** uses cosine similarity of per-topic embedding centroids
+(`centroid_k = Σ_d θ_dk · e_d`, normalised) matched with the Hungarian
+algorithm. No shared vocabulary is required, so runs from different model
+types can be compared.
+
+**Stability score** for topic k: mean pairwise `1 − JS(p, q)` where p and
+q are the normalised document-profile columns `θ[:,k]` (treated as a
+distribution over documents) from each pair of aligned runs.
+
+## BERTopic
+
+```python
+from topic_stability.integrations.bertopic import from_bertopic
+
+run, embeddings = from_bertopic(model, docs=None, *, embeddings=None, doc_ids=None)
+```
+
+Returns `(TopicRun, embeddings_array)`.
+
+**Key differences from LDA/NMF:**
+
+- BERTopic assigns each document to exactly one cluster (hard assignment). The
+  `doc_topic` matrix is binary: 1 for the assigned topic, 0 elsewhere.
+  Documents that HDBSCAN assigns to topic −1 (outliers) get an all-zero row.
+- `model.probabilities_` contains HDBSCAN soft-membership scores, not
+  topic-weight distributions. We do not use them — they are a geometric
+  property of the embedding space, not comparable to LDA posterior weights.
+- Word representations come from c-TF-IDF scores, not a generative word
+  distribution. Cross-model word-based comparison is not meaningful.
+- Stability scores measure whether the *same documents* cluster together
+  across runs, not whether the same word distributions recur.
+
+## CLI pipeline (Mallet / RustMallet)
+
+The package includes CLI wrappers for a full file-based workflow:
+
+```bash
+# 1. Embed documents
+topic-stability-embed corpus.tsv embeddings.npy
+
+# 2. Project to 2D
+topic-stability-project embeddings.npy umap_2d.csv
+
+# 3. Estimate distributions from Mallet states
+topic-stability-estimate model_42_run1/ 42 corpus.tsv
+
+# 4. Visualize a single run
+topic-stability-visualize umap_2d.csv model_42_run1/doc_topic_avg.csv \
+    model_42_run1/word_topic_avg.csv topics.png
+```
+
+## License
+
+MIT

topic_stability-0.1.0.dist-info/RECORD

@@ -0,0 +1,20 @@
+topic_stability/__init__.py,sha256=FQVi5oNJXBqvcTs4ozMDldzu9sUQPJMrXd7cTZEmLH4,245
+topic_stability/_align.py,sha256=rRwUHeYe4G6vTGIeznak45Wf_t8l29ZrIpQOpd8ZqbA,472
+topic_stability/_metrics.py,sha256=QWoiz2K2ByKCBM3-D1QIzKNRREfJvpGxptoy2XBGNtA,1027
+topic_stability/analysis.py,sha256=tgTgJuCOa5TRJBJRsg0-ycEhmhgLJlr8VAm483sPrco,7052
+topic_stability/embeddings.py,sha256=3ew_e5fV3FLe2BpCPr3Lr2g5SXs2MCAKXA0dufUvYVU,3171
+topic_stability/io.py,sha256=FrM3BAR4i0p-JApUDKRdEQ8H_8opSLq_2KL0A1uHyAw,5221
+topic_stability/run.py,sha256=5iknMtG6SOObIFOEYQi52JgCMHUgl_ixKHi5wJwZ8_E,3824
+topic_stability/visualization.py,sha256=7a-qKxORrkyoMH2mZxPNNMmXF9sWNu1ChtVcxgWz-QE,4205
+topic_stability/cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+topic_stability/cli/embed.py,sha256=C_PeQXxdIFg_ogmEWPyzOIAQXvF4SMYcXtIA03dLYXU,1115
+topic_stability/cli/estimate.py,sha256=xZKHuZ_00Nk0ayuwmR0jgy19ZJl8uM8gWRCx4gVI12Y,1687
+topic_stability/cli/project.py,sha256=p2m8wSZB_L4ILSTq9VESHZL2xeU4ARqZMTTqTMNuqD0,1478
+topic_stability/cli/visualize.py,sha256=Cd_Q9Rblt1TyuXrZR-RezmglbGPesAM1u7SKeVs5j7Y,1453
+topic_stability/integrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+topic_stability/integrations/bertopic.py,sha256=DL_1oDKdS67Y2nFm_LBNAIu1vFwChxVnXr1HoSORLsQ,6457
+topic_stability-0.1.0.dist-info/METADATA,sha256=jH10rLVS_ORnZLeQUgwLuBAqv7ZQDoSo2oeYf09CFAU,8228
+topic_stability-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+topic_stability-0.1.0.dist-info/entry_points.txt,sha256=wKp4yuV1LSF0Bq84yuOHKfZRrVPcQ5oEKVenwM-2EM4,256
+topic_stability-0.1.0.dist-info/licenses/LICENSE,sha256=XKuNUDXkpLe-Px7bBHxR1AtgIwSYNw3t_hE6m0Dkgq4,1062
+topic_stability-0.1.0.dist-info/RECORD,,

topic_stability-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

topic_stability-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,5 @@
+[console_scripts]
+topic-stability-embed = topic_stability.cli.embed:main
+topic-stability-estimate = topic_stability.cli.estimate:main
+topic-stability-project = topic_stability.cli.project:main
+topic-stability-visualize = topic_stability.cli.visualize:main

topic_stability-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mimno
+
+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.