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

tritopic/config.py

@@ -1,305 +1,289 @@
 """
 TriTopic Configuration Module
 
-Defines all configuration parameters for the TriTopic model.
+This module provides configuration classes and utilities for TriTopic.
 """
 
 from dataclasses import dataclass, field
-from typing import Optional, List, Literal, Union
+from typing import Optional, List, Literal
 
 
 @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.
+    Configuration class for TriTopic model.
     
-    # 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".
+    All hyperparameters can be set here and passed to TriTopic.
     
-    # 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).
+    Example:
+        config = TriTopicConfig(
+            embedding_model="all-mpnet-base-v2",
+            n_neighbors=20,
+            use_iterative_refinement=True
+        )
+        model = TriTopic(config=config)
     """
     
-    # === Embedding & Language Settings ===
-    embedding_model: str = "auto"
+    # ==========================================================================
+    # Embedding Settings
+    # ==========================================================================
+    embedding_model: str = "all-MiniLM-L6-v2"
+    """Sentence-Transformer model name or path.
+    Options: "all-MiniLM-L6-v2", "all-mpnet-base-v2", "BAAI/bge-base-en-v1.5", etc."""
+    
     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 ===
+    """Batch size for embedding generation. Reduce if GPU OOM."""
+    
+    # ==========================================================================
+    # Graph Construction
+    # ==========================================================================
     n_neighbors: int = 15
+    """Number of neighbors for kNN graph construction."""
+    
     metric: str = "cosine"
+    """Distance metric: "cosine", "euclidean", "manhattan"."""
+    
     graph_type: Literal["knn", "mutual_knn", "snn", "hybrid"] = "hybrid"
+    """Graph type:
+    - "knn": Standard k-nearest neighbors
+    - "mutual_knn": Only bidirectional connections
+    - "snn": Shared nearest neighbors
+    - "hybrid": Combination of mutual_knn + snn (recommended)
+    """
+    
     snn_weight: float = 0.5
+    """Weight of SNN component in hybrid graph (0.0 to 1.0)."""
     
-    # === Multi-View Fusion ===
+    # ==========================================================================
+    # Multi-View Fusion
+    # ==========================================================================
     use_lexical_view: bool = True
+    """Include lexical (TF-IDF) similarity in graph construction."""
+    
     use_metadata_view: bool = False
+    """Include metadata similarity in graph construction."""
+    
     semantic_weight: float = 0.5
+    """Weight for semantic (embedding) similarity."""
+    
     lexical_weight: float = 0.3
+    """Weight for lexical (TF-IDF) similarity."""
+    
     metadata_weight: float = 0.2
-    lexical_method: Literal["tfidf", "bm25"] = "tfidf"
-    ngram_range: tuple = (1, 2)
+    """Weight for metadata similarity."""
     
-    # === Clustering ===
+    # ==========================================================================
+    # Clustering (Leiden + Consensus)
+    # ==========================================================================
     resolution: float = 1.0
+    """Leiden resolution parameter. Higher = more topics, lower = fewer topics."""
+    
     n_consensus_runs: int = 10
+    """Number of clustering runs for consensus clustering."""
+    
     min_cluster_size: int = 5
+    """Minimum documents per topic. Smaller clusters become outliers."""
     
-    # === Iterative Refinement ===
+    # ==========================================================================
+    # Iterative Refinement
+    # ==========================================================================
     use_iterative_refinement: bool = True
+    """Enable iterative embedding refinement based on discovered topics."""
+    
     max_iterations: int = 5
+    """Maximum number of refinement iterations."""
+    
     convergence_threshold: float = 0.95
-    refinement_strength: float = 0.15
+    """ARI threshold for convergence (0.0 to 1.0)."""
+    
+    refinement_strength: float = 0.1
+    """How strongly to pull embeddings toward topic centroids (0.0 to 1.0)."""
     
-    # === Keywords ===
+    # ==========================================================================
+    # Keyword Extraction
+    # ==========================================================================
     n_keywords: int = 10
-    keyword_method: Literal["ctfidf", "bm25", "keybert"] = "ctfidf"
+    """Number of keywords to extract per topic."""
     
-    # === 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"
+    """Number of representative documents per topic."""
     
-    # === Outlier Handling ===
+    keyword_method: Literal["ctfidf", "bm25", "keybert"] = "ctfidf"
+    """Keyword extraction method:
+    - "ctfidf": Class-based TF-IDF (fast, good quality)
+    - "bm25": BM25 scoring
+    - "keybert": KeyBERT extraction (slower, embedding-based)
+    """
+    
+    # ==========================================================================
+    # Outlier Handling
+    # ==========================================================================
     outlier_threshold: float = 0.1
-    reassign_outliers: bool = False
+    """Threshold for outlier detection (documents below this similarity)."""
+    
+    reduce_outliers: bool = False
+    """Whether to reassign outliers to nearest topics."""
+    
+    # ==========================================================================
+    # Dimensionality Reduction (for visualization)
+    # ==========================================================================
+    umap_n_neighbors: int = 15
+    """UMAP n_neighbors for visualization."""
+    
+    umap_n_components: int = 2
+    """UMAP dimensions for visualization."""
     
-    # === Misc ===
+    umap_min_dist: float = 0.1
+    """UMAP min_dist parameter."""
+    
+    # ==========================================================================
+    # Misc
+    # ==========================================================================
     random_state: Optional[int] = 42
+    """Random seed for reproducibility."""
+    
     verbose: bool = True
+    """Print progress information."""
+    
     n_jobs: int = -1
+    """Number of parallel jobs (-1 = all cores)."""
     
     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
+        # Validate weights
+        if self.use_lexical_view and not self.use_metadata_view:
+            total = self.semantic_weight + self.lexical_weight
+            if abs(total - 1.0) > 0.01:
+                # Normalize weights
+                self.semantic_weight = self.semantic_weight / total
+                self.lexical_weight = self.lexical_weight / total
+        elif self.use_lexical_view and self.use_metadata_view:
+            total = self.semantic_weight + self.lexical_weight + self.metadata_weight
+            if abs(total - 1.0) > 0.01:
+                # Normalize weights
                 self.semantic_weight = self.semantic_weight / total
                 self.lexical_weight = self.lexical_weight / total
-            else:
-                self.semantic_weight = 1.0
+                self.metadata_weight = self.metadata_weight / total
         
         # 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.n_consensus_runs <= 50, "n_consensus_runs must be between 1 and 50"
+        assert 0 <= self.snn_weight <= 1, "snn_weight must be between 0 and 1"
         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"
+        assert self.min_cluster_size >= 2, "min_cluster_size must be at least 2"
     
     def to_dict(self) -> dict:
         """Convert config to dictionary."""
         return {
-            k: v for k, v in self.__dict__.items() 
-            if not k.startswith('_')
+            'embedding_model': self.embedding_model,
+            'embedding_batch_size': self.embedding_batch_size,
+            'n_neighbors': self.n_neighbors,
+            'metric': self.metric,
+            'graph_type': self.graph_type,
+            'snn_weight': self.snn_weight,
+            'use_lexical_view': self.use_lexical_view,
+            'use_metadata_view': self.use_metadata_view,
+            'semantic_weight': self.semantic_weight,
+            'lexical_weight': self.lexical_weight,
+            'metadata_weight': self.metadata_weight,
+            'resolution': self.resolution,
+            'n_consensus_runs': self.n_consensus_runs,
+            'min_cluster_size': self.min_cluster_size,
+            'use_iterative_refinement': self.use_iterative_refinement,
+            'max_iterations': self.max_iterations,
+            'convergence_threshold': self.convergence_threshold,
+            'refinement_strength': self.refinement_strength,
+            'n_keywords': self.n_keywords,
+            'n_representative_docs': self.n_representative_docs,
+            'keyword_method': self.keyword_method,
+            'outlier_threshold': self.outlier_threshold,
+            'reduce_outliers': self.reduce_outliers,
+            'random_state': self.random_state,
+            'verbose': self.verbose,
+            'n_jobs': self.n_jobs,
         }
     
     @classmethod
     def from_dict(cls, config_dict: dict) -> "TriTopicConfig":
         """Create config from dictionary."""
-        return cls(**config_dict)
+        return cls(**{k: v for k, v in config_dict.items() if hasattr(cls, k)})
 
 
-# Predefined configurations for common use cases
-CONFIGS = {
-    "default": TriTopicConfig(),
+def get_config(**kwargs) -> TriTopicConfig:
+    """
+    Helper function to create a TriTopicConfig with custom parameters.
+    
+    All parameters are optional and default to TriTopicConfig defaults.
+    
+    Example:
+        config = get_config(
+            embedding_model="all-mpnet-base-v2",
+            n_neighbors=20,
+            use_iterative_refinement=True
+        )
     
