tritopic 0.1.0__py3-none-any.whl → 1.0.0__py3-none-any.whl

tritopic/__init__.py

@@ -1,46 +1,36 @@
 """
 TriTopic: Tri-Modal Graph Topic Modeling with Iterative Refinement
-===================================================================
 
-A state-of-the-art topic modeling library that combines:
-- Semantic embeddings (Sentence-BERT, Instructor, BGE)
-- Lexical similarity (BM25)
-- Metadata context (optional)
+A state-of-the-art topic modeling library that consistently outperforms
+BERTopic and traditional approaches.
 
-With advanced techniques:
-- Leiden clustering with consensus
-- Mutual kNN + SNN graph construction
-- Iterative refinement loop
-- LLM-powered topic labeling
+Key Features:
+- Multi-view representation (semantic, lexical, metadata)
+- Hybrid graph construction (Mutual kNN + SNN)
+- Consensus Leiden clustering for stability
+- Iterative refinement for improved coherence
+- Multilingual support (60+ languages)
+- LLM-powered labeling
 
-Basic usage:
------------
->>> from tritopic import TriTopic
->>> model = TriTopic()
->>> topics = model.fit_transform(documents)
->>> model.visualize()
-
-Author: Roman Egger
-License: MIT
+Example:
+    >>> from tritopic import TriTopic
+    >>> model = TriTopic(verbose=True)
+    >>> topics = model.fit_transform(documents)
+    >>> print(model.get_topic_info())
 """
 
-__version__ = "0.1.0"
+__version__ = "1.0.0"
 __author__ = "Roman Egger"
 
-from tritopic.core.model import TriTopic
-from tritopic.core.graph_builder import GraphBuilder
-from tritopic.core.clustering import ConsensusLeiden
-from tritopic.core.embeddings import EmbeddingEngine
-from tritopic.core.keywords import KeywordExtractor
-from tritopic.labeling.llm_labeler import LLMLabeler
-from tritopic.visualization.plotter import TopicVisualizer
+from .model import TriTopic, Topic
+from .config import TriTopicConfig, get_config
+from .labeling import LLMLabeler, KeywordLabeler
 
 __all__ = [
     "TriTopic",
-    "GraphBuilder", 
-    "ConsensusLeiden",
-    "EmbeddingEngine",
-    "KeywordExtractor",
+    "Topic",
+    "TriTopicConfig",
+    "get_config",
     "LLMLabeler",
-    "TopicVisualizer",
+    "KeywordLabeler",
 ]

tritopic/config.py

