Skip to content

ReviewPulse v1.0.0 - Assessment-Ready Baseline + BiLSTM

Choose a tag to compare

View all tags
@lfariabr lfariabr released this 26 Apr 01:03
· 180 commits to main since this release
v1.0.0
922fd7e

ReviewPulse v1.0.0 - Assessment-Ready Baseline + BiLSTM Release

Release date: 2026-04-26

Summary

ReviewPulse v1.0.0 marks the first complete assessment-ready release of the project. The build covers Issues #1-#19 and takes the system from scratch to a deployed Streamlit sentiment-classification app.

The release includes a complete NLP pipeline for multi-domain Amazon reviews: data parsing, preprocessing, EDA, classical ML baseline, neural BiLSTM comparison model, evaluation, error analysis, inference API, Streamlit interface, tests, demo cases, presentation material, individual report scaffolding, and ethics/reference coverage.

What Shipped

  • Raw .review parsing across Books, DVDs, Electronics, and Kitchen & Housewares.
  • Label audit and preprocessing pipeline with text cleaning, outlier removal, and reproducible train/validation/test splits.
  • EDA helpers and notebook-backed findings for class balance, domain balance, rating distribution, review length, and label quality.
  • TF-IDF + Logistic Regression baseline model.
  • BiLSTM + optional GloVe neural model for comparison.
  • Training loop with validation F1 checkpointing, gradient clipping, and best-model persistence.
  • Evaluation module with held-out test metrics, confusion matrix generation, and sampled error analysis.
  • Shared inference API via predict_sentiment().
  • Streamlit app with autonomous model switching between baseline and BiLSTM.
  • Random sample generator, confidence display, progress bar, and raw JSON output.
  • Demo acceptance test cases using real model outputs.
  • Presentation outline, individual contribution report scaffold, contribution evidence, references, and ethics notes.

Model Results

Held-out test results:

Model Accuracy F1
TF-IDF + Logistic Regression 82.7% 81.9%
BiLSTM + GloVe 81.0% 80.3%

Validation result:

Model Best validation F1
BiLSTM + GloVe 84.0%

The baseline is the default deployed model because it generalised better on the held-out test split. The BiLSTM remains available in the app as the neural comparison model and demonstrates the project requirement for a defined neural architecture.

Application Experience

The Streamlit app allows users to:

  • paste or generate a sample review;
  • choose between TF-IDF + Logistic Regression and BiLSTM + GloVe;
  • run classification from the UI without touching code;
  • inspect predicted sentiment, confidence, and raw result JSON.

This makes the project suitable for live demonstration and facilitator testing.

Test Coverage

The release includes:

  • 117 unit tests;
  • 5 slow integration tests;
  • parser, preprocessing, dataset, baseline, model, training, evaluation, and inference coverage.

Fast test command:

pytest tests/ -q -m "not slow"

Full test command:

pytest tests/

Known Limitations

  • Negation remains difficult: phrases such as "not bad" can still be misclassified.
  • Sarcasm and mixed sentiment are hard for both models.
  • BiLSTM confidence is uncalibrated, so high confidence does not guarantee high correctness.
  • The dataset is from 2007 and may not fully represent modern review language, slang, or emoji.
  • The app is a demo and should not be used for high-stakes decisions without human oversight.

Issue Coverage

This release covers:

  • Issues #1-#7: project setup, parser, preprocessing, EDA, vocabulary, dataset loaders, and optional GloVe support.
  • Issues #8-#11: baseline model, BiLSTM model, training loop, evaluation, and error analysis.
  • Issues #12-#15: inference module, Streamlit app, unit tests, and demo acceptance cases.
  • Issues #16-#19: presentation pack, individual report scaffold, contribution evidence, references, and ethics coverage.

Issue #20 remains the submission packaging and release evidence task. Issue #21 remains open for the optional transformer stretch.

Next Milestone

The natural next milestone is v2.0.0: clean pretrained DistilBERT support using Hugging Face transformers, followed by RoBERTa benchmarking in a later minor release.

Planned version path:

  • v1.0.0: complete assessment-ready baseline + BiLSTM app.
  • v1.1.0: optional submission polish and small UX/documentation improvements.
  • v2.0.0: pretrained DistilBERT support.
  • v2.1.0: RoBERTa extension or transformer benchmarking.
  • v1.0.x: patch releases for typo fixes, docs corrections, or non-behavioral cleanup.
Assets 2
Loading