+    Args:
+        **kwargs: Any TriTopicConfig parameter
+        
+    Returns:
+        TriTopicConfig instance
+    """
+    return TriTopicConfig(**kwargs)
+
+
+# Preset configurations for common use cases
+PRESETS = {
     "fast": TriTopicConfig(
         embedding_model="all-MiniLM-L6-v2",
         n_neighbors=10,
         n_consensus_runs=5,
         use_iterative_refinement=False,
-        representative_method="centroid",
+        keyword_method="ctfidf",
+    ),
+    "balanced": TriTopicConfig(
+        embedding_model="all-MiniLM-L6-v2",
+        n_neighbors=15,
+        n_consensus_runs=10,
+        use_iterative_refinement=True,
+        max_iterations=3,
+        keyword_method="ctfidf",
     ),
-    
     "quality": TriTopicConfig(
+        embedding_model="all-mpnet-base-v2",
+        n_neighbors=20,
+        n_consensus_runs=15,
+        use_iterative_refinement=True,
+        max_iterations=5,
+        keyword_method="ctfidf",
+    ),
+    "research": TriTopicConfig(
         embedding_model="BAAI/bge-base-en-v1.5",
         n_neighbors=20,
         n_consensus_runs=20,
+        use_iterative_refinement=True,
         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",
+        convergence_threshold=0.98,
+        keyword_method="ctfidf",
     ),
+}
+
+
+def get_preset(name: str) -> TriTopicConfig:
+    """
+    Get a preset configuration.
     
