feat: Human-Readable Emotion Analysis Summary Generator

[cc-fuyu]

Summary

This PR adds a human-readable summary generator that converts raw emotion analysis percentages into natural-language text. It directly addresses the "Human-Readable Report Summaries" key feature of the GSoC 2026 project "Sentiment and Emotion Output Standardization for Usability Reports".

Problem

The current API returns only numerical percentages (e.g., {"Happy": 35.0, "Sad": 10.0, ...}). While precise, these raw numbers require interpretation effort from non-technical stakeholders such as UX researchers, designers, and product managers.

Changes

New Module: services/report/summary_generator.py

A pure-Python module (no external dependencies) that provides:

Component	Description
EmotionBreakdown	Dataclass wrapping emotion percentages with computed properties: dominant_emotion, positive_total, negative_total, neutral_total, top_n()
_sentiment_label()	Classifies overall sentiment as Positive / Negative / Mixed / Neutral (with "Mostly" variants)
_top_emotions_sentence()	Builds a grammatically correct sentence listing the top 3 emotions
_ux_insight()	Generates a brief UX-oriented interpretation based on the dominant emotion
generate_summary()	Main entry point returning a dict with overall_sentiment, top_emotions, ux_insight, and full_summary

New Endpoint: POST /process_video_summary

Returns both raw emotion percentages and the generated summary in a single response.

Example Response

{
  "emotions": {"Happy": 55.0, "Neutral": 20.0, "Surprised": 10.0, ...},
  "summary": {
    "overall_sentiment": "Mostly Positive",
    "top_emotions": "The top emotions were happiness (55.0%), neutral affect (20.0%), and surprise (10.0%).",
    "ux_insight": "The overall emotional response was positive, suggesting that users found the experience engaging or satisfying.",
    "full_summary": "Analysis of \"session_42.webm\": The overall emotional sentiment is **Mostly Positive**. The top emotions were happiness (55.0%), neutral affect (20.0%), and surprise (10.0%). The overall emotional response was positive, suggesting that users found the experience engaging or satisfying."
  }
}

Unit Tests: tests/test_summary_generator.py

15 tests covering:

• EmotionBreakdown computed properties
• Sentiment label classification for positive, negative, neutral, and mixed profiles
• Full summary generation with and without video names
• Edge case: all-zero emotion percentages

All tests pass: 15 passed in 0.04s

Backward Compatibility

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