Enhance README.md with detailed model description, usage examples, metrics, limitations, and training data for the IMDb sentiment analysis model.

README.md

@@ -1,37 +1,103 @@
-# IMDb Sentiment Analysis Model
+---
+language: en
+license: mit
+tags:
+  - sentiment-analysis
+  - text-classification
+  - imdb
+  - scikit-learn
+  - tfidf
+  - logistic-regression
+  - naive-bayes
+model-index:
+  - name: imdb-movie-review-sentiment-analysis
+    results:
+      - task:
+          type: text-classification
+          name: Sentiment Analysis
+        dataset:
+          name: IMDb Large Movie Review Dataset
+          type: imdb
+        metrics:
+          - type: accuracy
+            value: 0.8847
+            name: Logistic Regression Accuracy
+          - type: accuracy
+            value: 0.8520
+            name: Naive Bayes Accuracy
+---
 
-This repository contains a trained sentiment analysis model for IMDb movie reviews.
+# IMDb Movie Review Sentiment Analysis
 
-## Model Performance
-- Logistic Regression: ~88.47% accuracy
-- Naive Bayes: ~85.2% accuracy
+## Model description
 
-## Files
-- `saved_models/`: Directory containing trained models
-- `inference.py`: Script for making predictions
-- `train_and_save_model.py`: Script to train and save models
-- `requirements.txt`: Python dependencies
+**imdb-movie-review-sentiment-analysis** is a machine learning model that predicts the sentiment (positive or negative) of movie reviews from IMDb.  
+It uses a TF-IDF vectorizer for feature extraction and an ensemble of two classic machine learning classifiers: Logistic Regression and Multinomial Naive Bayes.
 
-## Usage
+The model was trained on the official IMDb Large Movie Review Dataset (50,000 labeled reviews) with standard NLP preprocessing: lowercasing, special character removal, tokenization, stopword removal, and lemmatization.
+
+**Intended use:**
+- Sentiment analysis of English-language movie reviews
+- Educational and research purposes
+- As a baseline for more advanced NLP projects
+
+---
+
+## Example usage
 
-### Load and Use the Model
 ```python
 from inference import SentimentAnalyzer
 
-# Initialize analyzer
-analyzer = SentimentAnalyzer()
+# Initialize the analyzer (make sure model files are in 'saved_models/')
+analyzer = SentimentAnalyzer(model_dir="saved_models")
 
-# Make prediction
-result = analyzer.predict("This movie was amazing!")
+# Predict sentiment for a new review
+review = "This movie was absolutely fantastic! I loved every minute of it."
+result = analyzer.predict(review)
 print(result)
+# Output example:
+# {
+#   'logistic_regression': {'prediction': 'positive', 'confidence': 0.98, ...},
+#   'naive_bayes': {'prediction': 'positive', 'confidence': 0.95, ...}
+# }
 ```
 
-### Deploy on Streamlit
-```bash
-streamlit run streamlit_deployment.py
-```
+---
+
+## Metrics
+
+- **Logistic Regression Accuracy:** 88.47%
+- **Naive Bayes Accuracy:** 85.20%
+- Evaluated on a held-out test set (20% of the IMDb dataset, 10,000 reviews).
+
+---
+
+## Limitations
+
+- Only works for **English** text.
+- Not robust to sarcasm, irony, or highly ambiguous reviews.
+- May not generalize well to domains outside of movie reviews.
+- Does not handle emojis, slang, or non-standard text well.
+- Classic ML models (not deep learning): may underperform on very complex language.
+
+---
+
+## Training data
+
+- **IMDb Large Movie Review Dataset**: 50,000 movie reviews labeled as positive or negative.
+- Balanced: 25,000 positive and 25,000 negative reviews.
+- Reviews are preprocessed (lowercased, cleaned, tokenized, stopwords removed, lemmatized).
+- Dataset is widely used for benchmarking sentiment analysis models.
+
+---
+
+## License
+
+MIT
+
+---
+
+## Author
 
-## Model Details
-- **Vectorizer**: TF-IDF with 5000 features
-- **Preprocessing**: Lowercase, special char removal, tokenization, stopword removal, lemmatization
-- **Models**: Logistic Regression and Naive Bayes
+Abdelmonem Hatem
+---