README.md

metadata

title: Entity Sentiment Classification
emoji: 📊
colorFrom: blue
colorTo: indigo
sdk: docker
app_port: 7860
pinned: false

Entity Sentiment Classification

Classify sentiment (positive, neutral, negative) for named entities in news article text using fine-tuned DistilBERT models.

Three classification modes:

• marker — entity wrapped in [E]...[/E] special tokens, single-sequence input
• qa_m — question-answering multi-class: "What do you think of the sentiment of {entity}?"
• qa_b — question-answering binary: three hypotheses per entity, argmax of P(yes)

Plus a fastText baseline using marker-mode text.

Report: report.pdf.

Live demo: https://huggingface.co/spaces/lamossta/entity-sentiment-classification

Logs: https://telemetry.betterstack.com/team/t529434/tail?s=2383648

Setup

1. Environment Variables

Create a .env file in the project root:

HF_TOKEN=<your huggingface token> (not needed for the inference)
BETTERSTACK_SOURCE_TOKEN=<your betterstack token>

2. Run

docker compose up

This will install dependencies, download models from HuggingFace, and start the backend and frontend. Everything is accessible on port 7860:

• Frontend: http://localhost:7860
• API: http://localhost:7860/api/

API Endpoints

Endpoint	Method	Description
/predict	POST	Classify entities using the marker model
/predict-all-models	POST	Classify entities using all available models
/health	GET	Health check
/docs	GET	Interactive Swagger UI API docs

Sending Requests

Request Format

[
  {
    "id": 0,
    "text": "Google had solid Q4 2025 earnings but Microsoft's were not great.",
    "entities": [
      {
        "entity_id": 0,
        "entity_text": "Google",
        "entity_type": "company",
        "positions": [
          {"position_text": "Google", "length": 6, "offset": 0}
        ]
      },
      {
        "entity_id": 1,
        "entity_text": "Microsoft",
        "entity_type": "company",
        "positions": [
          {"position_text": "Microsoft", "length": 9, "offset": 40}
        ]
      }
    ]
  }
]

Response Format

[
  {
    "id": 0,
    "entities": [
      {"entity_id": 0, "entity_text": "Google", "classification": "positive"},
      {"entity_id": 1, "entity_text": "Microsoft", "classification": "negative"}
    ]
  }
]

Local

curl -X POST http://localhost:7860/api/predict \
  -H "Content-Type: application/json" \
  -d @sample_input.json

curl -X POST http://localhost:7860/api/predict-all-models \
  -H "Content-Type: application/json" \
  -d @sample_input.json

HuggingFace Spaces

curl -X POST https://<your-space>.hf.space/predict \
  -H "Content-Type: application/json" \
  -d @sample_input.json

curl -X POST https://<your-space>.hf.space/predict-all-models \
  -H "Content-Type: application/json" \
  -d @sample_input.json

Notebooks

• notebooks/data_preprocessing_analysis.ipynb — data hygiene checks on data/data_raw.json
• notebooks/data_augmentation_analysis.ipynb — article length + label distribution analysis
• notebooks/data_splits_analysis.ipynb — train/val/test splitting strategy
• notebooks/train_marker.ipynb — fine-tunes marker mode
• notebooks/train_qa_m.ipynb — fine-tunes QA-M mode
• notebooks/train_qa_b.ipynb — fine-tunes QA-B mode
• notebooks/train_fasttext.ipynb — trains fastText baseline