ReviewPulse v3.0.0 - Aspect-Based Sentiment Analysis

ReviewPulse v3.0.0 adds an aspect-based sentiment analysis workflow on SemEval-2014 Task 4
Restaurants, predicting negative, neutral or positive for each aspect supplied with a review.
The ISY503 v2.3.0 binary workflow is preserved and untouched: v3 reuses none of its artifacts or
APIs, and lives under src/absa/ with its own data contracts, models, evaluation and app pages.

What it does

A six-model ladder over one shared official-test prediction set. TF-IDF and a target-agnostic LSTM
are review-only controls; ATAE-LSTM and DistilBERT sentence-pair receive the review and the aspect;
a target-agnostic GRU and a review-only TextCNN are exploratory and reported separately.

The headline result is the mixed-polarity subset: 228 instances across 80 sentences where one
sentence carries aspects with opposing labels. Aspect-conditioned models lead both review-only
controls there, which is the point of the whole comparison.

ATAE-LSTM exposes learned attention and DistilBERT gradient x input attribution, both aligned to
exact visible review offsets. Everything else explicitly reports token evidence as unsupported.
Displayed scores are indicative token-level evidence and never a causal explanation.

Submission archives

Both are built from c2ee52a by scripts/build_a3_package.py, which works from an explicit
allowlist, refuses a dirty working tree and rejects unresolved Git LFS pointers. Entry timestamps
are fixed to the source commit time and paths are sorted, so rebuilding the same mode reproduces
identical bytes.

Archive	Bytes	SHA-256
ReviewPulse-v3.0.0-lightweight.zip	54,048,531	935aabe3470082d0ecbb92596b60e65203e326caab91e46c3deb2609840ca9b9
ReviewPulse-v3.0.0-all-models.zip	301,254,100	0c773f444de2c1459d488ae4ab2c534c3025cbd5b445b530812421705ea7c17d

These digests are published here because every checklist and release document inside the repository
travels inside the archives, and no file can carry a checksum of the container holding it. Each
archive's PACKAGE_MANIFEST.json records the source commit and the size and digest of every entry.

The two archives differ only in the v3 DistilBERT directory, roughly 256 MB. Selecting that model
in the lightweight archive reports it unavailable and returns no prediction; a missing artifact is
always reported and never silently substituted.

Neither archive needs the SemEval corpus, an accelerator or a network connection. The trained
artifacts are shipped and inference runs on CPU.

Running it

unzip ReviewPulse-v3.0.0-all-models.zip && cd ReviewPulse-v3.0.0
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt -c constraints-a3.txt
python -m pytest -q
streamlit run app.py

Start at docs/dle602-a3/SUBMISSION_README.md.

Test outcomes depend on the environment, and every skip is an intentional absence of licensed data
or Git metadata: 363 passed / 3 skipped on the development machine, 357 / 9 in a clean clone, and
355 / 11 in the extracted lightweight archive.

Data

The SemEval-2014 Restaurants XML is licensed and is not redistributed. No archive contains it or
any row-level export derived from it. Acquisition instructions and checksums are in
docs/dle602-a3/semeval-restaurants.md.

Validation

