SRL-aware-SEPF

SRL-aware-SEPF: Single-Sentence Inference Plugins

Ready-to-run plugins that detect four communication signals from a single sentence: Sentiment, Emotion, Politeness, and Formality (SEPF), using SRL-aware BERT models (role-attention with gated fusion). Each plugin bundles the trained checkpoint with a self-contained script and notebook, and can optionally generate an LLM-based explanation of the prediction.

Training code lives on GitHub: https://github.com/philz0918/SRL-gated-fusion-SEPF The underlying SRL predictor is at yeomtong/srl_bert_model and is downloaded automatically at runtime.

Repository structure

srl_common.py                          # shared: SRL init, data structures, helpers
External cues/
    politeness_formality_common.py     # shared text->SRL processing for this pair
    srl-aware-politeness-plugin/       # checkpoint + script + notebook
    srl-aware-formality-plugin/
Internal states/
    emotion_sentiment_common.py        # shared datasets/collate for this pair
    srl-aware-emotion-plugin/          # + emotions.txt (28 GoEmotions labels)
    srl-aware-sentiment-plugin/        # + sentiments.txt (4 labels)

Keep this folder structure intact: each plugin script loads its checkpoint from its own folder and imports the shared modules from the parent folders.

Quickstart

git clone https://huggingface.co/yeomtong/SRL-aware-SEPF
cd "SRL-aware-SEPF/Internal states/srl-aware-emotion-plugin"
python Emotion_single_sentence.py

Or import it in your own code:

from Emotion_single_sentence import predict_emotion
result = predict_emotion("I got 100 on the exam")

Each task works the same way, from its own plugin folder:

from Sentiment_single_sentence import predict_sentiment   # Internal states/srl-aware-sentiment-plugin
from Politeness_single_sentence import predict_politeness # External cues/srl-aware-politeness-plugin
from Formality_single_sentence import predict_formality   # External cues/srl-aware-formality-plugin

Results include the predicted label(s) and the SRL frame descriptions that informed the model (for sentiment, also a continuous score from -1 to +1). On first run, the SRL predictor (~1 GB) is downloaded automatically from the Hub; a GPU is recommended but not required.

LLM explanations (optional)

Each script contains an explanation function that turns a prediction into a short natural-language rationale via an OpenAI-compatible API. Set your credentials in the __main__ block:

client = OpenAI(
    api_key="enter-your-api-key",
    base_url="enter-your-base-url",
)

Requirements

torch  transformers  huggingface_hub  scikit-learn  scipy
pandas  numpy  tqdm  openai
spacy                    # politeness / formality only

For politeness and formality, also run: python -m spacy download en_core_web_md

Models

Each plugin ships the best-performing variant for its task from our fusion vs. no-fusion comparison (six configurations per task, trained against vanilla BERT baselines). Gated fusion was the strongest architecture for emotion, politeness, and formality; for sentiment, the no-fusion (concatenation) variant performed best, showing that while gated fusion is generally the most effective way to integrate SRL information, the optimal integration strategy can differ by task.