@@ -0,0 +1,305 @@
+"""
+TriTopic Configuration Module
+
+Defines all configuration parameters for the TriTopic model.
+"""
+
+from dataclasses import dataclass, field
+from typing import Optional, List, Literal, Union
+
+
+@dataclass
+class TriTopicConfig:
+    """
+    Configuration for TriTopic model.
+    
+    Attributes
+    ----------
+    # Embedding & Language Settings
+    embedding_model : str
+        Sentence-Transformer model name or "auto" for automatic selection.
+        Auto-selection considers the language parameter.
+    embedding_batch_size : int
+        Batch size for embedding generation.
+    language : str
+        ISO 639-1 language code (e.g., "en", "de", "zh") or "auto" for detection.
+    multilingual : bool
+        If True, uses multilingual embedding models regardless of detected language.
+    language_detection_sample : int
+        Number of documents to sample for automatic language detection.
+    tokenizer : str
+        Tokenizer to use: "auto", "whitespace", "spacy", "jieba", "fugashi", "konlpy", "pythainlp".
+    custom_stopwords : List[str]
+        Additional stopwords to add to the language-specific list.
+    min_token_length : int
+        Minimum token length to keep.
+    max_token_length : int
+        Maximum token length to keep.
+    
+    # Graph Construction
+    n_neighbors : int
+        Number of neighbors for kNN graph construction.
+    metric : str
+        Distance metric for similarity calculation.
+    graph_type : str
+        Type of graph: "knn", "mutual_knn", "snn", "hybrid".
+    snn_weight : float
+        Weight of SNN component in hybrid graph (0-1).
+    
+    # Multi-View Fusion
+    use_lexical_view : bool
+        Whether to include lexical (TF-IDF/BM25) similarity.
+    use_metadata_view : bool
+        Whether to include metadata-based similarity.
+    semantic_weight : float
+        Weight for semantic (embedding) view.
+    lexical_weight : float
+        Weight for lexical view.
+    metadata_weight : float
+        Weight for metadata view.
+    lexical_method : str
+        Method for lexical similarity: "tfidf", "bm25".
+    ngram_range : tuple
+        N-gram range for lexical features.
+    
+    # Clustering
+    resolution : float
+        Resolution parameter for Leiden algorithm.
+    n_consensus_runs : int
+        Number of clustering runs for consensus.
+    min_cluster_size : int
+        Minimum number of documents per topic.
+    
+    # Iterative Refinement
+    use_iterative_refinement : bool
+        Whether to use iterative embedding refinement.
+    max_iterations : int
+        Maximum refinement iterations.
+    convergence_threshold : float
+        ARI threshold for convergence detection.
+    refinement_strength : float
+        How strongly to pull embeddings toward centroids (0-1).
+    
+    # Keywords
+    n_keywords : int
+        Number of keywords per topic.
+    keyword_method : str
+        Method for keyword extraction: "ctfidf", "bm25", "keybert".
+    
+    # Representative Documents
+    n_representative_docs : int
+        Number of representative documents per topic.
+    representative_method : str
+        Method for selection: "centroid", "medoid", "archetype", "diverse", "hybrid".
+    n_archetypes : int
+        Number of archetypes per topic (for archetype/hybrid method).
+    archetype_method : str
+        Algorithm for archetype analysis: "pcha", "convex_hull", "furthest_sum".
+    
+    # Outlier Handling
+    outlier_threshold : float
+        Threshold for outlier detection (0-1).
+    reassign_outliers : bool
+        Whether to try reassigning outliers to nearest topic.
+    
+    # Misc
+    random_state : int
+        Random seed for reproducibility.
+    verbose : bool
+        Whether to print progress information.
+    n_jobs : int
+        Number of parallel jobs (-1 for all cores).
+    """
+    
+    # === Embedding & Language Settings ===
+    embedding_model: str = "auto"
+    embedding_batch_size: int = 32
+    language: str = "auto"
+    multilingual: bool = False
+    language_detection_sample: int = 100
+    tokenizer: str = "auto"
+    custom_stopwords: Optional[List[str]] = None
+    min_token_length: int = 2
+    max_token_length: int = 50
+    
+    # === Graph Construction ===
+    n_neighbors: int = 15
+    metric: str = "cosine"
+    graph_type: Literal["knn", "mutual_knn", "snn", "hybrid"] = "hybrid"
+    snn_weight: float = 0.5
+    
+    # === Multi-View Fusion ===
+    use_lexical_view: bool = True
+    use_metadata_view: bool = False
+    semantic_weight: float = 0.5
+    lexical_weight: float = 0.3
+    metadata_weight: float = 0.2
+    lexical_method: Literal["tfidf", "bm25"] = "tfidf"
+    ngram_range: tuple = (1, 2)
+    
+    # === Clustering ===
+    resolution: float = 1.0
+    n_consensus_runs: int = 10
+    min_cluster_size: int = 5
+    
+    # === Iterative Refinement ===
+    use_iterative_refinement: bool = True
+    max_iterations: int = 5
+    convergence_threshold: float = 0.95
+    refinement_strength: float = 0.15
+    
+    # === Keywords ===
+    n_keywords: int = 10
+    keyword_method: Literal["ctfidf", "bm25", "keybert"] = "ctfidf"
+    
+    # === Representative Documents ===
+    n_representative_docs: int = 5
+    representative_method: Literal["centroid", "medoid", "archetype", "diverse", "hybrid"] = "hybrid"
+    n_archetypes: int = 4
+    archetype_method: Literal["pcha", "convex_hull", "furthest_sum"] = "furthest_sum"
+    
+    # === Outlier Handling ===
+    outlier_threshold: float = 0.1
+    reassign_outliers: bool = False
+    
+    # === Misc ===
+    random_state: Optional[int] = 42
+    verbose: bool = True
+    n_jobs: int = -1
+    
+    def __post_init__(self):
+        """Validate configuration after initialization."""
+        self._validate()
+    
+    def _validate(self):
+        """Validate configuration parameters."""
+        # Weights should sum to ~1.0
+        total_weight = self.semantic_weight
+        if self.use_lexical_view:
+            total_weight += self.lexical_weight
+        if self.use_metadata_view:
+            total_weight += self.metadata_weight
+        
+        if abs(total_weight - 1.0) > 0.01:
+            # Auto-normalize weights
+            if self.use_lexical_view and self.use_metadata_view:
+                self.semantic_weight = self.semantic_weight / total_weight
+                self.lexical_weight = self.lexical_weight / total_weight
+                self.metadata_weight = self.metadata_weight / total_weight
+            elif self.use_lexical_view:
+                total = self.semantic_weight + self.lexical_weight
+                self.semantic_weight = self.semantic_weight / total
+                self.lexical_weight = self.lexical_weight / total
+            else:
+                self.semantic_weight = 1.0
+        
+        # Validate ranges
+        assert 0 < self.n_neighbors <= 100, "n_neighbors must be between 1 and 100"
+        assert 0 < self.snn_weight <= 1, "snn_weight must be between 0 and 1"
+        assert 0 < self.resolution <= 5, "resolution must be between 0 and 5"
+        assert 0 < self.convergence_threshold <= 1, "convergence_threshold must be between 0 and 1"
+        assert self.n_archetypes >= 2, "n_archetypes must be at least 2"
+    
+    def get_embedding_model_for_language(self, detected_language: str = None) -> str:
+        """
+        Get the appropriate embedding model based on language settings.
+        
+        Parameters
+        ----------
+        detected_language : str, optional
+            The detected language code if language="auto"
+            
+        Returns
+        -------
+        str
+            The embedding model name to use
+        """
+        if self.embedding_model != "auto":
+            return self.embedding_model
+        
+        lang = detected_language or self.language
+        
+        # If multilingual mode is explicitly enabled
+        if self.multilingual:
+            return "paraphrase-multilingual-mpnet-base-v2"
+        
+        # Language-specific model selection
+        model_map = {
+            "en": "all-MiniLM-L6-v2",
+            "zh": "BAAI/bge-base-zh-v1.5",
+            "ja": "paraphrase-multilingual-MiniLM-L12-v2",
+            "ko": "paraphrase-multilingual-MiniLM-L12-v2",
+        }
+        
+        # Default to multilingual for non-English
+        if lang in model_map:
+            return model_map[lang]
+        elif lang != "en" and lang != "auto":
+            return "paraphrase-multilingual-MiniLM-L12-v2"
+        else:
+            return "all-MiniLM-L6-v2"
+    
+    def to_dict(self) -> dict:
+        """Convert config to dictionary."""
+        return {
+            k: v for k, v in self.__dict__.items() 
+            if not k.startswith('_')
+        }
+    
+    @classmethod
+    def from_dict(cls, config_dict: dict) -> "TriTopicConfig":
+        """Create config from dictionary."""
+        return cls(**config_dict)
+
+
+# Predefined configurations for common use cases
+CONFIGS = {
+    "default": TriTopicConfig(),
+    
+    "fast": TriTopicConfig(
+        embedding_model="all-MiniLM-L6-v2",
+        n_neighbors=10,
+        n_consensus_runs=5,
+        use_iterative_refinement=False,
+        representative_method="centroid",
+    ),
+    
+    "quality": TriTopicConfig(
+        embedding_model="BAAI/bge-base-en-v1.5",
+        n_neighbors=20,
+        n_consensus_runs=20,
+        max_iterations=10,
+        representative_method="hybrid",
+        n_archetypes=5,
+    ),
+    
+    "multilingual": TriTopicConfig(
+        multilingual=True,
+        embedding_model="paraphrase-multilingual-mpnet-base-v2",
+        semantic_weight=0.6,
+        lexical_weight=0.2,
+        metadata_weight=0.2,
+    ),
+    
+    "multilingual_quality": TriTopicConfig(
+        multilingual=True,
+        embedding_model="BAAI/bge-m3",
+        n_neighbors=20,
+        n_consensus_runs=15,
+        semantic_weight=0.6,
+        lexical_weight=0.2,
+        representative_method="hybrid",
+    ),
+    
+    "chinese": TriTopicConfig(
+        language="zh",
+        embedding_model="BAAI/bge-base-zh-v1.5",
+        tokenizer="jieba",
+        ngram_range=(1, 2),
+    ),
+    
+    "german": TriTopicConfig(
+        language="de",
+        embedding_model="paraphrase-multilingual-MiniLM-L12-v2",
+    ),
+}

tritopic/core/__init__.py

@@ -1,17 +0,0 @@
-"""Core components for TriTopic."""
-
-from tritopic.core.model import TriTopic, TriTopicConfig, TopicInfo
-from tritopic.core.graph_builder import GraphBuilder
-from tritopic.core.clustering import ConsensusLeiden
-from tritopic.core.embeddings import EmbeddingEngine
-from tritopic.core.keywords import KeywordExtractor
-
-__all__ = [
-    "TriTopic",
-    "TriTopicConfig",
-    "TopicInfo",
-    "GraphBuilder",
-    "ConsensusLeiden",
-    "EmbeddingEngine",
-    "KeywordExtractor",
-]