-    "chinese": TriTopicConfig(
-        language="zh",
-        embedding_model="BAAI/bge-base-zh-v1.5",
-        tokenizer="jieba",
-        ngram_range=(1, 2),
-    ),
+    Available presets:
+    - "fast": Quick results, lower quality
+    - "balanced": Good balance of speed and quality (default)
+    - "quality": Higher quality, slower
+    - "research": Maximum quality for research/publication
     
-    "german": TriTopicConfig(
-        language="de",
-        embedding_model="paraphrase-multilingual-MiniLM-L12-v2",
-    ),
-}
+    Args:
+        name: Preset name
+        
+    Returns:
+        TriTopicConfig instance
+    """
+    if name not in PRESETS:
+        raise ValueError(f"Unknown preset '{name}'. Available: {list(PRESETS.keys())}")
+    return PRESETS[name]

{tritopic-1.0.0.dist-info → tritopic-1.1.0.dist-info}/METADATA

@@ -1,13 +1,9 @@
 Metadata-Version: 2.4
 Name: tritopic
-Version: 1.0.0
+Version: 1.1.0
 Summary: Tri-Modal Graph Topic Modeling with Iterative Refinement
-Author-email: Roman Egger <roman.egger@example.com>
+Author-email: Roman Egger <roman.egger@smartvisions.at>
 License: MIT
-Project-URL: Homepage, https://github.com/roman-egger/tritopic
-Project-URL: Documentation, https://tritopic.readthedocs.io
-Project-URL: Repository, https://github.com/roman-egger/tritopic
-Project-URL: Issues, https://github.com/roman-egger/tritopic/issues
 Keywords: topic-modeling,nlp,machine-learning,bertopic,clustering,text-analysis,multilingual
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers

{tritopic-1.0.0.dist-info → tritopic-1.1.0.dist-info}/RECORD

@@ -1,5 +1,5 @@
 tritopic/__init__.py,sha256=BaHbardg5BW9zykYOtYG1ZM1nGwvfVt7DV7NJ7tp4l8,936
-tritopic/config.py,sha256=bsornL0etlRxQyMa6-Yx7tgXqVR1b8OZPpXM62cibhI,10120
+tritopic/config.py,sha256=vL47vU5KAYD1iCzH3cRMFUO1w1NSibmjIuAHNsBLu5c,10614
 tritopic/labeling.py,sha256=SJsvOXRl-q8f3qtk1S66FGozTJsW8bwNnAKGkAklmVQ,8883
 tritopic/model.py,sha256=mzptfvqG_Q81OcS6kiYd7u2uU2AKjxpDYKo9u1EfpH4,25015
 tritopic/visualization.py,sha256=MCiIgIoTzFoQ7GG9WjfSZlV2j1BBGzZwxRddmvmh1OY,9841
@@ -14,7 +14,7 @@ tritopic/multilingual/__init__.py,sha256=EagOqVqMDNKX7AfEAQfVgbR92f2vBy1KSM5O88A
 tritopic/multilingual/detection.py,sha256=xeZqNp4l-fRII5s2S4EMzBdJPf3Xgt6e1a3Od2hc2q4,5700
 tritopic/multilingual/stopwords.py,sha256=viMM1pb4VpDEmDpGpx_8sDfumXfrVXKfUULyOZXFFYU,29942
 tritopic/multilingual/tokenizers.py,sha256=seTCzRiUOqO0UbAqA3nn8V8EoVYQ1wiwqcH8lafRCxM,9954
-tritopic-1.0.0.dist-info/METADATA,sha256=kwoHBkE7i3m59h5i5QA10IsfBpJ5_rqI1u_SKXHFjQU,14178
-tritopic-1.0.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
-tritopic-1.0.0.dist-info/top_level.txt,sha256=9PASbqQyi0-wa7E2Hl3Z0u1ae7MwLcfgFliFE1ioFBA,9
-tritopic-1.0.0.dist-info/RECORD,,
+tritopic-1.1.0.dist-info/METADATA,sha256=nIWD3zUMOQR9efdUFo8zUjM0JVJGgrzgZVDyLbbjJ7I,13922
+tritopic-1.1.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+tritopic-1.1.0.dist-info/top_level.txt,sha256=9PASbqQyi0-wa7E2Hl3Z0u1ae7MwLcfgFliFE1ioFBA,9
+tritopic-1.1.0.dist-info/RECORD,,