Twitter Sentiment Analysis

This project trains a three-class sentiment classifier for tweets about a named entity. It predicts Positive, Negative, or Neutral. The dataset's Irrelevant label is deliberately mapped to Neutral, following the project brief.

Approach

• Cleans tweet text: lowercases it, replaces links and user handles with stable tokens, and keeps hashtags and punctuation that may carry sentiment.
• Adds a weighted entity-context token because the task asks for sentiment about an entity; this helps tweets that refer to several brands or games.
• Transforms text with both word 1–2 gram TF-IDF and character 3–5 gram TF-IDF. Character features help with spelling variants, emoji-adjacent punctuation, and informal social-media language.
• Trains a linear support-vector classifier and evaluates top-1 accuracy on the supplied validation CSV.

Run

Create an environment and install the dependencies (if needed):

python3 -m pip install -r requirements.txt

Train and evaluate with the included Kaggle CSV files:

python3 train.py

The command prints validation accuracy, per-class precision/recall/F1, and a confusion matrix. It also writes:

• models/sentiment_tfidf_svm.joblib — trained scikit-learn pipeline
• outputs/validation_predictions.csv — actual and predicted validation labels

With the supplied files, the current model obtains 99.00% validation accuracy (990 / 1,000). This split contains closely related tweet variants, so treat this as the score on the provided split rather than a guarantee of performance on unrelated, newly collected tweets.

Paths can be overridden for another dataset split:

python3 train.py --train path/to/train.csv --validation path/to/validation.csv

Real-time API

Train the model first, then start the API:

uvicorn api:app --reload

Once the startup log says Application startup complete, navigate to one of these local URLs:

• Swagger UI (interactive API) — send and test requests directly from the browser.
• OpenAPI schema (JSON) — the machine- readable API specification for tools such as Postman or client generators.
• ReDoc (reference documentation) — a read-only API reference.
• Health check — confirms the model is loaded.

The base address, http://127.0.0.1:8000/, intentionally has no route and will return 404 Not Found; use one of the URLs above instead.

Use POST /predict for one tweet:

curl -X POST http://127.0.0.1:8000/predict \
  -H 'Content-Type: application/json' \
  -d '{"tweet":"Borderlands is fantastic!", "entity":"Borderlands"}'

For several tweets, use POST /predict/batch (up to 100 per request):

{
  "tweets": [
    {"tweet": "The latest update is great!", "entity": "Xbox"},
    {"tweet": "This keeps crashing.", "entity": "Xbox"}
  ]
}

Each result contains sentiment and decision_margin. The margin is the linear classifier's separation between its top two classes, not a calibrated probability. entity is optional but recommended, since the model is trained to assess sentiment about a particular entity. Set SENTIMENT_MODEL_PATH to load a model stored outside the default models/ directory.

Dataset format

The supplied CSV files are headerless, with these fields:

tweet_id, entity, sentiment, tweet_text

Blank tweets are excluded from training because there is no text to classify.