tritopic 0.1.0__py3-none-any.whl → 1.1.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,289 @@
+"""
+TriTopic Configuration Module
+
+This module provides configuration classes and utilities for TriTopic.
+"""
+
+from dataclasses import dataclass, field
+from typing import Optional, List, Literal
+
+
+@dataclass
+class TriTopicConfig:
+    """
+    Configuration class for TriTopic model.
+    
+    All hyperparameters can be set here and passed to TriTopic.
+    
+    Example:
+        config = TriTopicConfig(
+            embedding_model="all-mpnet-base-v2",
+            n_neighbors=20,
+            use_iterative_refinement=True
+        )
+        model = TriTopic(config=config)
+    """
+    
+    # ==========================================================================
+    # 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
+    """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
+    # ==========================================================================
+    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
+    """Weight for metadata similarity."""
+    
+    # ==========================================================================
+    # 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
+    # ==========================================================================
+    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
+    """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)."""
+    
+    # ==========================================================================
+    # Keyword Extraction
+    # ==========================================================================
+    n_keywords: int = 10
+    """Number of keywords to extract per topic."""
+    
+    n_representative_docs: int = 5
+    """Number of representative documents per topic."""
+    
+    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
+    """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."""
+    
+    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."""
+        # 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
+                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.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.min_cluster_size >= 2, "min_cluster_size must be at least 2"
+    
+    def to_dict(self) -> dict:
+        """Convert config to dictionary."""
+        return {
+            '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(**{k: v for k, v in config_dict.items() if hasattr(cls, k)})
+
+
+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,
+        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,
+        convergence_threshold=0.98,
+        keyword_method="ctfidf",
+    ),
+}
+
+
+def get_preset(name: str) -> TriTopicConfig:
+    """
+    Get a preset configuration.
+    
+    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
+    
+    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/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",
-]