Resonance â€” Emotional Intelligence Layer for LLMs

resonance-layer sits between your users and your LLM. It reads the emotion behind what someone writes and injects that context before the LLM responds.

from resonance import Resonance

r = Resonance(user_id="your-user-id")
context = r.process("I've been so anxious about this")
llm.chat(system=context.to_prompt(), message=message)

That's it. The LLM now knows the emotional state, psychological signals, and longitudinal pattern for this user â€” before it says a word.

The problem this solves

Text doesn't carry emotion. When someone types "I'm fine" or "whatever, doesn't matter" â€” the LLM sees words. It has no idea if that person is exhausted, shutting down, or genuinely okay.

Resonance gives it that context, continuously, per user, without any extra effort from the developer or the user.

What this model detects

This is a custom 86M parameter student model distilled from three specialist teachers, trained on real human emotional expression across 29 datasets (~740K rows).

18 output heads across 4 groups:

Group	Heads
Core	Primary emotion (7-class), VAD continuous, CNN local patterns, confidence calibration
Frameworks	Secondary emotion (21-class TONE), PERMA Ã--5, Window of Tolerance, reappraisal/suppression, Wise Mind
Ethics	Crisis detection, alexithymia screening
SDT	Autonomy, competence, relatedness

All framework scores are continuous outputs, not binary flags â€” grounded in the clinical research each framework comes from.

What makes it different from general emotion models:

The three specialist teachers each cover a distinct psychological blind spot:

T1 (DeBERTa-v3-large + CNN): shame/guilt separation with PoliGuilt typing â€” the distinction most models collapse or miss entirely
T2 (XLNet-large): anger and complex social context
T3 (ELECTRA-large): fear, PERMA wellbeing, and efficiency

Installation

pip install resonance-layer

Weights download automatically on first use (~700MB). Fully local after that â€” no API call, no data leaving your infrastructure.

Quick start

from resonance import Resonance

r = Resonance(user_id="alice")
result = r.process("I keep second-guessing everything I do")

print(result.primary_emotion)        # e.g. "anxiety"
print(result.vad)                    # valence, arousal, dominance
print(result.perma)                  # PERMA scores across 5 dimensions
print(result.crisis_detected)        # always check this first
print(result.to_prompt())            # ready-made system prompt context

If crisis_detected is True, surface a crisis resource immediately. This is non-negotiable â€” it's in the ethics documentation and built into the API contract.

Longitudinal learning

Resonance learns in two ways per user:

Passive â€” every call to r.process() updates the user's local profile. Patterns, suppression signals, regulation style â€” all accumulate silently. The LLM gets richer context with every conversation.
Active â€” explicit corrections (e.g. a user tapping a different emotion chip) feed directly into per-user reinforcement and adjust future detections for them specifically.

Both paths are local. No opt-in required.

Upgrading from v1

pip install --upgrade resonance-layer

No API changes. Drop-in replacement.

Honest limitations

Shame F1 is the lowest of any class â€” it's the hardest psychological distinction to learn
Sadness is weaker than anger, fear, and joy
Some high-arousal distress returns as surprise
All gaps are documented in the repo

Architecture

Student: 86M parameter DeBERTa-v3-base, 18 active heads
Teachers: DeBERTa-v3-large+CNN (T1), XLNet-large (T2), ELECTRA-large (T3)
Distillation: Multi-teacher knowledge distillation with per-head weighting, mutual information maximisation, born-again networks, uncertainty-aware loss
Training data: 29 datasets, ~740K rows, 7 locked dataset rules (commercial licence, institutional/peer-reviewed, real human expression, framework-mapped, not too narrow, no gated access, no severe class imbalance)

wpferrell
/

resonance-model