(TF-IDF + Logistic Regression + SHAP)
End-to-end machine learning project for binary sentiment classification of text with interpretable predictions. The project includes a reproducible training pipeline, model evaluation, SHAP-based explainability, and a public Streamlit application.
The application is publicly available and requires no setup:
Users can enter arbitrary text, get a sentiment prediction, model confidence, and see the most influential words and phrases that affected the decision.
- Text Classification with Explainability
This project demonstrates a complete ML workflow for text classification:
- Binary sentiment classification (positive / negative)
- Text vectorization using TF-IDF
- Classification with Logistic Regression
- Local model explainability using SHAP
- Reproducible execution via standalone scripts
- Interactive inference and explanations via Streamlit
The project is intentionally structured to clearly separate:
- reusable ML logic (
src/tce) - orchestration scripts (
scripts/) - exploratory notebooks (
notebooks/) - application-level code (
app.py)
This application can be used for text sentiment analysis in a variety of contexts, such as:
- Customer feedback: Quickly assess whether reviews or comments are positive or negative.
- Product or service monitoring: Track public sentiment over time to identify trends or potential issues.
- Content moderation: Detect negative or harmful sentiment in user-generated content.
- Educational purposes: Learn how TF-IDF, Logistic Regression, and SHAP work together in a complete ML pipeline.
- Prototyping NLP solutions: Serve as a reusable starting point for other text classification tasks.
The interactive Streamlit app allows users to explore predictions and explanations without setup, making it accessible to both technical and non-technical users.
The model is trained on the IMDb Large Movie Review Dataset:
- Source: IMDb dataset
- Task: binary sentiment classification (
positive/negative)
The dataset is not included in the repository due to its size. It is downloaded automatically via a dedicated script.
- The application supports English language input only.
- Predictions for texts written in other languages may be meaningless or misleading.
- This limitation comes from the TF-IDF vectorizer and vocabulary built only on English data.
artifacts/
├── evaluation_report/
│ ├── figures/ # ROC and PR curves
│ └── model_metrics.json # Evaluation metrics
├── notebooks_artifacts/ # Outputs from notebooks, generated locally via notebooks execution
config/
├── model.json # Model hyperparameters
├── paths.json # Centralized paths configuration
data/ # Data directory, generated locally
models/ # Generated locally (not versioned)
├── model.joblib
└── explainer.joblib
notebooks/
├── 01_eda.ipynb
├── 02_preprocessing_and_training.ipynb
└── 03_explainability.ipynb
scripts/
├── load_data.py # Download and prepare dataset
├── train_model.py # Train and save model
├── build_explainer.py # Build SHAP explainer
└── evaluate_model.py # Evaluate model on test set
src/tce/
├── data.py # Data loading and preprocessing
├── model.py # Pipeline construction and inference
├── evaluate.py # Metrics computation and plots
├── explain.py # SHAP-based explainability
└── utils.py # Logging and helper utilities
app.py # Streamlit application
- No data or models in version control
- Reproducible scripts for every pipeline step
- Reusable ML logic isolated in a Python package (
src/tce) - Clear separation between experimentation, training, and deployment
- Explainability-first approach
- The dataset is downloaded via
scripts/load_data.py - Trained model and SHAP explainer are saved locally
- Neither data nor models are committed to the repository
This keeps the repository lightweight while preserving full reproducibility.
- Python >= 3.10
- CPU-only (no GPU required)
python -m venv venv
source venv/bin/activate # Linux/macOS
venv\Scripts\activate # Windowspython -m pip install --upgrade pip
pip install -e .
pip install -r requirements.txtpython scripts/load_data.pypython scripts/train_model.pypython scripts/build_explainer.pypython scripts/evaluate_model.pyEvaluation artifacts (metrics and plots) will be saved to artifacts/evaluation_report/.
streamlit run app.pyThe application allows the user to:
-
Manually input text
-
Obtain:
-
predicted class (positive / negative)
-
model confidence
- Inspect explanations:
-
top influential words and phrases
-
contribution sign and magnitude (SHAP values)
The number of displayed influential tokens can be adjusted via the sidebar.
The model and explainer are trained automatically on application startup and cached for reuse.
Model decisions are explained using SHAP:
-
per-sample explanations
-
token-level contribution scores
-
clear distinction between positive and negative influence
Explanations are available:
-
interactively in the Streamlit app
-
in exploratory notebooks
The notebooks/ directory contains exploratory and experimental work:
-
exploratory data analysis (EDA)
-
feature inspection and hyperparameter selection
-
explainability visualization
Notebook outputs are stored separately in artifacts/notebooks_artifacts/ and are not part of the production pipeline.
| Metric | Value |
|---|---|
| Accuracy | 0.91 |
| F1-score | 0.91 |
| ROC AUC | 0.97 |
-
Type hints across all modules
-
Centralized logging
-
Explicit error handling
-
Entry-point guarded scripts
-
Modular and testable design
-
Python
-
scikit-learn
-
SHAP
-
Streamlit
-
joblib
This project was developed as a personal ML portfolio project with a focus on:
-
interpretability,
-
reproducibility,
-
clean project structure.
This project is licensed under the MIT License – see the LICENSE file for details.