feat(schema): add FacialEmotionOutput for multimodal engine integration

[Kunal-Somani]

Summary

The facial-sentiment-analysis-api and sentiment-analysis-api currently have no shared contract — the facial API returns a
GetEmotionPercentagesResponse Pydantic model but there is no standardized way to convert that into the format the MultimodalSentimentEngine expects.

This PR adds that conversion layer.

New File — schemas/multimodal_output_schema.py

FacialEmotionOutput is a Pydantic wrapper around
GetEmotionPercentagesResponse that exposes two conversion methods:

from_response(response)
Converts a GetEmotionPercentagesResponse into a validated FacialEmotionOutput with field-level range constraints (0.0–100.0 per emotion). Fails fast on out-of-range values rather than silently passing bad data downstream.

to_multimodal_dict()
Produces the {emotion_label: percentage} dict format expected by MultimodalSentimentEngine.analyze(facial_emotions=...) in the sentiment-analysis-api repo (PR #39).

dominant_emotion()
Returns (label, percentage) for the highest-scoring emotion — useful for logging and single-label summaries without reimplementing max() at every call site.

Integration Boundary

facial-sentiment-analysis-api
        |
        | GetEmotionPercentagesResponse
        v
FacialEmotionOutput.from_response()
        |
        | .to_multimodal_dict()
        v
MultimodalSentimentEngine.analyze(facial_emotions={...})
        |
        | fused prediction
        v
sentiment-analysis-api /multimodal/analyze (PR #39)

Example

from schemas.multimodal_output_schema import FacialEmotionOutput

response = emotion_analysis_service.get_emotion_percentages(video_path)
output = FacialEmotionOutput.from_response(response)

# Ready for MultimodalSentimentEngine 
facial_dict = output.to_multimodal_dict()
# {'Angry': 2.5, 'Happy': 61.3, 'Neutral': 28.0, ...}

label, pct = output.dominant_emotion()
# ('Happy', 61.3)

Relation to GSoC 2026

This is the integration boundary between both RUXAILAB sentiment repos for the Multimodal Sentiment Analysis Engine project. PR #21 and #22 established consistent logging across both repos. This PR establishes the data contract between them.