feat: Emotion Intensity Metrics (Valence, Arousal, Diversity Index)

[cc-fuyu]

Summary

This PR introduces emotion intensity metrics that compute derived quantitative indicators from raw emotion percentages. It directly addresses the "Confidence and Intensity Metrics" key feature of the GSoC 2026 project "Sentiment and Emotion Output Standardization for Usability Reports".

Problem

The current API returns only flat emotion percentages. While useful, they lack higher-level quantitative indicators that UX researchers need for comparative analysis across sessions, such as "Was this session more emotionally positive than the last?" or "How diverse were the user's emotions?"

Changes

New Module: services/metrics/emotion_intensity.py

A pure-Python module (only uses math from stdlib) that computes:

Metric	Range	Description
valence_score	[-1, +1]	Weighted emotional valence: positive values indicate positive emotions dominate, negative values indicate negative emotions dominate
arousal_score	[0, 1]	Emotional activation level based on psychological arousal mappings (e.g., Angry/Surprised = high arousal, Neutral/Sad = low)
diversity_index	[0, 1]	Shannon entropy-based measure of how spread out emotions are (0 = single emotion, 1 = perfectly uniform)
dominant_emotion	string	The emotion with the highest percentage
dominant_percentage	[0, 100]	Percentage of the dominant emotion
dominance_ratio	[1, inf)	Ratio of dominant emotion to runner-up (higher = more clearly dominant)
interpretation	string	Brief human-readable explanation of the metrics

Psychological Basis

The valence and arousal weights are based on the circumplex model of affect (Russell, 1980):

VALENCE_WEIGHTS = {
    "Happy": 1.0, "Surprised": 0.3, "Neutral": 0.0,
    "Sad": -0.7, "Fearful": -0.8, "Angry": -0.9, "Disgusted": -0.85,
}
AROUSAL_WEIGHTS = {
    "Happy": 0.7, "Surprised": 0.9, "Neutral": 0.1,
    "Sad": 0.3, "Fearful": 0.8, "Angry": 0.9, "Disgusted": 0.6,
}

New Endpoint: POST /process_video_metrics

Returns both raw emotion percentages and computed intensity metrics.

Example Response

{
  "emotions": {"Happy": 60.0, "Neutral": 15.0, "Surprised": 10.0, ...},
  "intensity_metrics": {
    "valence_score": 0.4825,
    "arousal_score": 0.5830,
    "diversity_index": 0.7123,
    "dominant_emotion": "Happy",
    "dominant_percentage": 60.0,
    "dominance_ratio": 4.0,
    "interpretation": "The emotional response is predominantly positive. Emotional activation was moderate. There was moderate emotional diversity across the session."
  }
}

Unit Tests: tests/test_emotion_intensity.py

20 tests covering:

• Percentage normalization
• Valence computation (positive/negative/bounded/single emotion)
• Arousal computation (bounded, high-arousal emotions)
• Diversity index (uniform/single/bounded)
• Dominance ratio (clear dominant, single emotion edge case)
• Full metrics computation (type, dict keys, interpretation, edge cases)

All tests pass: 20 passed in 0.05s

Backward Compatibility

The original /process_video endpoint is not modified. The new /process_video_metrics endpoint is purely additive.