A deep learning project that fine-tunes DistilBERT for binary sentiment classification. It includes training, evaluation, inference, and a Streamlit web UI.
- Public link: https://sentiment-nlp-live-20260617.streamlit.app/
- Local run link: http://localhost:8501/
The public link is a Cloudflare quick tunnel. It stays live while the cloudflared process is running on this machine.
Run start_public_link.bat from the project root. It starts:
- Streamlit on localhost:8501
- Cloudflare quick tunnel for a public HTTPS URL
Keep both terminal windows open while sharing the app.
- Python 3.10 or higher
piporconda- About 2 GB of free disk space for model files
# Clone the repository
git clone https://github.com/EbiAraz/SENTIMENT-NLP-.git
cd SENTIMENT-NLP-
# Install dependencies
pip install -r requirements.txt
# Launch the Streamlit UI
python -m streamlit run app.pyThe app will open at http://localhost:8501/ in your browser.
# Use local development dependencies
pip install -r SRC/Requirement.txt
# Run the Streamlit development UI
python -m streamlit run SRC/Streamlit_App.py- Local Streamlit app runs correctly
- DistilBERT model inference works correctly
- Training, evaluation, and batch prediction are operational
- Deployment configuration is ready
- Streamlit Cloud: currently unavailable due to a 403 Forbidden access issue
- Hugging Face Spaces: recommended alternative if you want hosted deployment
- Local testing: fully functional
- SSH tunneling: available for temporary sharing
- Create an account at huggingface.co
- Create a new Space with the Streamlit template
- Connect the GitHub repo or upload the files
- The app auto-deploys on push
- Fork or push the repo to GitHub
- Connect the repo to your hosting platform
- Set the startup command to
python -m streamlit run app.py - Deploy
# Terminal 1: Run the app
python -m streamlit run app.py
# Terminal 2: Create tunnel
ssh -o StrictHostKeyChecking=no -R 80:localhost:8501 nokey@localhost.runThis generates a public HTTPS URL that changes each time you restart the tunnel.
SENTIMENT_Project/
├── app.py # Streamlit entry point (deployment)
├── requirements.txt # Production dependencies
├── run_pipeline.py # Full training/eval/inference pipeline
├── SRC/
│ ├── Config.py # Centralized config
│ ├── Train.py # Model fine-tuning on IMDb
│ ├── Evaluate_Model.py # Performance evaluation
│ ├── Inference.py # Single text prediction
│ ├── Batch_Predict.py # CSV batch predictions
│ ├── Streamlit_App.py # Web UI (local development)
│ ├── Preprocess.py # Data preprocessing
│ ├── Data_Loader.py # Dataset utilities
│ ├── Requirement.txt # Development dependencies
│ └── Models/ # Trained model checkpoints
├── Data/ # Datasets and sample data
├── Models/ # Model outputs
└── Outputs/ # Predictions and results
# Production (recommended for deployment)
pip install -r requirements.txt
# Development (local experiments)
pip install -r SRC/Requirement.txt- streamlit
- transformers
- torch and torchvision
- pandas, numpy, scikit-learn
- datasets, evaluate
# Deploy-ready entry point
python -m streamlit run app.py
# Or development UI
python -m streamlit run SRC/Streamlit_App.pyThen open http://localhost:8501/ in your browser and enter text for sentiment prediction.
Train the model:
python SRC/Train.py
python SRC/Train.py --smoke-testEvaluate performance:
python SRC/Evaluate_Model.pyPredict sentiment for a single text:
python SRC/Inference.py --text "Great movie!"Batch predict from CSV:
python SRC/Batch_Predict.py --input Data/sample_reviews.csv --output predictions.csvRun the full pipeline:
python run_pipeline.py
python run_pipeline.py --fast# Reinstall all dependencies
pip install -r requirements.txt --force-reinstall
# Or upgrade pip first
pip install --upgrade pip
pip install -r requirements.txt# Use a different port
python -m streamlit run app.py --server.port 8502Open SRC/Config.py and reduce BATCH_SIZE or MAX_LENGTH.
The app automatically falls back to HuggingFace's default DistilBERT model. To train and save your own checkpoint:
python SRC/Train.py- Base model: DistilBERT (
distilbert-base-uncased) - Task: binary sentiment classification
- Training data: IMDb movie reviews (50K samples)
- Framework: HuggingFace Transformers + PyTorch
- Input: any text string
- Output: predicted label and confidence score
- Paths are configured to be execution-location independent
- Model files are auto-downloaded from HuggingFace on first run
- Streamlit UI includes interactive examples
- Batch predictions support custom text column names
- Training uses GPU if available, otherwise CPU
- Configure
SRC/Config.pyfor customization
- Streamlit Cloud deployment currently returns a 403 Forbidden error due to platform account access.
- Workaround: deploy to Hugging Face Spaces, Railway, or Render.
- First run is slower because the model and dependencies download on the initial execution.
- Later runs are faster due to caching.
- Initial model download requires internet access.
# Create a virtual environment (optional but recommended)
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install dev dependencies
pip install -r SRC/Requirement.txtpython SRC/Train.py --smoke-test
python SRC/Evaluate_Model.py
python SRC/Inference.pyFeel free to fork, modify, and submit pull requests.
- Support for other languages
- Multi-class classification with star ratings
- Model quantization for faster inference
- GPU optimization for batch processing
- API deployment with FastAPI
- Docker containerization
This project is open source and available under the MIT License.
For issues or questions:
- GitHub Issues: SENTIMENT-NLP- Issues
- Author: EbiAraz