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.

Plugin	Architecture	Checkpoint
Emotion	SRL role-attention, gated fusion, no MLP (ARG1 + ARGM + PRED)	28 GoEmotions labels
Sentiment	SRL role-attention, no fusion, no MLP (ARGM + PRED)	4 labels
Politeness	Directional SRL (ARG0 → ARG1), gated fusion, no MLP	score 0–4
Formality	Directional SRL, gated fusion, no MLP	binary