Independent Streamlit QA by Juan Martinez across 12 deployed cases (#120, #121). Independent
reproduction by Victor Dorantes (#123): stored metrics recomputed from all six confusion matrices,
the four canonical models retrained and evaluated on CUDA, and the shipped artifacts verified
without retraining.

Known limitations. Restaurants only; aspects are supplied by the user and never extracted
automatically; results come from a single frozen seed on a small benchmark; timing is observational
because models were not all evaluated on identical hardware; attention and attribution do not
establish a faithful causal explanation.

ReviewPulse v3.0.0-rc.1 — ABSA Release Candidate

ReviewPulse v3.0.0 — Aspect-Based Sentiment Analysis

Status: release candidate
Track: DLE602 Assessment 3
Last updated: 2026-07-23

Summary

ReviewPulse v3.0.0 is the DLE602 evolution of the product delivered for ISY503. Versions 1.x and 2.x classify the overall sentiment of an Amazon review. Version 3.0 adds an isolated aspect-based sentiment analysis (ABSA) workflow that predicts negative, neutral or positive for each restaurant aspect supplied by the user.

The legacy v2.3.0 workflow remains available and its binary API and artifacts are not reused by v3. The new implementation lives under src/absa/, with separate data contracts, model artifacts, evaluation outputs and application entry points.

This document is the consolidated delivery record for v3. Detailed experiment contracts remain in docs/dle602-a3/, and GitHub issue #72 remains the implementation tracker.

Delivery Status

Area	Delivered in the candidate	Remaining release gate
Data and task contract	Restaurants parser, offset audit, fixed labels, grouped splits and mixed-polarity subset	None for core scope
Four-model ladder	TF-IDF, target-agnostic LSTM, ATAE-LSTM and DistilBERT sentence pair	Regenerate the final four verified artifacts together
Training controls	Seeded runs, regularisation, early stopping, best-checkpoint restoration and run metadata	Review the final overfitting diagnostics
Common evaluation	Reproducible runner, shared predictions, metrics, efficiency evidence, confusion matrices and error candidates	Complete issue #84 from reviewed code and final artifacts
Application	Separate v2/v3 pages, manual multi-aspect input, sample generation and controlled missing-artifact errors	Final clean-process smoke test
Token evidence	ATAE-LSTM attention payload and indicative-evidence contract	Complete the user-facing ATAE/DistilBERT evidence work in issue #85
Academic package	Protocols and traceable machine-readable outputs	Write the evidence-backed report in issue #88
Release package	Release notes and documented commands	Clean install, package, tag and archive in issue #89

1. Data and Task Contract

The v3 core dataset is the SemEval-2014 Task 4 Restaurants domain. Laptops, automatic aspect extraction and topic modelling are outside the core release.

• Training and evaluation use the SemEval gold aspect terms.
• The application asks the user to enter one or more aspects manually.
• Labels have the fixed order negative, neutral, positive.
• The original SemEval conflict label is counted during audit and excluded from three-class modelling.
• The mixed-polarity multi-aspect subset contains sentences with at least two retained aspects assigned different polarities.
• Development splits are grouped by sentence so instances from the same sentence cannot leak across partitions.
• Raw sentence text and character offsets remain authoritative; v2 text cleaning is not applied to ABSA alignment.

Acquisition, licensing constraints and checksum recording are documented in docs/dle602-a3/semeval-restaurants.md.

2. Four-Model Comparison Ladder

All four models use the same retained examples, label mapping and official Restaurants test partition.

Model	Input contract	Purpose
TF-IDF + Logistic Regression	Review only	Lightweight classical baseline
Target-agnostic LSTM	Review only	Controlled neural baseline without aspect conditioning
ATAE-LSTM	Review and aspect	Lightweight aspect-conditioned model with attention weights
DistilBERT sentence pair	Review and aspect	Pretrained contextual aspect-conditioned model

The review-only models intentionally do not receive the target aspect. Their behaviour on mixed-polarity sentences is part of the comparison, rather than an accidental input mismatch. No v2 binary checkpoint or metric is accepted as v3 evidence.

3. Reproducible Training

Issue #91 aligned the implementation with the submitted A2 methodology:

• Python, NumPy and PyTorch are seeded before split, model and data-loader creation.
• CUDA, Apple MPS and CPU device selection are supported where applicable.
• Neural optimisers use recorded weight decay.
• Development macro-F1 selects checkpoints; the best state is restored before final metrics are produced.
• Early stopping, complete epoch history, best epoch and overfitting diagnostics are persisted.
• Training duration, configuration, dataset checksums, seed and source commit are stored with the artifacts.
• Loss functions are instantiated outside batch loops.

The exact defaults and the fixed-seed versus multi-seed decision rule are defined in docs/dle602-a3/training-protocol.md.

4. Common Evaluation and Error Analysis

Issue #84 provides one command that loads the four verified model families and evaluates them over one shared official-test prediction set.

The evaluation records:

• accuracy, macro-F1, per-class metrics and confusion matrices;
• full-test and mixed-polarity multi-aspect results;
• training time, artifact size, cold start, first-prediction time, warm latency and throughput;
• representative conditioned-model wins, review-only wins, disagreements and common errors;
• source commit, seed, device, dataset checksums and the SHA-256 digest of the shared predictions.

Generated files below outputs/absa/evaluation/ are:

File	Release evidence
results.json	Metrics, environment, provenance and efficiency measurements
predictions.csv	Shared gold labels and four-model predictions
comparison.md	Report-ready comparison table
confusion_matrices.png	Four official-test confusion matrices
error_analysis.json	Ordered error categories and candidate examples

The default runner rejects older artifacts that do not contain the reproducibility metadata introduced by issue #91. The diagnostic override for legacy local files must not be used for report claims. Final numerical results will be added only after all four artifacts are regenerated from the same reviewed commit and verified inputs.

5. Application Experience

The Streamlit landing page presents two deliberately separate product phases:

• v2.3.0 / ISY503: binary sentiment for one complete Amazon review.
• v3.0.0 / DLE602: three-class sentiment for one or more manually entered restaurant aspects.

The v3 page supports comma-separated aspects, ordered per-aspect results, model selection and sample generation for repeatable demonstrations. TF-IDF and the target-agnostic LSTM receive only the review; ATAE-LSTM and DistilBERT receive the review-and-aspect pair. Missing data, dependencies or model artifacts produce controlled application errors and never fall back silently to a v2 model.

6. Indicative Token Evidence

Interpretability claims are intentionally limited.

• ATAE-LSTM can expose aligned attention weights.
• DistilBERT token attribution or attention visualisation is tracked in issue #85.
• TF-IDF and the target-agnostic LSTM are not required to produce a heatmap.
• Any displayed weights are indicative token-level evidence, not model reasoning or a causal explanation.

The final v3 release requires the supported evidence views, legends, alignment checks and caveats from issue #85. Until that issue closes, the evidence presentation is incomplete even though aspect predictions are functional.

7. Reliability and Safety

The candidate includes focused protection for the new pipeline:

• external SemEval XML is parsed with defusedxml;
• parser tests fail when available source XML unexpectedly produces no examples;
• split tests assert deterministic sentence-level separation;
• checkpoint tests protect label mappings, configuration and clean loading;
• legacy v2 and isolated v3 workflows have non-regression coverage;
• the current full-suite result on this candidate branch is 230 passed, 8 skipped.

The eight skips apply when the optional, gitignored legacy Amazon dataset is absent.

Canonical Commands

From the repository root in the recorded Python environment:

# Verify the isolated v3 path.
.venv/bin/python -m pytest tests/absa -q
.venv/bin/python scripts/smoke_absa.py

# Regenerate all four verified artifacts.
.venv/bin/python -m src.absa.training.runner --device auto

# Produce the common comparison package.
.venv/bin/python -m src.absa.evaluation.runner --device auto

# Run the full product test suite and application.
.venv/bin/python -m pytest tests/ -q
.venv/bin/streamlit run app.py

SemEval source files and generated model/evaluation artifacts remain local and gitignored. The release package must preserve their checksums and reproducibility metadata without committing restricted data or large binaries.

Known Limitations

• Core scope covers Restaurants only.
• Users must provide aspects; v3 does not extract them automatically.
• The SemEval benchmark is small, so model comparisons must retain the recorded overfitting and variance caveats.
• Attention or attribution does not establish a faithful causal explanation.
• Final performance and efficiency claims depend on a common verified run and must identify the recorded device.
• Large model artifacts are local rather than hosted.

Issue Coverage and Final Gates

Completed foundation: issues #73–#83, #86, #87 and #91.

Open release path:

1. #84 — merge the reviewed four-model comparison and regenerate final evidence.
2. #85 — complete indicative token-evidence views.
3. #88 — write the A3 implementation report from veri...

ReviewPulse v2.3.0 — Compatibility Cleanup

ReviewPulse v2.3.0 — Compatibility Cleanup

Release date: 2026-05-04

Summary

This release records the Issue #59 cleanup that removes legacy flat-module compatibility wrappers after the modular package refactor.

Model behavior is unchanged. No models are retrained, no thresholds are changed, and artifact paths/checkpoint formats remain the same.

Removed Legacy Wrappers

• src/model.py
• src/model_bert.py
• src/baseline.py
• src/train.py
• src/train_bert.py
• src/dataset.py
• src/dataset_bert.py
• src/parser.py
• src/preprocess.py
• src/features.py
• src/app_service.py
• src/evaluate.py
• src/inference.py

Package __init__.py public APIs remain in place, especially src/inference/__init__.py and src/evaluation/__init__.py.

Canonical Commands

python -m src.training.baseline
python -m src.training.bilstm
python -m src.training.bert
python -m src.evaluation.runner
streamlit run app.py

Validation

.venv/bin/python3 -m pytest tests/ -q -m "not slow"
# 194 passed, 5 deselected

ReviewPulse v2.2.0 — Modular Package Refactor

ReviewPulse v2.2.0 — Modular Package Refactor

Release date: 2026-05-04

Summary

ReviewPulse v2.2.0 completes the modular package refactor track. The release keeps model behavior, thresholds, artifacts, output filenames, and the Streamlit app experience unchanged while moving major responsibilities out of legacy flat modules.

The public compatibility surface remains intact: existing commands such as python -m src.evaluate, python -m src.train, python -m src.train_bert, and imports from src.inference continue to work.

Highlights

• Split data concerns into src.data:
  • src/data/parser.py
  • src/data/preprocess.py
  • src/data/features.py
• Split tokenization concerns into src.tokenization:
  • src/tokenization/vocab.py
  • src/tokenization/sequence.py
  • src/tokenization/bert.py
• Split model definitions into src.models:
  • src/models/baseline.py
  • src/models/bilstm.py
  • src/models/bert.py
• Split training orchestration into src.training:
  • src/training/baseline.py
  • src/training/bilstm.py
  • src/training/bert.py
• Split single-text inference into src.inference:
  • src/inference/loaders.py
  • src/inference/predictors.py
  • src/inference/registry.py
  • src/inference/api.py
• Split batch evaluation into src.evaluation:
  • src/evaluation/metrics.py
  • src/evaluation/plots.py
  • src/evaluation/errors.py
  • src/evaluation/bilstm.py
  • src/evaluation/bert.py
  • src/evaluation/runner.py
• Moved Streamlit service helpers to src/app/service.py.
• Added or preserved compatibility wrappers for legacy import paths and CLI commands.
• Updated submission checklist, README, and architecture documentation for the final modular layout.

Compatibility Wrappers Kept

The following wrappers remain to protect older imports and commands:

• src/evaluate.py wraps src.evaluation and remains compatible with python -m src.evaluate.
• src/inference.py and src/inference/__init__.py preserve the existing src.inference API.
• src/baseline.py wraps src.training.baseline.
• src/train.py wraps src.training.bilstm.
• src/train_bert.py wraps src.training.bert.
• src/parser.py wraps src.data.parser.
• src/preprocess.py wraps src.data.preprocess.
• src/features.py wraps src.data.features.
• src/dataset.py and src/dataset_bert.py preserve legacy tokenization imports.
• src/model.py and src/model_bert.py preserve legacy model imports.
• src/app_service.py wraps src.app.service.

Behavior And Artifact Guarantees

No retraining is required from v2.1.0 to v2.2.0.

Unchanged:

• Prediction threshold: 0.5
• App command: streamlit run app.py
• Baseline artifact: outputs/baseline.joblib
• BiLSTM checkpoint: outputs/bilstm.pt
• Vocabulary artifact: outputs/vocab.json
• DistilBERT checkpoint: outputs/distilbert.pt
• Evaluation output filenames under outputs/
• Existing model metrics and checkpoint formats

DistilBERT remains integrated in the app. The only open DistilBERT deployment item is external checkpoint hosting, tracked in Issue #28.

Validation

Latest verified fast suite:

.venv/bin/python3 -m pytest tests/ -q -m "not slow"
# 204 passed, 5 deselected

Issue-specific validation was run during the modular refactor PRs:

.venv/bin/python3 -m pytest tests/test_inference.py tests/test_boundaries.py -q
.venv/bin/python3 -m pytest tests/test_evaluate.py tests/test_boundaries.py -q

Warnings observed locally:

• UndefinedMetricWarning in small mocked DistilBERT evaluation tests where one class has no predicted samples.
• PytestCacheWarning because .pytest_cache was not writable in the local execution environment.

Both warnings are non-blocking and unrelated to app behavior.

Related Pull Requests

• #61 — data module refactor
• #62 — tokenization module refactor
• #63 — training package refactor
• #64 — tests migrated to new import paths
• #66 — inference package refactor
• #67 — evaluation package refactor
• #65 — final submission checklist

Known Follow-Ups

• Issue #28: host large model checkpoints outside git for deployment.
• Issue #59: remove compatibility wrappers when all consumers have moved to package-native imports.

ReviewPulse v2.1.0 - Refactor Track

ReviewPulse v2.1.0 — Refactor Track

Release date: 2026-05-02

Summary

ReviewPulse v2.1.0 is the maintainability release after the v2.0.0 DistilBERT milestone.

The application behavior remains the same: users can compare TF-IDF + Logistic Regression, BiLSTM + GloVe, and DistilBERT from the Streamlit interface. The main change is architectural: the codebase now has clearer boundaries around config, inference, evaluation, DistilBERT checkpointing, app loading, documentation, and tests.

Highlights

• Completed the #30-#39 refactor track.
• Centralized shared constants in src/config.py.
• Introduced predictor classes and registry-based inference dispatch in src/inference.py.
• Added runtime predictor registration for future models.
• Separated evaluation metric computation from PNG/CSV artifact writing.
• Added compute_metrics() as a pure evaluation helper.
• Split DistilBERT support into:
  • src/dataset_bert.py
  • src/checkpoint_bert.py
  • src/train_bert.py
• Moved Streamlit model loading and availability logic into src/app_service.py.
• Moved demo samples into src/utils/samples.py.
• Added model artifact policy and DistilBERT model-card notes to docs/architecture.md.
• Added config contract tests and module boundary tests.

Documentation Reorganization

Documentation was reorganized to make the project history easier to follow:

File	Purpose
docs/issueBreakdown-phase1.md	Original assessment delivery: setup through app/report/presentation
docs/issueBreakdown-phase2.md	Completed refactor track: Issues #30-#39
docs/issueBreakdown-phase3.md	Proposed modular package refactor plan
docs/assessment-files/	Presentation outline, individual report template, and demo test cases
docs/architecture.md	Current system architecture, artifact policy, and model-card notes

The README was updated to match the current module layout, test counts, artifact policy, and app capabilities.

Validation

Validated on 2026-05-02:

pytest tests/ -q -m "not slow"
# 189 passed, 5 deselected

pytest tests/
# 194 passed

Warnings observed:

• UndefinedMetricWarning in small mocked DistilBERT evaluation tests where one class has no predicted samples.
• PytestCacheWarning because the local .pytest_cache directory is not writable in this environment.

Both warnings are non-blocking and unrelated to deployed app behavior.

Architecture State

The code is substantially cleaner than v2.0.0:

• app.py is now mostly UI.
• src/app_service.py owns Streamlit model loading and availability policy.
• src/inference.py owns single-text prediction and model registry behavior.
• src/evaluate.py owns batch metrics, plots, and error analysis.
• src/checkpoint_bert.py owns DistilBERT checkpoint save/load behavior.
• src/dataset_bert.py owns DistilBERT tokenizer and DataLoader helpers.
• src/config.py owns shared constants.

The remaining architectural debt is package organization: src/ is still flat. The next proposed refactor is documented in docs/issueBreakdown-phase3.md.

Known Follow-Ups

• Issue #28 remains open for hosting outputs/distilbert.pt outside git.
• Issue #20 remains open if the final submission package/checklist still needs to be created.
• Issue #21 remains open even though DistilBERT functionality has landed; decide whether to close it as completed or keep it as a broader transformer tracking issue.

Upgrade Notes

No retraining is required from v2.0.0 to v2.1.0.

Existing commands still work:

python -m src.baseline
python -m src.train
python -m src.train_bert
python -m src.evaluate
streamlit run app.py
pytest tests/

ReviewPulse v2.0.0 — DistilBERT Extension

ReviewPulse v2.0.0 — DistilBERT Extension

Release date: 2026-04-29

Summary

ReviewPulse v2.0.0 adds a Hugging Face DistilBERT sentiment classifier as a third model option alongside the v1.0.0 baseline and BiLSTM. The pretrained transformer clears both v1 models by a meaningful margin on the held-out test set and is live in the Streamlit app.

This release covers Issues #21–#27 and PR #22 (implemented by Victor Meneses, hardened by Luis Faria).

What Shipped

• Hugging Face distilbert-base-uncased wrapper (src/model_bert.py) with frozen-encoder default and partial unfreezing support.
• Full fine-tuning pipeline (src/train_bert.py): head-first training, partial encoder unfreezing for the last 2 layers, Adam with BCEWithLogitsLoss, ReduceLROnPlateau, and checkpoint serialisation to outputs/distilbert.pt.
• DistilBERT evaluation path in src/evaluate.py with confusion matrix and error analysis outputs.
• predict_distilbert() wired into src/inference.py as model_name="distilbert".
• Streamlit app updated with DistilBERT as a third model option; graceful unavailable state if checkpoint or dependency is missing.
• pytest.importorskip("transformers") guards on BERT-specific test files so baseline/BiLSTM tests run cleanly without the optional dependency.
• Updated presentation outline, individual report template, and docs/issueBreakdown.md to reflect v2.0.0 results.

Model Results

All results on the held-out test split (1,159 reviews, seed=42):

Model	Accuracy	F1	Misclassified
TF-IDF + Logistic Regression	82.7%	81.9%	201
BiLSTM + GloVe	81.0%	80.3%	220
DistilBERT	88.2%	88.6%	137

Validation result:

Model	Best validation F1	Best epoch
DistilBERT	87.8%	12

DistilBERT is available in the app but not the default model — the TF-IDF baseline remains the default because it is faster, has no optional dependency, and its held-out behaviour is well understood. DistilBERT is selectable and degrades gracefully if unavailable.

Application Experience

The Streamlit app now offers three model options:

• TF-IDF + Logistic Regression (default) — fastest, no GPU, best understood
• BiLSTM + GloVe — neural model satisfying the rubric architecture requirement
• DistilBERT — highest accuracy; requires transformers and outputs/distilbert.pt

If DistilBERT fails to load, the app shows a clear warning and keeps baseline/BiLSTM available.

Test Coverage

Scope	Fast tests	Slow integration
v1.0.0 (baseline, BiLSTM, parser, preprocess, dataset, inference, evaluate)	120	5
v2.0.0 BERT (model_bert, train_bert)	23	0
Total	143	5

Fast test command:

pytest tests/ -q -m "not slow"

BERT tests are skipped automatically when transformers is absent.

Known Limitations

• DistilBERT confidence is uncalibrated — 95% confidence does not imply 95% accuracy. Platt scaling is the recommended next step.
• Negation and sarcasm remain partially handled; DistilBERT is better than v1 models but not robust.
• The checkpoint (outputs/distilbert.pt, ~29 MB) is committed to the repository for now. Long-term hosting on the luisfaria webserver is tracked in Issue #28.
• The dataset is from 2007; modern review language, emoji, and slang are not represented in training.

Issue Coverage

• Issue #21: DistilBERT implementation (Victor Meneses, PR #22).
• Issue #23: BERT test guard with pytest.importorskip.
• Issue #24: Graceful DistilBERT loading failure in Streamlit app.
• Issue #25: Verified metrics — confirmed test F1 88.6% from held-out evaluation.
• Issue #26: Training/evaluation implementation cleanup (dead params, device consistency, exception narrowing).
• Issue #27: Presentation outline, individual report template, and issueBreakdown updated with v2.0.0 evidence.

Next Milestone

• Issue #28: host outputs/distilbert.pt on the luisfaria webserver to move the binary out of git long-term.
• Issue #29: v2.0.0 GitHub release tag, changelog, and submission packaging.
• Future: RoBERTa benchmarking (v2.1.0), confidence calibration, LIME explainability.

ReviewPulse v1.0.0 - Assessment-Ready Baseline + BiLSTM

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.