A clean, production-ready topic modeling application built following BERTopic 2025 best practices with sentiment-guided discovery, hierarchical exploration, and comprehensive data viewing.

# Simple launch
python3.11 -m streamlit run bertopic_demo.py

# Or with any Python 3.9+
python3 -m streamlit run bertopic_demo.py

If automatic installation fails:

pip install -r requirements.txt
streamlit run bertopic_demo.py

• Guided topic modeling with sentiment-aware seed topics (2025 best practice)
• Dynamic granularity control - adjust topic detail level in real-time
• Advanced representation models - KeyBERT + MaximalMarginalRelevance chaining
• Reproducible results with proper random state management

• Sentiment-aware seed topics guide natural topic formation
• Interactive sentiment filtering within any discovered topic
• Comprehensive sentiment analysis with confidence scoring
• No hardcoded business assumptions - discovers actual patterns

• Four organized tabs - Upload, Overview, Hierarchy, Data Table
• Paginated data viewing - handles large datasets (60K+ rows) efficiently
• Dynamic reconfiguration - change settings and see immediate results
• Comprehensive export options with complete analysis metadata

1. 📤 Upload CSV: Select a CSV file with text data
2. 📝 Choose Column: Pick the text column to analyze
3. 🎯 Configure Granularity: Control topic detail level (Very Granular/Balanced/Broad)
4. 🌱 Add Seed Words: Optional keywords to guide topic discovery
5. 🤖 Choose Labeling: Use AI for human-readable labels or keyword-based labels
6. 🚀 Discover Topics: View all topics in comprehensive overview table
7. 🔍 Drill Down:
   • Click "Find Sub-Topics" for deeper analysis
   • View "Topic Hierarchy" with interactive visualizations
   • Explore "Sentiment Breakdown" tables
8. 💾 Export: Download complete results with hierarchical structure

• Python: 3.9+ (tested with 3.11, 3.13+)
• Memory: 500MB+ available RAM
• Platform: Windows, macOS, Linux

• Web Framework: Streamlit 1.28+
• Embeddings: Model2Vec (lightweight alternative to TensorFlow)
• Topic Modeling: BERTopic 0.16+
• Clustering: HDBSCAN, UMAP
• Visualization: Plotly
• Monitoring: psutil, loguru

"ModuleNotFoundError": Install dependencies

pip install streamlit loguru model2vec bertopic plotly psutil

"Python version error": Use the universal launcher

python3 launch.py

"Port already in use": Specify different port

streamlit run bertopic_demo.py --server.port 8502

• ✅ Upload CSV files
• ✅ Topic modeling with BERTopic
• ✅ Interactive parameter tuning
• ✅ Seed word support
• ✅ Topic visualization
• ✅ Document exploration
• ✅ Results export

• ✅ Model2Vec lightweight embeddings
• ✅ Multi-level caching
• ✅ Session state management
• ✅ Memory monitoring
• ✅ Real-time progress tracking
• ✅ Background processing

Your CSV should have at least one text column:

For issues or questions:

1. Check the troubleshooting section above
2. Ensure all dependencies are installed
3. Try the universal launcher: python3 launch.py

🎉 Ready to explore your text data with lightning-fast topic modeling!